ComfyUI-LTXVideo：LTX-2 视频生成节点实用指南，从跑通到可控长视频-平芜编程栈

ComfyUI-LTXVideo：LTX-2 视频生成节点实用指南，从跑通到可控长视频

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

ComfyUI-LTXVideo 是一套面向 LTX-2 视频生成模型的 ComfyUI 自定义节点。LTX-2 模型本身已内置于 ComfyUI 核心，本项目补齐了工程化落地所需的加载、采样、条件控制与解码环节：文本/图像转视频、IC-LoRA 条件控制、长视频分块采样、低显存加载等。适合有 32GB 级显存、需要可控视频输出的创作者与工程师，跑通后可直接产出带音轨的短视频、受控运镜片段和高分辨率成片。

适用场景判断：哪些任务值得用

先看它擅长什么，再决定投入环境搭建的成本：

适合：

需要画面与音频同步生成的短片（LTX-2 是音视频联合 transformer，单阶段即可出带声音的视频）
有参考素材的 video-to-video：按深度/边缘/姿态控制生成方向，或替换口型对白（Dub-It IC-LoRA）
长视频、高分辨率成片：靠时间分块（LTXVLoopingSampler）和空间融合（LTXVTiledFusionSampler）突破单次推理窗口
有现成素材要编辑：inpaint 补洞、outpaint 扩画幅、SDR 转 HDR、2×/4× 生成式上采样

不适合：

显存远低于 32GB 且无法用低显存节点降档的机器（官方基线就是 32GB+，磁盘预留 100GB+）
要求逐像素精确复刻参考片的场景——Pixel Spatial Upscaler这类节点是"生成式"上采样，会合成细节而非忠实插值
只需要静图编辑或一次性小模型的轻量任务，直接走 ComfyUI 内置节点更省

判断标准很简单：如果你的需求是"从文字/一张图/一段旧视频出发，产出可交付的视频文件，且对运镜、结构或时长有约束"，这套节点链就是为此设计的。

最小可用环境准备：安装与模型清单

官方推荐路径是走 Comfy Manager，手动安装仅作备选。

打开 ComfyUI，按Ctrl+M或点 Manager
进入 Install Custom Nodes，搜索LTXVideo，安装并等待完成
重启 ComfyUI

验证是否装好：新建节点时按L开头搜索，节点菜单的Lightricks分类下应出现带 🅛🅣🅧 前缀的节点（如LTXVLoopingSampler、LTXVTiledFusionSampler）。没有该分类说明插件未加载，检查ComfyUI/custom_nodes/下是否存在ComfyUI-LTXVideo目录，并确认依赖装全（pip install -r requirements.txt，依赖包含 diffusers、einops、transformers、openimageio 等）。

手动安装备选（网络受限时）：

git clone https://gitcode.com/GitHub_Trending/co/ComfyUI-LTXVideo # 放入 ComfyUI/custom_nodes/ 后安装依赖并重启 pip install -r ComfyUI-LTXVideo/requirements.txt

模型文件按用途分目录存放，缺失任一项对应工作流就会报错：

文件	放置目录	何时需要
`ltx-2.3-22b-dev.safetensors`或`ltx-2.3-22b-distilled-1.1.safetensors`（二选一）	`models/checkpoints`	所有工作流，必选其一
Gemma 3 文本编码器（整目录）	`models/text_encoders/gemma-3-12b-it-qat-q4_0-unquantized`	所有工作流
`ltx-2.3-spatial-upscaler-x2-1.1.safetensors`	`models/latent_upscale_models`	两阶段工作流
`ltx-2.3-temporal-upscaler-x2-1.0.safetensors`	`models/latent_upscale_models`	两阶段工作流
`ltx-2.3-22b-distilled-lora-384-1.1.safetensors`	`models/loras`	部分两阶段图（DistilledPipeline/ICLoraPipeline 类除外）
各类 IC-LoRA / 相机控制 LoRA	`models/loras`	用到对应控制能力时按需下载

清单来源是仓库 README.md 的 Required Models 一节，文件名与目录名以它为准，不要自行改名。

跑通第一条结果：两阶段蒸馏工作流

