ComfyUI-LTXVideo 完整攻略：LTX-2 视频生成从 0 到出片一次到位

ComfyUI-LTXVideo 完整攻略：LTX-2 视频生成从 0 到出片一次到位

【免费下载链接】ComfyUI-LTXVideoLTX-Video Support for ComfyUI项目地址: https://gitcode.com/GitHub_Trending/co/ComfyUI-LTXVideo

ComfyUI-LTXVideo 是 ComfyUI 生态里最完整的 LTX-2 扩展节点包，把文生视频、图生视频、IC-LoRA 构图控制、HDR 电影感输出、Lipdub 配音换词、纯音频生成等 LTX-2 能力全部封装成可视化节点，并附带可直接加载的示例工作流。这篇笔记按"装环境 → 跑工作流 → 排故障 → 玩高级控制"的顺序，给你一套完整的 LTX-2 安装教程与 ComfyUI 视频生成实操路径，从 0 到出片一次到位。

能力全景：核心自带什么，LTXVideo 补什么

先厘清一个关键事实：LTX-2 本身已经内置在 ComfyUI 核心里，你不需要为"能跑 LTX-2"装任何插件。ComfyUI-LTXVideo 提供的是核心之外的全部高级能力——IC-LoRA 引导管线、HDR/EXR 后处理、低显存加载器、平铺采样、音频单模态模式，以及一批藏在 tricks 目录里的高级控制节点 🎯。

• LTX-2 核心自带：联合音视频 Transformer 的 checkpoint 加载、VAE 编解码、基础采样器、Gemma 3 文本编码接口、蒸馏/完整两种模型形态
• LTXVideo 补充：Union IC-LoRA（深度/Canny/姿态三合一控制）、HDR IC-LoRA 与LTXVHDRDecodePostprocess解码链、Dub-It 配音换词、Pixel Spatial Upscaler 创意超分、LTXVAudioOnlyModel纯音频模式、低显存顺序加载器、Tiled Fusion 大画布采样、注意力库/STG/PAG 等 tricks 节点

换句话说：核心保证你能生成，LTXVideo 决定你能生成得多专业。全部节点注册关系集中在 nodes_registry.py，节点入口在__init__.py，装好后节点菜单会出现 "LTXVideo"（显示名带 🅛🅣🅧 前缀）分类。

环境就绪：先装插件，再放模型 📦

装插件的两条路

Manager 安装（推荐）：ComfyUI 界面按Ctrl+M打开 Manager → Install Custom Nodes → 搜索 "LTXVideo" → Install → 重启。这是官方 Quick Start 推荐路径，重启后节点分类即出现。

手动克隆（Manager 失败时用）：

git clone https://gitcode.com/GitHub_Trending/co/ComfyUI-LTXVideo

把目录放进 ComfyUI 的custom_nodes/下（最终路径形如ComfyUI/custom_nodes/ComfyUI-LTXVideo），再装依赖并重启：

pip install -r requirements.txt

依赖清单很短（requirements.txt），重点看两个：colour-science负责 HDR primaries 换算，openimageio负责 EXR 读写——缺了它后面 HDR 章节的 EXR 导出会翻车。

模型该放哪个目录

硬件基线先说死：CUDA 显卡 32GB+ 显存、100GB+ 磁盘空间（模型+缓存，这是官方 Prerequisites 的硬指标）。目录归属如下，放错位置 = 加载失败：

偷懒方案：不手动下载，第一次运行工作流时打开Workflow Overview面板，它会把 Missing Models 列出来，点 Download all 一次性拉齐。手动下载中断过的文件务必校验完整性再重试。

按任务拆解核心工作流

示例工作流在 example_workflows/ 下按模型版本分目录：2.3/是当前主力，2.5/是蒸馏模型族（含更细的任务树和 选型决策树），2.0/仅作旧版参考。以下按"你要做什么"逐个拆。

文生视频与图生视频：单阶段还是两阶段

这是 ComfyUI 图生视频/文生视频的日常入口，两条工作流按用途选：

• 单阶段：LTX-2.3_T2V_I2V_Single_Stage_Distilled_Full.json—— 一次蒸馏/完整模型直通，最快最省显存，出预览稿用
• 两阶段：LTX-2.3_T2V_I2V_Two_Stage_Distilled.json—— 第一阶段在基础分辨率出片，第二阶段过 2× 空间超分再 refine。构图和运镜在第一阶段锁定，后续不再动，追求成片质量用它

关键参数：帧数必须满足1 + 8 的倍数（时长按 fps × 秒数换算，落点可能略有偏移）；提示词写清楚镜头运动和风格。显存吃紧时的降级顺序：两阶段换单阶段 → 1024×576 降到 512×288 → 减帧数 → 完整版换蒸馏版，逐项往下试，通常前两项就够。

用 Union IC-LoRA 锁住构图与运动

