qishizhe/ai-series-comfyui-handbook

Fork 0

Files

T

qishizhe 9eef175633 docs: add video route selection and verified ComfyUI workflow tutorials

2026-10-29 15:06:10 +08:00

27 KiB

Raw Permalink Blame History

15｜ComfyUI 工作流怎样搭建、验证与排错

返回知识库目录 · 先选生成路线 · 看现有工作流拆解 · 原制作手册

工作流不是把“文生图、LoRA、ControlNet、采样器、视频保存”几个节点都摆上去。它是一张有类型、有依赖、有执行条件的数据流图：输入从哪里进入，经过什么模型与处理，最后由哪个输出节点产生可取回的文件。

本章以官方基础图像链和 Wan2.2 TI2V 5B 原生模板解释搭建方法。资料与模板核查日期为 2026-10-29；节点名称、模型文件、菜单位置和默认值可能随版本变化。下列链路是教学拆解，不能代替目标服务器的节点 schema、实际模型列表和运行验收。本次没有为这些教学步骤排队生成新视频。

1. 先写任务卡，再找模板

开始连线前，先写清这七项：

项目	应该写成什么	为什么影响工作流
镜头任务	女儿接过伞，母亲松手；不是“温情大片”	决定需要验证哪段动作与关系
输入	文字、首帧、人物参考、视频、声音分别有哪些	不是有图片就一定走同一种 I2V 路线
必须锁定	人物身份、首帧构图、道具位置、动作轨迹等	决定选基础生成、参考条件还是控制模块
允许变化	镜头角度、背景、动作、风格中哪些可探索	避免为了“全锁定”叠加互相冲突的约束
输出	一段视频、帧序列、音频或带音轨容器	决定解码与保存链，不是只看预览
规模	画幅、尺寸、帧数、批量、预期时长	影响模型支持范围、显存、解码与封装
验收	接触成立、台词连续、人物未换位等	用内容标准判断流程，而非只看绿色运行状态

例如“两分钟短剧”是项目总长，不等于应寻找一个直接输出两分钟的单节点。先按分镜识别需要生成的素材，再分别选择路线，最后在剪辑里组织时长。

2. 搭建起点：先用对应版本的模板建立基线

优先顺序可以这样安排：官方对应模型模板 → 已验证的本机流程 → 可追溯的作者示例 → 从组件组合新的图。这是本手册建议的排查顺序，不代表官方模板在任意硬件上必然运行成功。

在 ComfyUI 的模板侧栏，或 Workflow → Browse Workflow Templates 一类入口，按任务和模型加载模板；模板通常附模型信息。界面名称可能不同，关键是确认模板来自哪里、适用哪个模型版本。官方文档也说明模板包含原生模型流程及部分自定义节点示例，模板包本身与核心、前端存在版本关系。官方模板说明

第一次打开后，依次做五件事：

另存一份基线。 原模板保留，实验在副本上进行，文件名包含任务与版本。
读图的主路径。 找到模型加载、条件、采样、解码和保存，沿最终输出往前追。
列出外部依赖。 哪些是模型文件，哪些是自定义节点包，哪些是图片、视频或声音。
确认节点模式。 正常、禁用、旁路不是同一回事；尤其检查可选图像输入是否真正进入执行图。
先跑原有基线，再改目标。 实际需要生成时，先用受支持的较小规模确认加载、采样、解码和保存闭环，再逐步增加负担。

不要为了“清理画布”先删除看起来不懂的采样配置、条件节点或模型补丁；它们可能正是该模型能工作的必要环节。反过来，不与最终输出存在依赖的装饰分支，也不能仅凭它出现在画布上就认定已经生效。

3. 把依赖分清：缺节点、缺模型、模型不匹配是三类问题