选example_workflows/2.5/下的LTX-2.5_T2V_I2V_Two_Stage_Distilled.json作为首跑目标，官方对该文件夹的说明里把它标为 "Start here"：文本或图转视频、2× 空间上采样加短精炼、音视频同出。该目录的完整工作流选择逻辑见 example_workflows/2.5/README.md，其中有一棵"按输入类型分流"的决策树，比逐文件试错快。

操作与检查点：

加载：Workflow → Open（或把 json 拖进画布）
补模型：打开 Workflow Overview 面板，首次使用会列出 Missing Models，点 Download all 一次即可，后续复用
填输入：左侧 Inputs 区填提示词，可选首帧图、时长。注意帧数约束：帧数必须是 1 + 8 的倍数（如 81 帧），图里填的时长会经 fps 换算，可能略偏
运行并看结果：点 Run 后观察队列；输出应同时得到视频与音频。stage 1 在基础分辨率生成，stage 2 做 2× 上采样与精炼，若只出低清说明 upscaler 模型缺失或没进图

首跑成功的判断口径：输出文件存在、画面无整块噪点、音画同步。若提示词明显未被遵循，优先检查文本编码器是否加载成功（Gemma 目录不完整时编码会静默降级），再谈参数调优。

影响结果的关键参数：按优先级排序

只列会实际改变画面、速度或显存的项，其余保持默认。

1. 主模型选择（dev 完整模型 vs distilled 蒸馏模型）dev 版质量上限高但采样步数多、慢；distilled 版只需少量步数，适合迭代。日常出片建议从 distilled 起步，最终成片再换 dev 复跑。这是速度差异的最大来源。

2. 帧数与分辨率显存消耗随"帧数 × 像素数"上升，二者是同一预算。帧数守 1+8k 规则；分辨率不足时用两阶段上采样补，而不是一开始就拉高基础分辨率。

3. 解码 tile 大小2.5 系列图的默认值按低显存机器调过；显存富余时调大 decode tile size 可提速（更少、更大的 tile 跑得快但吃显存），每个图内有 Decode notes 说明上限。

4. 分块采样参数（长视频/高分辨率场景）LTXVLoopingSampler的关键旋钮（完整参数表见 looping_sampler.md）：

temporal_tile_size（默认 80，范围 24–1000，步进 8）：每块帧数。短片 40–80，中片 80–120，长片 120–200
temporal_overlap（默认 24）：块间重叠帧数，经验取 tile 的 25–30%
temporal_overlap_cond_strength（默认 0.5）：前一块尾帧对下一块的条件强度，越高时间越连贯
adain_factor（默认 0）：长序列建议 0.1–0.3，抑制色彩过饱和漂移
horizontal_tiles/vertical_tiles（各 1–6）：空间切分，2K 常用 2×1~2，4K 常用 2~3 × 2~3，配spatial_overlap至少 1

5. Tiled Fusion 专属约束（4K/8K V2V）LTXVTiledFusionSampler与独立采样的LTXVTiledSampler不是一回事，别混用。硬约束（详见 tiled_fusion_sampler.md）：

overlap_frac保持 ≥ 0.5，否则结构化内容上会出现周期性网格
采样器只认离散步法：euler、heun、dpm_2；多步记忆类（dpmpp_2m、lms）会丢失记忆，ancestral 类会在 tile 间出缝
tile_frames对 LTX 取 97；片段超过训练窗口时，guide 端与 sampler 端要开同一个use_streaming和tile_frames
提示词只写风格（光线、调色、锐度），不要点名具体物体——上采样后点名的细节可能盖到每个空间 tile 上

提升可控性与稳定性：按任务分类

控制能力由 LoRA + 配套节点组成，按"想解决什么问题"对号入座：

镜头语言：官方提供 dolly in/out/left/right、jib up/down、static 七款相机控制 LoRA（19b 系列）。想要平滑推拉摇移，加载对应 LoRA 后生成，效果是整段镜头匀速运动。

结构保持：Union IC-LoRA 把深度图与边缘（canny）条件合进单个 LoRA，且工作在降采样 latent 上，比分别挂两个 LoRA 省显存、快推理。2.5 系列图里默认接深度，图内可切换标注器（depth/canny/pose），入口工作流是LTX-2.5_ICLoRA_Union_Control_Distilled.json。

