Files

T

boos 79ade45c25 docs: LTX2.3 数字人 spec 补充 media.py image_path 转发缺口

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>

2026-06-18 02:17:12 +08:00

4.9 KiB

Raw Blame History

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(带音频说话视频), 正好匹配数字人。

已确认决策

用官方模板 video_ltx2_3_id_lora(LTX2.3),不自拼 InfiniteTalk(官方模板天然 Comfy-Cloud 兼容、模型已托管、风险低)。
接入方式:comfy 通道 + 节点图注入(放 comfy/digital_ltx2.json,经适配器),不走 RunningHub、不另做独立入口。
comfykit 注入机制:节点 _meta.title 标记($~image! / $~audio! / $prompt!)。
分支 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:

LoadImage 节点 → _meta.title = "$~image_path!"(必填、媒体上传;键名对齐 media.py 转发的 image_path)
LoadAudio 节点 → _meta.title = "$~audio_path!"(键名对齐 api_video_params 注入的 audio_path)
文本提示节点(PrimitiveStringMultiline / CLIPTextEncode)→ _meta.title = "$prompt!"(对齐 media.py 的 prompt)
SaveVideo 已知输出节点,自动识别,不标记
删除 RecordAudio 节点(UI 录音交互,服务端不需要)
成品写 data/workflows/comfy/digital_ltx2.json(宿主持久化,经 ./data 挂载)
键名以 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 仓库内;若需纳入版本管理另议。

4.9 KiB Raw Blame History