Union IC-LoRA 把深度、Canny 边缘、人体姿态三种控制信号合并进同一个 LoRA，一次加载按需切换。它的设计亮点是在下采样后的 latent 上运算——显存占用更低、推理更快，质量不打折。

• 结构/构图控制：LTX-2.3_ICLoRA_Union_Control_Distilled.json，参考片先过标注器（深度默认接好，图内可切 Canny/姿态）
• 轨迹运动控制：LTX-2.3_ICLoRA_Motion_Track_Distilled.json，在第一帧上画稀疏运动轨迹（配合 sparse_tracks.py 的绘制/编辑节点），让画面元素沿指定路径走
• 显存降级：Union 工作流本身就在降采样 latent 上跑，若仍紧张就把参考分辨率降半，或换2.0/目录的LTX-2_ICLoRA_All_Distilled_ref0.5.json（显式 0.5 下采样参考版）

HDR 电影感与 EXR 输出

HDR 链路的原理：HDR IC-LoRA 生成的是LogC3 压缩空间的线性 HDR 帧，LTXVHDRDecodePostprocess节点负责解码回线性 HDR，同时输出两路——Reinhard 色调映射的 SDR 预览 + 原始线性 HDR 张量，后两者可直接进调色流程 🎬。

• 单阶段起步：LTX-2.3_ICLoRA_HDR_Distilled.json（SDR 视频进，ACEScct HDR 出）
• 大画布/高分辨率：2.5/HDR_workflows/LTX-2.5_V2V_TiledFusion_SDR_to_HDR.json（FullHD → 4K/8K 平铺阶梯）
• 导出 EXR：依赖openimageio把线性 HDR 帧写成 16/32 位 EXR 序列，pip install openimageio已包含在依赖里，装好依赖即开即用
• 显存降级：HDR 解码用 float32 VAE，比 SDR 更吃显存——先用单阶段 2.3 图验证效果，再上 2.5 平铺图；解码 tile 调小

Lipdub 配音换词：换台词但保音色

Dub-It IC-LoRA 的输入是"源视频 + 目标台词文本"，输出是重新生成的唇形与音频，匹配目标文本的同时保留说话人身份——参考音频 token 提供声纹上下文，所以换语言（多语种配音）或同语言改台词都成立。

工作流：LTX-2.3_ICLoRA_DubIt_Two_Stage_Distilled.json。两阶段管线：Stage 1 在基础分辨率同时生成视频和音频，Stage 2 放大画面时冻结音频，保证音画不脱节。适合短视频二创和本地化生产。显存降级：Stage 1 就是大头，直接降基础分辨率和帧数；音频分支本身几乎不占显存，不用动。

低清素材创意超分与纯音频生成

Pixel Spatial Upscaler不是插值器。它基于参考画面"重新绘制"细节，属于生成式放大，2× 与 4× 两档（ltx-2.3-22b-ic-lora-pixel-spatial-upscaler-x2/x4-0.9.safetensors）。标准工作流是草稿先行：先在约 280p 低分辨率出片定死构图与运动，再跑LTX-2.3_ICLoRA_Pixel_Spatial_Upscaler_Distilled.json出最终高清。三个旋钮控制贴合度：LoRA 强度、引导强度、步数——调低更贴近源片，调高细节更"自由"。

纯音频生成是冷门但实用的能力：LTX-2 是联合音视频 Transformer，但可以用LTXVAudioOnlyModel节点关掉run_vx与双向 cross-attention 标志，切到音频单模态模式。配套流程：LTXVAudioOnlyEmptyVideoLatent（固定 64×64 单帧占位，无参数可调）+LTXVConcatAVLatent拼接音频 latent → 采样 →LTXVAudioVAEDecode直接提取音频 → 用内置Save Audio (FLAC)存盘。工作流直接开LTX-2.3_T2A_Single_Stage_Distilled.json，提示词描述想要的声音内容即可，显存占用比同参数视频生成低一个量级。

跑不动怎么办 🛠️

显存爆掉：三种降法

现象：采样阶段直接 OOM 崩溃，报错像一堵墙。原因：32GB 是基线不是上限，完整模型 + 高分辨率 + 两阶段超分三者叠加必然溢出。解法按顺序试：

1. 换用 low_vram_loaders.py 里的LowVRAMCheckpointLoader/LowVRAMLatentUpscaleModelLoader/LowVRAMAudioVAELoader，它们保证模型加载/卸载顺序正确并做 offload，让生成落在 32GB 内
2. 启动参数预留系统显存：

python -m main --reserve-vram 5

3. 降分辨率（1024×576 → 512×288）或减帧数；还不行就把完整模型换蒸馏版
4. 极限情况：LoRA 走LTXVQ8LoraModelLoader的 8-bit 量化加载（q8_nodes.py），平铺 VAE 解码见下节

节点找不到：检查两个位置