人物动作：LTX-2.3_ICLoRA_Motion_Track_Distilled.json用稀疏运动轨迹控制——在第一帧上画轨迹（配套LTXVDrawTracks、LTXVSparseTrackEditor节点，前端交互在web/js/sparse_track_editor.js），生成沿轨迹运动的视频。姿态精控另有 pose-control IC-LoRA。

素材编辑类：inpaint/outpaint 共用一支 LoRA（遮罩区域填充 / 画幅外扩）；HDR IC-LoRA 把 SDR 升为 ACEScct HDR，LTXVHDRDecodePostprocess负责从 LogC3 压缩空间解回线性 HDR，可选导出 16/32 位 EXR 序列（依赖 openimageio）；Dub-It IC-LoRA 做跨语言配音，两阶段流程里第二阶段冻结音频只做上采样。

长视频稳定性：这是分块采样的核心问题。时间漂移靠temporal_overlap+temporal_overlap_cond_strength压住，色彩过饱和靠adain_factor（0.1–0.3）修正，需要全局锚点时再接 negative index latents 给每个时间块提供长期参照。分块种子是确定性派生的（base_seed + 时间偏移 + 空间偏移），同一配置可复现，也可以只重生成某一块。

性能与故障排查：显存、速度与伪影

低显存有两条官方认可的降档路径：

用 low_vram_loaders.py 里的 loader 节点（LowVRAMCheckpointLoader等），它们保证正确的执行顺序并做模型 offload，官方口径是 32GB VRAM 可跑
启动参数预留显存：python -m main --reserve-vram 5

速度层面，"换 distilled 模型 + 单阶段图 + 加大 decode tile"是三个正交手段，可叠加。

常见症状对照：

症状	可能原因	处理
节点菜单无 Lightricks 分类	插件未加载或未重启	检查 custom_nodes 目录，重启 ComfyUI
报模型缺失/加载失败	文件放错目录或名字不符	对照上表目录清单，文件名原样保留
OOM / 显存不足	分辨率×帧数超预算	换 distilled 模型、低显存 loader、降帧数或 tile
长视频色彩漂移、过饱和	时间块统计量漂移	`adain_factor`调到 0.1–0.3，提高 overlap
成片出现规则网格/接缝	Tiled Fusion 参数越界	`overlap_frac`提到 0.5+，改用 euler/heun
提示词部分不生效	CFG/guidance 或编码器问题	先验证 Gemma 目录完整性，再动 guider 参数
上采样后出现"多出来的物体"	提示词点名了具体物体	提示词改为纯风格描述

⚠️ 排查顺序建议固定为：模型文件完整性 → 参数越界 → 显存降档，不要一开始就怀疑代码。

复用与扩展：模板、批量与源码入口

工作流模板：example_workflows/下按 2.0 / 2.3 / 2.5 三个版本分目录，每个 json 都可直接当生产起点；2.5 目录内还有README.md的分流决策树。模板化的正确姿势是整图复用子图布局（Load Models / Inputs / Preprocess / Generate / Decode），只改输入与 LoRA，而不是手搭节点
批量与 API：走 ComfyUI 标准 API 队列即可，把模板 json 的 prompt 节点内容按条替换后提交；控制提交间隔避免显存堆积。不需要为批处理改造本项目代码
进阶技巧入口：tricks/目录是实验性节点集（PAG、FlowEdit、注意力覆盖等，节点名带 Experimental 前缀），presets/stg_advanced_presets.json提供 STG 高级引导预设，system_prompts/内是 Gemma 提示词增强的系统提示
文档：仓库内两份 md（looping_sampler.md、tiled_fusion_sampler.md）就是这两个复杂节点的参数手册，比外部二手资料可靠

从这一步开始

用 Comfy Manager 装插件并重启，确认 Lightricks 分类可见
按下表目录清单备齐 dev 或 distilled checkpoint + Gemma 编码器，跑LTX-2.5_T2V_I2V_Two_Stage_Distilled.json出第一条带声音的视频
出片后只按一个变量调整（先帧数、再分辨率、最后 LoRA 控制），每次改动记录种子与参数，攒出自己的可复现基线，再进入长视频分块阶段

环境跑通只需一晚上，参数手感需要几次复跑才能建立——把首跑的 json 和参数存下来，它是后续所有对比的基准。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考