docs: 数字人接入 Comfy Cloud 视频工作流(完整视频入口)设计

调查确认 BoosAPI 数字人 UI 无视频工作流入口、后端不转发 api_video_workflow、 Pixelle 仅给 api/ 通道注入 audio_path。设计贯穿三层补齐: 前端加视频工作流选择器 + 后端转发 api_video_workflow + Pixelle 给 comfy 工作流注入 audio_path。 Co-Authored-By: Claude <noreply@anthropic.com>
2026-06-18 02:48:49 +08:00
parent 937442df04
commit 30b7b12682
1 changed files with 93 additions and 0 deletions
@@ -0,0 +1,93 @@
+# 数字人接入 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。