yumoqing
0e5696f5da
- 支持火山方舟(Volcengine Ark)真人人像素材API - AK/SK HMAC-SHA256签名(纯stdlib实现) - 素材组合(Asset Group)管理: 创建认证、查询、删除 - 素材资产(Asset)管理: 上传、状态同步、删除 - 多供应商可扩展架构 - 完整CRUD + 前端UI + uapi SQL配置 - 12个API端点 + 6个前端页面 - 数据库表: rl_asset_group, rl_asset
142 lines
4.6 KiB
Markdown
142 lines
4.6 KiB
Markdown
# reallife_asset - 真人人像素材管理模块
|
||
|
||
Sage平台的真人人像素材管理模块，支持多供应商（火山方舟等）的真人人像素材资产（Asset Group / Asset）管理。
|
||
|
||
## 功能概述
|
||
|
||
- **真人认证**: 创建H5认证链接，终端用户完成真人认证后获取素材组合ID
|
||
- **素材上传**: 上传真人人像素材（图片/视频/音频），系统自动进行面部一致性比对
|
||
- **状态同步**: 从供应商同步素材组合和素材资产状态
|
||
- **多供应商**: 可扩展架构，当前支持火山方舟，预留可灵等供应商接口
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
reallife_asset/
|
||
├── reallife_asset/ # Python包
|
||
│ ├── __init__.py
|
||
│ ├── init.py # 模块初始化 + 业务逻辑
|
||
│ └── volcengine_client.py # 火山方舟API客户端(AK/SK签名)
|
||
├── models/ # 数据库表定义
|
||
│ ├── rl_asset_group.json # 素材组合表
|
||
│ └── rl_asset.json # 素材资产表
|
||
├── json/ # CRUD定义
|
||
│ ├── rl_asset_group_list.json
|
||
│ └── rl_asset_list.json
|
||
├── wwwroot/ # 前端
|
||
│ ├── index.ui # 模块入口
|
||
│ ├── group_manage.ui # 组合管理页
|
||
│ ├── asset_manage.ui # 资产管理页
|
||
│ ├── create_validate.ui # 创建认证页
|
||
│ ├── upload_asset.ui # 上传素材页
|
||
│ ├── sync_groups.ui # 同步页
|
||
│ └── api/ # API端点
|
||
│ ├── rl_asset_group_create.dspy
|
||
│ ├── rl_asset_group_update.dspy
|
||
│ ├── rl_asset_group_delete.dspy
|
||
│ ├── rl_asset_create.dspy
|
||
│ ├── rl_asset_update.dspy
|
||
│ ├── rl_asset_delete.dspy
|
||
│ ├── sync_asset_status.dspy
|
||
│ ├── check_validate.dspy
|
||
│ ├── sync_from_vendor.dspy
|
||
│ ├── sync_assets.dspy
|
||
│ ├── get_rl_asset_group_list.dspy
|
||
│ └── get_rl_asset_list.dspy
|
||
├── init/
|
||
│ └── data.json # 初始化编码数据
|
||
├── scripts/
|
||
│ ├── load_path.py # RBAC权限注册
|
||
│ └── uapi_volcengine_ark.sql # uapi接口SQL配置
|
||
├── pyproject.toml
|
||
├── build.sh
|
||
└── README.md
|
||
```
|
||
|
||
## 数据库表
|
||
|
||
### rl_asset_group (素材组合表)
|
||
- 记录真人认证组合，每个组合对应一个真人
|
||
- 字段: vendor, vendor_group_id, name, status, byted_token, h5_link等
|
||
|
||
### rl_asset (素材资产表)
|
||
- 记录具体素材文件，关联到组合
|
||
- 字段: vendor, vendor_asset_id, asset_type, status, url, asset_uri等
|
||
|
||
## API接口
|
||
|
||
### 火山方舟 API (通过uapi系统)
|
||
|
||
| API | 功能 | 限流 |
|
||
|-----|------|------|
|
||
| CreateVisualValidateSession | 创建H5认证页 | 3 QPS |
|
||
| GetVisualValidateResult | 获取认证结果 | 3 QPS |
|
||
| CreateAsset | 上传素材(异步) | 按权益 |
|
||
| GetAsset | 查询素材 | 100 QPS |
|
||
| ListAssets | 素材列表 | 10 QPS |
|
||
| ListAssetGroups | 组合列表 | 10 QPS |
|
||
| GetAssetGroup | 查询组合 | 10 QPS |
|
||
| UpdateAsset | 更新素材 | 10 QPS |
|
||
| UpdateAssetGroup | 更新组合 | 10 QPS |
|
||
| DeleteAsset | 删除素材 | 10 QPS |
|
||
| DeleteAssetGroup | 删除组合 | 5 QPS |
|
||
|
||
## 安装部署
|
||
|
||
### 1. 安装模块
|
||
```bash
|
||
cd ~/repos/reallife_asset
|
||
bash build.sh
|
||
```
|
||
|
||
### 2. 创建数据库表
|
||
```bash
|
||
# 执行DDL
|
||
mysql -u root -p sage < mysql.ddl.sql
|
||
```
|
||
|
||
### 3. 注册RBAC权限
|
||
```bash
|
||
cd ~/repos/sage
|
||
./py3/bin/python ~/repos/reallife_asset/scripts/load_path.py
|
||
```
|
||
|
||
### 4. 配置uapi接口（可选）
|
||
```bash
|
||
mysql -u root -p sage < ~/repos/reallife_asset/scripts/uapi_volcengine_ark.sql
|
||
```
|
||
|
||
### 5. 集成到Sage
|
||
在 `app/sage.py` 中添加:
|
||
```python
|
||
from reallife_asset.init import load_reallife_asset
|
||
# 在init()中:
|
||
load_reallife_asset()
|
||
```
|
||
|
||
### 6. 重启Sage
|
||
```bash
|
||
cd ~/repos/sage && ./stop.sh && ./start.sh
|
||
```
|
||
|
||
## 使用流程
|
||
|
||
1. **创建真人认证**: 提供回调URL和AK/SK → 获取H5认证链接
|
||
2. **终端用户认证**: 用户通过H5链接完成真人认证
|
||
3. **获取组合ID**: 认证成功后查询获取供应商端Group ID
|
||
4. **上传素材**: 向已认证的组合上传图片/视频素材
|
||
5. **同步状态**: 轮询素材处理状态直到Active
|
||
6. **使用素材**: 使用 `asset://<asset_id>` URI 进行视频生成
|
||
|
||
## 扩展新供应商
|
||
|
||
1. 在 `volcengine_client.py` 中实现新的客户端类
|
||
2. 在 `_PROVIDERS` 字典中注册
|
||
3. 添加对应的uapi SQL配置
|
||
|
||
## 技术要点
|
||
|
||
- AK/SK签名: 使用HMAC-SHA256实现火山方舟V4签名（纯stdlib，无外部依赖）
|
||
- 多租户: 所有数据按org_id隔离
|
||
- 异步处理: CreateAsset为异步接口，需轮询状态
|