forked from boos/BoosAPI
boos
79ade45c25
writing-plans 阶段发现:media.py 只给 api/ 通道转发 image_path,comfy/ 通道收不到肖像图。 增加 media.py 一行级改动(非 api 分支把 image_path 加入 workflow_params), 标记名对齐为 $~image_path! / $~audio_path! / $prompt!。 Co-Authored-By: Claude <noreply@anthropic.com>
94 lines
4.9 KiB
Markdown
94 lines
4.9 KiB
Markdown
# LTX2.3 数字人工作流(Comfy Cloud)设计
|
|
|
|
日期:2026-06-18
|
|
分支:`feat/comfy-cloud-adapter`
|
|
状态:已通过 brainstorming,待落实现计划
|
|
|
|
## 背景
|
|
|
|
Pixelle 数字人(说话头像)能力原先只有 RunningHub 形态(`runninghub/digital_*.json` 是
|
|
`{"source":"runninghub","workflow_id":"..."}` 指针,非 ComfyUI 节点图,无法在 Comfy Cloud 跑)。
|
|
为让数字人走 Comfy Cloud,采用官方 ComfyUI 模板 `video_ltx2_3_id_lora`(LTX2.3 身份保持
|
|
LoRA + 音频驱动),把它做成 Pixelle 的 `comfy/` 工作流,经已建好的 comfy-cloud 适配器执行。
|
|
|
|
可行性已验证(查 Comfy Cloud `/object_info` 3548 节点 + 模型池):
|
|
- 模型齐全:`ltx-2.3-22b-dev-fp8`、`ltx-2.3-id-lora-talkvid-3k`、`gemma_3_12B_it_fp4_mixed`、
|
|
distilled LoRA 均托管;另有 `ltx-2.3-22b-ic-lora-lipdub-0.9` 口型 LoRA。
|
|
- 节点齐全:LTX2.3 音视频节点(LTXVReferenceAudio/LTXVConcatAVLatent/LTXVAudioVAEDecode 等)
|
|
全在 Comfy Cloud 节点集中。
|
|
- 模板 I/O = LoadImage(肖像)+ LoadAudio(旁白)+ 文本 → SaveVideo(带音频说话视频),
|
|
正好匹配数字人。
|
|
|
|
## 已确认决策
|
|
|
|
1. 用官方模板 `video_ltx2_3_id_lora`(LTX2.3),不自拼 InfiniteTalk(官方模板天然 Comfy-Cloud
|
|
兼容、模型已托管、风险低)。
|
|
2. 接入方式:comfy 通道 + 节点图注入(放 `comfy/digital_ltx2.json`,经适配器),不走 RunningHub、
|
|
不另做独立入口。
|
|
3. comfykit 注入机制:节点 `_meta.title` 标记(`$~image!` / `$~audio!` / `$prompt!`)。
|
|
4. 分支 `feat/comfy-cloud-adapter`(与 comfy-cloud 适配器同分支,属同一能力线)。
|
|
|
|
## 前置依赖(硬依赖)
|
|
|
|
**需要用户从 Comfy Cloud 导出 API 格式 JSON**:模板当前是 UI 格式(含 subgraph 子图),
|
|
`/api/prompt` 要求 API 格式(`{node_id:{class_type,inputs,_meta}}`)。子图必须展开。
|
|
用户操作:Comfy Cloud 网页打开模板/share → Workflow → Export (API Format) → 放服务器
|
|
(如 `/tmp/ltx2_api.json`)。服务端无法代取(需登录态)。
|
|
|
|
## Pixelle media.py 改动(writing-plans 阶段发现的必需项)
|
|
|
|
现状:`pixelle_video/services/media.py` 的 `__call__` 只把 `image_path` 转发给 `api/` 通道
|
|
(`api_media`),**comfy/ 通道的 workflow_params 不含 image_path**。`audio_path` 经 `**params`
|
|
能进 workflow_params,但肖像图进不去。所以 comfy/ 工作流收不到肖像图。
|
|
|
|
改动:在 `media.py` 的非 api/ 分支(构建 `workflow_params` 处),把 `image_path` 也加入
|
|
`workflow_params`(命名 `image_path`),使其能被 `$~image_path!` 标记注入。一行级小改,
|
|
但属 Pixelle 源码(非 BoosAPI 仓库),改在容器内 `/app/pixelle_video/services/media.py`,
|
|
并同步到宿主持久化(确认 media.py 是否在挂载卷;若在镜像内则需固化方案)。
|
|
|
|
## 架构
|
|
|
|
```
|
|
Pixelle 数字人流程
|
|
生成肖像图(image_path)+ TTS 旁白(audio_path)+ 脚本文本
|
|
│ comfykit 按 _meta.title 标记注入到 LoadImage/LoadAudio/文本节点
|
|
▼
|
|
comfy/digital_ltx2.json (API 格式 + 标记)
|
|
│ comfyui_url = http://<boosapi>/comfy-cloud
|
|
▼
|
|
Comfy Cloud /api/prompt → LTX2.3(id-lora-talkvid + 可选 lipdub)→ 带音频说话视频
|
|
▼
|
|
SaveVideo 产出 → 适配器 /view 取回 → Pixelle HTML 模板合成
|
|
```
|
|
|
|
## 工作流改造(实现步骤)
|
|
|
|
基于用户导出的 API-format JSON:
|
|
1. `LoadImage` 节点 → `_meta.title = "$~image_path!"`(必填、媒体上传;键名对齐 media.py 转发的 image_path)
|
|
2. `LoadAudio` 节点 → `_meta.title = "$~audio_path!"`(键名对齐 api_video_params 注入的 audio_path)
|
|
3. 文本提示节点(PrimitiveStringMultiline / CLIPTextEncode)→ `_meta.title = "$prompt!"`(对齐 media.py 的 prompt)
|
|
4. `SaveVideo` 已知输出节点,自动识别,不标记
|
|
5. 删除 `RecordAudio` 节点(UI 录音交互,服务端不需要)
|
|
6. 成品写 `data/workflows/comfy/digital_ltx2.json`(宿主持久化,经 `./data` 挂载)
|
|
7. 键名以 media.py 实际放入 workflow_params 的为准(image_path/audio_path/prompt),已在 writing-plans 阶段确认。
|
|
|
|
## 验证
|
|
|
|
- 校验探测:`POST /comfy-cloud/prompt`(body 为改造后 `{prompt:节点图}`)→ 期望
|
|
`node_errors:{}` + 返回 prompt_id(不跑完整数字人流程,先验证节点+模型全兼容)。
|
|
- 真实验证:Pixelle 数字人任务选 `comfy/digital_ltx2.json`,出片确认。
|
|
- 错误处理沿用适配器:节点不支持→400 透传;模型缺失→校验错误透传;执行失败→job failed。
|
|
|
|
## 非目标
|
|
|
|
- 不改 comfy-cloud 适配器代码(已完成且验证)。
|
|
- 不做多人对话(multi-speaker)数字人,先单人肖像。
|
|
- 不在 Comfy Cloud 上自训/上传新模型,只用已托管模型。
|
|
- 不做 RunningHub 数字人的迁移/替换(保留并存)。
|
|
|
|
## 提交约定
|
|
|
|
分支 `feat/comfy-cloud-adapter`,工作流文件 + 任何 Pixelle 侧配置分开提交,中文 commit。
|
|
注:工作流文件落在 Pixelle 宿主目录(`/opt/Pixelle-Video/data/workflows/comfy/`),不在
|
|
BoosAPI 仓库内;若需纳入版本管理另议。
|