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. 安装模块

cd ~/repos/reallife_asset
bash build.sh

2. 创建数据库表

# 执行DDL
mysql -u root -p sage < mysql.ddl.sql

3. 注册RBAC权限

cd ~/repos/sage
./py3/bin/python ~/repos/reallife_asset/scripts/load_path.py

4. 配置uapi接口（可选）

mysql -u root -p sage < ~/repos/reallife_asset/scripts/uapi_volcengine_ark.sql

5. 集成到Sage

在 app/sage.py 中添加:

from reallife_asset.init import load_reallife_asset
# 在init()中:
load_reallife_asset()

6. 重启Sage

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为异步接口，需轮询状态