依赖层	例子	具体检查
Comfy Core / 前端 / 模板	核心节点实现、画布功能、官方模板包	记录各自版本；“更新了核心”不证明前端和模板同时更新
自定义节点包	特定视频封装、预处理、模型 wrapper	记录节点的 `class_type`、包来源、版本及启动导入错误
主模型	扩散模型、完整 checkpoint	文件格式、模型架构、精度、量化方式与加载节点是否匹配
文本编码器	CLIP、T5 或其他架构的编码器	与主模型及模板要求一致，不能只看接口都写 CLIP
VAE	图像或视频编码、解码器	架构、通道、压缩与时间维度是否匹配
条件模型	LoRA、ControlNet、视觉编码器等	适用的基座、版本、任务和作用范围
运行输入	首帧、参考图、音频、控制图	确实能被服务端找到，尺寸、时长和内容符合本镜

模型目录应按当前安装和 extra_model_paths.yaml 实际配置检查。常见分区包括 checkpoints、diffusion_models、text_encoders、vae、loras、controlnet、clip_vision；但本机是否看得到文件，要以相应加载节点的下拉列表或服务器返回值为准。文件下载到浏览器所在电脑，不等于已放进远程 ComfyUI 的模型目录。官方首次生成与模型安装说明

有些 checkpoint 打包多个组件，有些模型必须分开加载。CheckpointLoaderSimple 的常见输出为 MODEL、CLIP、VAE；这不意味着每个名为 checkpoint 的文件都真的提供了适用的三者。加载器能读文件、节点能连线、模型组件兼容，是三个需要分别验证的层面。

4. 先看数据类型，颜色只作辅助

节点可连接的端口有数据类型，参数控件则常是字符串、数字、下拉选项等。颜色帮助识别，但主题、插件和版本可能改变表现；判断时读取端口名称、类型与节点说明。官方节点概念

类型	可以怎样理解	常见来源 → 去向	容易弄错的地方
MODEL	可用于当前模型运算的模型对象	加载 / 模型补丁 → 引导器或采样器	不是图片，也不是模型文件名字符串
CLIP	此接口名称下的文本编码组件	编码器加载 → 文本编码	名字相同不保证不同模型家族可互换
VAE	像素与潜空间之间的编解码组件	VAE 加载 → 编码 / 解码	Wan 视频 VAE 不能当 SD 图像 VAE 随意替换
CONDITIONING	编码后的条件结构	文本编码、参考或控制条件 → 采样	不是直接把一句提示词接到采样端口
IMAGE	像素图像或图像批	加载、解码、图像处理 → 编码 / 保存 / 视频封装	在视频链中可能是帧批，不只是一张图
LATENT	潜表示及相关元数据	空潜变量、编码、采样 → 采样 / 解码	同叫 LATENT 仍可能有架构、通道与时间维差异
MASK	区域或权重信息	图片加载、分割、遮罩处理 → 对应条件或合成	不是所有黑白图片都会自动被当成正确遮罩
CONTROL_NET	控制模型对象	ControlNet 加载 → 控制条件应用	不等于骨架、深度图或轮廓图片本身
AUDIO	波形与采样率等音频数据	音频加载 / 解码 → 音频保存或视频封装	有声音输入口不表示视频模型自动会生成声音
VIDEO	某些节点使用的视频对象	帧和音轨封装、视频加载 → 视频保存	不与 IMAGE 或 AUDIO 直接等同
INT / FLOAT / STRING	数值或文字参数	控件 / 输入节点 → 指定参数	不能把输出槽编号误当成参数值

官方数据类型文档给出了 IMAGE、LATENT、AUDIO 等结构。文档中基础 SD 的潜图尺寸示例不能推广成所有视频模型的压缩比例；后续连线还需检查模型语义与实际张量形状。官方数据类型参考

转换必须有意义。 VAEEncode 可把兼容的 IMAGE 编为 LATENT，VAEDecode 执行反向过程；视频模型也可能要求专用条件节点来组织首帧、时间长度、掩码和潜变量。不要只为让线接上，就插入一个不属于该模型的转换器。

5. 第一张教学图：基础文生图闭环

下面是理解数据流的基础 SD 类示意，不是所有图像模型、更不是所有视频模型的通用配方：

CheckpointLoaderSimple
  MODEL ───────────────────────────────────┐
  CLIP ──→ CLIPTextEncode（正向文字）─────────┤
       └─→ CLIPTextEncode（负向文字）─────────┤