现象：工作流加载后满屏红节点，或菜单里没有 🅛🅣🅧 分类。原因：要么插件没装在custom_nodes/下，要么依赖没装好导致导入中断（ComfyUI 会静默跳过加载失败的节点包）。解法：确认目录是ComfyUI/custom_nodes/ComfyUI-LTXVideo（注意不要多套一层）；看启动日志里的 import 报错，缺什么补什么，兜底重跑pip install -r requirements.txt。装好后对照 nodes_registry.py 里的注册清单确认节点是否都进表。

模型加载失败：路径是头号嫌疑

现象：加载器下拉框选不到文件，或选中后报 not found / corrupt。原因：LTX-2 的 checkpoint、超分模型、LoRA、文本编码器各有固定目录（见前文表格），放错目录就不可见；下载中断的文件也会报 corrupt。解法：按表格重新归位；中断文件删掉重下并校验；再看一眼df -h，磁盘剩余低于模型体积时下载会静默失败。

EXR 导不出：先查 openimageio

现象：HDR 工作流 SDR 预览正常，但 EXR 序列一个文件都没写出来，或节点报后端缺失。原因：本仓库的 EXR 读写走OpenImageIO后端，不是 OpenCV——requirements.txt里写明了 "no OpenCV EXR fallback"，装 ComfyUI 时没装过openimageio就没有任何 EXR 能力。解法：

pip install openimageio

或重跑pip install -r requirements.txt，重启 ComfyUI 即可。

蒸馏与完整模型混用：出片效果诡异

现象：画面糊、运动漂移、步数"好像不对"，但没有任何报错。原因：蒸馏版工作流的采样 schedule（sigma 序列、步数）是按蒸馏模型调的，把蒸馏 JSON 里的参数搬到完整模型上（或反过来），引导强度与噪声调度全错位。解法：文件名即契约——..._Full.json只配完整版 checkpoint，..._Distilled.json只配蒸馏版，一一对应不互换。同一任务下两个 JSON 都现成的，直接换文件。

进阶工具箱：tricks 目录里的高级控制 🧪

跑熟基础工作流后，tricks/nodes/ 是能力边界所在，每个节点解决一个具体痛点：

• 注意力库（attn_bank_nodes.py）：把指定采样步的注意力权重存进 bank，回灌给后续片段或后续采样——跨片段保持场景与风格一致性，做系列视频时的核心工具
• STG 引导（stg.py + presets/stg_advanced_presets.json）：STGGuiderAdvanced配预设参数，用空间-时间偏移扰动改善运动质量，治"画面糊动、肢体漂移"
• PAG（ltx_pag_node.py）：扰动注意力引导，用模糊注意力对照抑制过饱和与伪影，提升画面质感
• Feta 增强（ltx_feta_enhance_node.py）：微调注意力贡献的轻量增强，和 PAG 叠用
• 平铺采样（tiled_sampler.py / tiled_fusion_sampler.md）：LTXVTiledSampler把大画布拆成独立 tile 各自采样；LTXVTiledFusionSampler更高级——所有 tile 共享一张 latent 画布和同一噪声场，每步去噪后融合重叠区，专治"画布大于模型训练窗口"的 4K/8K 生成，配合LTXVGetTilingSizes保证尺寸合法
• 平铺 VAE 解码（tiled_vae_decode.py）：解码阶段平铺，高分辨率出片不爆显存，是 LTX-2 显存优化里最实用的一招
• Gemma 3 提示词增强（gemma_encoder.py）：提示词写得烂时，LTXVGemmaEnhancePrompt用 Gemma 3 本地扩写，系统提示词模板在 system_prompts/（gemma_t2v_system_prompt.txt/gemma_i2v_system_prompt.txt）；没本地 Gemma 可用GemmaAPITextEncode走 API
• 循环采样（looping_sampler.py）：多提示词循环采样，长视频分段叙事

这些节点可以任意串联：注意力库保一致性 → STG 治运动 → PAG/Feta 提质感 → 平铺解码控显存，组合方式比工作流本身更有想象力。

收尾：下一步走哪条路

• 刚跑通第一条视频的：别急着上高级节点，把单阶段工作流的分辨率、帧数、提示词各拉三组对照，搞懂"输入 → 采样 → 解码"三段式连接关系，再换两阶段图体会先定稿后放大的节奏。
• 已在反复调参的：直接进 tricks/nodes/ 加注意力库 + STG 预设，然后拿LTXVTiledFusionSampler试一次 4K 画布——显存和画质的边界会立刻清楚。

AI 视频生成是"环境先行"的工程：插件、模型、参数三者理顺之后，剩下的全是调参乐趣。跑起来，比看十篇教程都管用。

【免费下载链接】ComfyUI-LTXVideoLTX-Video Support for ComfyUI项目地址: https://gitcode.com/GitHub_Trending/co/ComfyUI-LTXVideo