# 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 仓库内;若需纳入版本管理另议。