EmptyLatentImage（尺寸、批量）──────────────→ KSampler
                                               │ LATENT
  VAE ────────────────────────────────────→ VAEDecode
                                               │ IMAGE
                                            SaveImage

逐条检查，比从左往右随便拉线更可靠：

模型输出到采样器的 MODEL 输入。
文本编码器分别接正向与负向文本节点，再接对应的 CONDITIONING 输入。
空潜变量提供待采样的潜表示；尺寸和 batch 属于这里的生产条件。
采样器输出 LATENT，使用匹配的 VAE 解码成 IMAGE。
IMAGE 接到保存节点，确认有可取回的文件。

该链可以用于学习“模型、条件、潜变量、解码、输出”的职责，但 FLUX、其他编码架构、蒸馏模型或视频模型会有不同的加载、引导和采样方式。遇到差异先回到对应模板，不要把示意图当成强制节点清单。基础示例工作流

6. 第二张教学图：Wan2.2 TI2V 5B 的文／图双模式

Wan2.2 家族并非只有一个可任意切换的权重。官方区分 TI2V 5B、T2V A14B、I2V A14B 等任务版本；此处专门解释 TI2V 5B 原生模板，不把它的接法移植到 14B 双专家或其他 wrapper。Wan 官方仓库

6.1 加载、条件、潜变量与输出各自成链

UNETLoader ─→ ModelSamplingSD3 ─────────────────────────────┐
CLIPLoader ─→ CLIPTextEncode（正向）─────────────────────────┤
           └→ CLIPTextEncode（负向）─────────────────────────┤
VAELoader ─→ Wan22ImageToVideoLatent ──────────────────────→ KSampler
LoadImage.IMAGE → Wan22ImageToVideoLatent.start_image（可选） │
                                                          │ LATENT
VAELoader ──────────────────────────────────────────────→ VAEDecode
                                                          │ IMAGE 帧批
                                                       CreateVideo
                                                          │ VIDEO
                                                        SaveVideo

这里 ModelSamplingSD3 是该模板对模型采样配置的处理节点；节点名称不能被理解成主模型变成了 Stable Diffusion 3。Wan22ImageToVideoLatent 同时承担该模型所需的潜变量组织，不能用普通 EmptyLatentImage 随意替换。

本次读到的官方 JSON 使用 wan2.2_ti2v_5B_fp16.safetensors、umt5_xxl_fp8_e4m3fn_scaled.safetensors 与 wan2.2_vae.safetensors，并连接上述路径。文件名是该快照的依赖示例；如果使用其他精度或重新打包版本，应按其配套说明核对加载方式。官方 TI2V 5B 模板 JSON

6.2 文生与图生，真正改的是输入分支

要做的模式	输入分支怎样处理	运行前看什么
T2V：文字驱动视频	在该模板规定的方式下停用可选首帧输入，使实际执行图不携带 `start_image` 图像条件	导出的 API 图是否真的不再引用首帧；不要只看画布上有无一张图
I2V：首帧驱动视频	启用 `LoadImage`，将实际首帧接入 `Wan22ImageToVideoLatent.start_image`	图片来自哪里，尺寸与裁切怎样处理，图中初态是否能发生所需动作

官方教程提供可选图像输入的切换，并指出视频尺寸和长度在专用潜变量节点中设置。切换必须使用本模板支持的办法；不是任何 T2V 图加一个 LoadImage 就获得 I2V 能力，也不是从任意 I2V 图删掉输入便得到可用 T2V。官方 Wan2.2 教程

选择 I2V 后，首帧给出的身份、构图与初态仍需审查。手已握住伞柄，却在文字里要求先从远处走近，图和动作就会冲突；这是输入设计问题，不必先怀疑采样器坏了。

6.3 帧数、采样步数与输出帧率不是一回事

帧数 / length： 要组织多少视频帧；模型可能有特定的时间尺寸约束。
采样步数 / steps： 去噪过程的计算次数，不等于视频帧数。
输出 fps： 帧序列怎样按时间播放；随意改它会改变速度和时长，并不自动补出新的运动内容。
batch： 多个样本的批量，不能把它直接当成一个视频的时间长度。

