boos
30b7b12682
调查确认 BoosAPI 数字人 UI 无视频工作流入口、后端不转发 api_video_workflow、 Pixelle 仅给 api/ 通道注入 audio_path。设计贯穿三层补齐: 前端加视频工作流选择器 + 后端转发 api_video_workflow + Pixelle 给 comfy 工作流注入 audio_path。 Co-Authored-By: Claude <noreply@anthropic.com>
94 lines
4.8 KiB
Markdown
94 lines
4.8 KiB
Markdown
# 数字人接入 Comfy Cloud 视频工作流(完整视频入口)设计
|
|
|
|
日期:2026-06-18
|
|
分支:`feat/comfy-cloud-adapter`
|
|
状态:已通过调查,待用户复审
|
|
|
|
## 背景
|
|
|
|
LTX2.3 说话头像工作流(`comfy/video_digital_ltx2.json`)已就绪并通过 Comfy Cloud 校验
|
|
(节点+模型全兼容,probe `node_errors:{}`)。但 BoosAPI 数字人 UI 没有「视频/动画工作流」
|
|
入口,无法触发「肖像图 + 旁白音频 → 说话视频」这一步。本设计补齐贯穿三层的入口。
|
|
|
|
## 现状(调查结论)
|
|
|
|
- **BoosAPI 数字人前端 `src/web/pages/DigitalHuman.tsx`**:仅 3 个选择器——ttsWorkflow、
|
|
imageWorkflow(从 mediaWorkflows 选,默认含 "image" 的)、frameTemplate(HTML 模板)。
|
|
**无视频/动画工作流选择器**。流程是「生成图片 + TTS + HTML 模板合成」,不做说话头像动画。
|
|
- **BoosAPI 后端 `src/routes/digital_human.rs`** 的 `pixelle_request_body`(~line 2053):转发
|
|
text/mode/title/backend_provider/workflow_source/n_scenes/video_fps/frame_template/
|
|
template_params/prompt_prefix/bgm_*/media_workflow/tts_workflow/ref_audio。
|
|
**不转发 `api_video_workflow`**;`workflow_source` 写死 `runninghub`/`selfhost`(无 comfy)。
|
|
- **Pixelle `pixelle_video/pipelines/asset_based.py`**(~line 693):动画步读
|
|
`context.request.get("api_video_workflow")`;`audio_path` 仅当 `_get_api_workflow_info`
|
|
(查 `api_media`,只 `api/` 通道)匹配到 `audio_driven_i2v` 能力时才注入 → **comfy 工作流
|
|
拿不到 audio_path**。
|
|
- **Pixelle 工作流执行按前缀路由**:`runninghub` 走 RunningHub,其余(含 `comfy/`)走
|
|
`comfyui_url`(= BoosAPI `/comfy-cloud` 适配器)。`comfy/video_digital_ltx2.json` 已在
|
|
`/workflows/media` 列出(已加 `video_` 前缀)。
|
|
- 已完成的前置:comfy-cloud 适配器(已验证)、`comfy/video_digital_ltx2.json`(标记
|
|
image_path/audio_path/prompt,probe 通过)、media.py 转发 image_path(已打补丁)。
|
|
|
|
## 已确认决策
|
|
|
|
1. 加完整视频入口:前端选择器 + 后端转发 + Pixelle 音频注入,三层都改。
|
|
2. 视频工作流选择器列 `video_*` media 工作流(含 `comfy/video_digital_ltx2.json`)。
|
|
3. 单人肖像说话头像;不做多人。
|
|
|
|
## 三层改动设计
|
|
|
|
### 层 1:前端 `src/web/pages/DigitalHuman.tsx`
|
|
- 新增 state `apiVideoWorkflow`(默认空=不启用动画,保持现有「图片+HTML」行为向后兼容)。
|
|
- 新增「视频工作流(可选)」`<select>`:选项 = `mediaWorkflows.filter(name 含 "video")`,
|
|
含空选项「不生成视频(仅图片合成)」。
|
|
- 提交 payload 增加 `apiVideoWorkflow` 字段;draft 持久化同步。
|
|
|
|
### 层 2:BoosAPI 后端 `src/routes/digital_human.rs`
|
|
- `pixelle_request_body` 增加:
|
|
```rust
|
|
if let Some(value) = optional_string(body, &["apiVideoWorkflow", "api_video_workflow"]) {
|
|
request_body["api_video_workflow"] = json!(value);
|
|
}
|
|
```
|
|
- 若所选视频工作流以 `comfy/` 开头,确保 `workflow_source` 不会阻断(comfy 工作流靠前缀
|
|
路由,workflow_source 主要影响 media/tts 默认通道;api_video_workflow 独立按前缀执行,
|
|
无需改 workflow_source。实现时验证不冲突)。
|
|
- 可选转发 `api_video_params`(若前端给了音频驱动等参数)。本期最小化:只转发 api_video_workflow。
|
|
|
|
### 层 3:Pixelle `pixelle_video/pipelines/asset_based.py`
|
|
- 动画步注入 `audio_path` 的条件放宽:除 `api_media` 能力匹配外,**当 `api_video_workflow`
|
|
以 `comfy/` 开头时,也注入 `audio_path = frame.audio_path`**(comfy 工作流的 `$~audio_path!`
|
|
标记需要它)。最小改动:在 `audio_driven_i2v` 判断旁边加 comfy 前缀分支。
|
|
- 镜像内置文件,改后重启容器,备份到 `/opt/Pixelle-Video/patches/`。
|
|
|
|
## 数据流(目标)
|
|
|
|
```
|
|
DigitalHuman.tsx: 选 comfy/video_digital_ltx2.json (apiVideoWorkflow)
|
|
→ BoosAPI digital_human.rs: request_body.api_video_workflow
|
|
→ Pixelle /api/video/generate/async: context.request.api_video_workflow
|
|
→ asset_based.py 动画步: 注入 image_path(media.py已补)+ audio_path(本期补)+ prompt
|
|
→ media() comfy 前缀 → comfyui_url=/comfy-cloud 适配器 → Comfy Cloud LTX2.3
|
|
→ 说话视频 → 帧合成/HTML 模板 → 成片
|
|
```
|
|
|
|
## 验证
|
|
|
|
- 前端 typecheck:`npm run typecheck:web`。
|
|
- 后端构建:`cargo build -j 2`。
|
|
- Pixelle 改动:语法校验 + 重启 healthy。
|
|
- 端到端:数字人任务选 `comfy/video_digital_ltx2.json`,确认 Comfy Cloud 出现 job、
|
|
注入了 image_path+audio_path、出说话视频。
|
|
|
|
## 非目标
|
|
|
|
- 不改 comfy-cloud 适配器(已完成)。
|
|
- 不做多人对话数字人。
|
|
- 不重构数字人现有「图片+HTML 合成」路径(视频入口为可选叠加,默认不启用,向后兼容)。
|
|
- 不动 RunningHub 数字人路径。
|
|
|
|
## 提交约定
|
|
|
|
分支 `feat/comfy-cloud-adapter`。前端、BoosAPI 后端分别提交(项目内,受版本控制);
|
|
Pixelle 改动在容器内 + 备份 patches/(非本仓库)。中文 commit。
|