先保留模板适用的帧数与采样安排。做小样时，在模型支持范围内缩小分辨率、时长或批量；不能把长度改成任意整数后，认为所有时序结构仍会兼容。

这个 Wan 示例的 CreateVideo 有可选 AUDIO 入口，但以上基础链没有音频生成分支，因此不能把提示词里的“雨声、说话”当成已经输出音轨。原生音画联合生成或外部音轨合成，需要不同的模型或额外的实际音频路径，见现有工作流拆解。

7. 在哪里加模块：先有问题，再加一条支路

已确认的问题	可研究的模块	它主要改变哪一层	不能指望它自动解决
需要特定风格或训练过的主体特征	兼容 LoRA	模型，部分也改编码组件	所有机位的身份、持物、空间与剧情记忆
姿态或结构偏离	对应模型支持的 ControlNet / 控制条件	采样的结构约束	肌肉受力、接触顺序及所有遮挡物理
需要参考人物或外观	模型原生参考、视觉编码或适配器	模型规定的参考条件	自动获得首帧、尾帧、3D 世界的全部约束
局部需要修复	遮罩、局部编辑或重绘	指定区域的生成与合成	与其他镜头天然连续
分辨率不足	尺寸调整、超分、分块修复	像素或潜空间处理	修正原先错误的构图和动作因果
需要更多播放帧	插帧	已有帧之间的运动估计	修好换脸、瞬移、穿模和错误手势
运行速度不足	已支持的量化、缓存、加速方案	权重、计算或采样路径	在不测试的前提下保证质量不变

后期插帧是在已有视频帧之间补过渡；首尾帧视频生成则把两张图作为生成条件，让模型生成中间内容。它们解决的问题和输入路径不同，不能混称为同一种操作。

LoRA 放在它实际修改的流上。 经典 LoraLoader 接收 MODEL 与 CLIP，再输出修改后的对象；某些模型或 LoRA 使用 model-only 路径。不能把 LoRA 文件接到文本框，也不能假定每个 LoRA 都训练过文本编码器。ComfyUI 官方节点源码

加速 LoRA 还带采样契约。 它可能要求特定模型、步数、引导与调度，不能只把文件叠上去，再沿用普通高步数设置。人物 LoRA、风格 LoRA、加速 LoRA 的目标不同；每次只加入一个已核对兼容性的变化，与基线对照。

控制图和控制模型不是同一物。 骨架、深度和轮廓是输入条件；相应控制模型或原生节点负责如何使用它们。经典 ControlNetApplyAdvanced 把控制信息应用到 CONDITIONING，不是用一张深度图直接替换采样器的 MODEL。视频模型可能采用完全不同的原生控制结构，应另找对应模板，而非照搬图像 ControlNet 支路。

8. UI JSON、API JSON 和节点编号怎样理解

文件或字段	主要用途	不能混淆的地方
UI 工作流 JSON	保留画布节点、连线、布局、控件、分组或子图定义	好看的截图不能代替它；API 图也通常不含完整布局
API 工作流 JSON	描述后端实际执行节点的 `class_type` 与 `inputs`	通常不能把 UI 顶层 `nodes/links` 直接作为本地 `/prompt` 的执行图
node ID	标识当前图中的一个节点实例	节点标题可改，ID 也不是跨所有工作流的固定职责编号
输出 slot	该节点输出列表中的索引	通常从 0 开始；不是节点 ID、不是链接 ID
`widgets_values`	某些 UI 格式按顺序存储参数	改版本或控件顺序后，不能按旧下标盲填
参数与引用	字面值，或对上游节点输出的引用	两项数组引用不是任意数值列表

例如，API 图中的 "samples": ["3", 0] 表示从当前图的节点 3 的第 0 个输出取数据，不是“采样 3 次、用 0 号随机种子”。只把这一字段单独保存，不会形成完整可运行工作流；还需存在源节点、匹配类型和可到达的输出。

UI 里的注释、重路由、禁用节点和子图也会影响导出形态。尽量从当前前端导出 API 格式，再检查实际 class_type 和引用；不要通过删除几个顶层字段手工“转换”。本机版本与示例可见第16章。

用只读 schema 检查连线

自托管 ComfyUI 的 GET /object_info 或 GET /object_info/{node_class} 可查节点定义；GET /system_stats 可查设备与内存信息。以此确认必填项、可选项、输出顺序和模型下拉值，不必为了检查而提交生成任务。官方服务器路由

GET /object_info/Wan22ImageToVideoLatent
检查：需要哪些输入？start_image 是不是可选？输出是什么类型？

GET /object_info/UNETLoader
检查：要用的模型文件是否出现在该服务器的候选列表？

GET /object_info/SaveVideo
检查：接收 VIDEO 还是其他类型？输出文件由哪个字段配置？

这不是一套独立的请求脚本，也不会执行图。模型列表能证明“被服务器发现”，不能证明文件完整、权重可加载或显存足够。

9. 一次可复查的搭建循环

保存基线 UI 图与 API 图，记下模型、节点包、输入素材和运行设置。
在受支持的小规模上跑通，确认输出数量、文件路径、视频帧数及有无音轨。
抽看开头、中间、结尾，并看一次完整播放；采样成功不等于镜头合格。
按问题只改一个主要变量，例如加入参考条件，而不是同时更换模型、seed、步数与所有提示词。
A/B 比较时尽量控制其他输入；固定 seed 方便对照，但不承诺完全确定性或跨版本相同结果。
若要更换模型家族，重新选模板和对应组件；不要只替换主模型文件名。
扩到目标尺寸、帧数与批量后再验收；小样跑通不保证最终规模的峰值内存可承受。
采用的版本重新保存，并把失效或弃用的实验标清，避免剪辑时混用不同初始状态。

画布可按“输入／模型→条件→采样→解码→封装保存→后处理”分组。共享同一组件的支路可复用其加载器；不同模型家族不因端口类型相同就共享 VAE 或编码器。整理布局的目的是能沿故障数据追到上游，不能靠折叠分组掩盖依赖。

10. 排错顺序：找最早失败的层面

现象	先收集什么证据	优先检查与处理
导入后红色缺节点	缺失的 `class_type`、节点来源、启动导入日志	核心版本是否包含它、自定义包是否装在实际运行环境、是否导入失败；先不乱换采样器
模型下拉框没有文件	加载器列表、实际模型目录、路径配置	文件是否放在服务端正确分类目录；目录变化后刷新列表，仍无则检查路径配置
线接不上或参数校验失败	源输出类型、目标输入类型、字段名与允许选项	先修连线和参数；不要把错误类型强行伪装成匹配
`shape`、矩阵维度或通道错误	首个报错节点、模型与编码器/VAE组合、输入尺寸	检查模型家族与时间/空间尺寸约束，回到原模板验证
采样开始就 OOM	当前空闲显存、尺寸、帧数、批量、权重精度	在模型允许范围内减负，检查重复加载；不能仅凭模型文件大小估算总峰值
采样完成，解码时 OOM	解码节点、最终潜变量规模、设备占用	检查视频长度、VAE 与分块/分段支持；不是每个 VAE 都实现相同的 tiled 行为
输出黑片、噪点或异常颜色	潜变量来源、匹配的 VAE、首个异常阶段和精度日志	可能是模型/条件错配、数值异常或解码问题；先定位，别一律认定“提示词不够好”
显示成功，却找不到视频	末端输出节点、执行历史中的 outputs、文件名与类型	是不是只连了预览，或只有 IMAGE 帧而未封装保存；确认保存节点真在输出路径上
有画面没有声音	是否有实际 AUDIO 数据，是否接入封装，成片音轨信息	不以提示词提到声音或节点有 AUDIO 口，推定音频已生成
视频速度或音画长度不符	帧数、封装 fps、音频采样率与实际时长	分清采样过程和播放设置；先对齐时间，再判断是否需要补帧或重做素材
改参数几乎立刻结束	执行节点与缓存信息、被改控件是否在有效支路	可能是正常缓存复用，也可能改了未执行分支；不要仅凭快就判故障
更新后以前的图失效	更新前后核心、前端、节点包与依赖版本	回到可工作的备份并逐层定位；先查当前发布说明，不凭旧问题清单认定今天仍未修复

每次报错保留节点 ID、class_type、首个异常、输入素材版本和参数快照。报错最后一行常是结果，真正原因可能在更早的模型加载或节点导入处。多用户服务器上，清队列、释放模型、重启会影响其他任务，排错前先确认当前运行状态；本章没有要求读者先重装整个环境。

11. API 的“入队成功”与“完成成功”分开

对自托管服务，POST /prompt 会验证并加入执行队列，成功响应通常包含 prompt_id；如果验证失败，会有 error 或 node_errors。这只说明接收状态。后续还可能加载失败、运行异常或没有所需输出。要继续观察 WebSocket 事件，或查询 GET /history/{prompt_id}，核对状态和输出，再实际取回文件检查。

最少记录四个阶段：已提交 → 已开始 → 执行结束状态 → 输出已取回并验收。云端、部署 API 与自托管接口可能有不同端点和认证方式，不能把本地请求体直接推广给所有服务。

12. 交付一份别人能继续改的工作流

workflow_gui.json       供画布查看与编辑，保留可理解的布局
workflow_api.json       当前版本导出的实际执行图
dependencies.md         模型文件、节点包、版本与来源
inputs.md               输入素材清单、职责和适用镜头
run_record.json         运行设置、prompt_id、输出文件、采用或返修理由

文件名是组织建议，不要求每个项目都照抄。模型权重、图片、音频与凭据不需要打进同一个 JSON。尤其检查调用服务的节点是否把 token 等敏感值存进了工作流；分享给团队时使用适当的凭据配置方式。

交付检查：

图中的节点类型和必填参数，在目标服务器可用。
模型、编码器、VAE 与可选模块确实相互兼容。
输入来自可定位的素材版本，参考职责写清楚。
所需支路没有误禁用，最后有对应的保存路径。
UI 图与 API 图对应同一个制作版本，布局能沿数据依赖阅读。
实际运行过的设置与只做过结构检查的设置分别标注。
文件取回后检查内容与时间，不把成功日志代替观看。

13. 建议的三个搭建练习

练习一：只学闭环。 用基础文生图模板，指出 MODEL、CLIP、VAE、CONDITIONING、LATENT 和 IMAGE 各在哪条线上。暂不叠 LoRA、ControlNet 与放大，确认自己知道每一步产生什么。

练习二：同一视频模板比较文／图模式。 在支持双模式的 TI2V 5B 模板副本上，只切换首帧条件，并检查导出的执行图。使用同一镜头任务，对比初始构图、身份与动作发展；结果不能提前假定 I2V 一定更好。选择依据见第14章。

练习三：给已有工作流增加一个有理由的支路。 先说清它解决什么，再查端口类型、模型兼容与额外内存，生成一次有对照的样片。写下这个模块改善了什么、没有改善什么，以及是否值得保留。可以从本机已用流程开始，避免学习与生产同时更换全部变量。

本章查证来源

以下均于 2026-10-29 读取官方页面或官方仓库；教程、节点实现和模板今后可能更新。本章不把旧技能日志中的开放问题当作当前仍存在的事实。

ComfyUI Workflow Templates——模板入口、依赖与模板包。
ComfyUI First Generation——基础生成、工作流导入与模型路径。
ComfyUI Nodes——节点、连接与状态。
ComfyUI Datatypes——IMAGE、LATENT、AUDIO 等类型结构。
Comfy-Org 基础示例工作流——基础图像链的结构入口。
Wan2.2 官方仓库——模型家族与 TI2V 的任务区别。
ComfyUI Wan2.2 教程——5B 与 14B 的组件、可选图像模式。
官方 TI2V 5B 模板 JSON——本章视频节点与数据流拆解。
ComfyUI 官方节点源码——经典加载、LoRA 与 ControlNet 节点职责。
ComfyUI Server Routes——schema、队列、历史与输出查询。

27 KiB Raw Permalink Blame History Unescape Escape