AI视频生成环境配置指南:ComfyUI-LTXVideo 装通 LTX-2 的避坑与调优清单

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

这份教程写给刚把 ComfyUI-LTXVideo 放进 custom_nodes、准备本地跑 LTX-2 模型的人:显卡档位怎么对、插件装完为什么没有节点、dev 和 distilled 版本怎么选、FP8 量化开在哪、生成慢和显存爆掉怎么调。每个环节都给了一条能核对的命令和预期输出,照着做就能自检。

预算档位怎么选显卡:12GB、24GB、48GB 各能跑什么 🎛️

把别人给的 dev 模型拖进一张 16GB 卡,进度条刚动两格就 OOM——这是最常见的翻车现场。LTX-2 本体不小,仓库 README 的前置要求写明需要 32GB+ 显存,所以选卡前先按预算对号入座,而不是默认"越大越好"。

预算档	推荐配置	适合干什么	别指望它干什么
约 ¥4000-6000	RTX 4060 Ti 16GB + 64GB DDR5 + 1TB NVMe	distilled 版 + LowVRAM 加载器,跑 768×512 短片段、熟悉节点	dev 完整版、1080p 以上输出
约 ¥15000	RTX 4090 24GB + 96GB DDR5 + 2TB PCIe 4.0 SSD	distilled 全流程调参、两阶段 1080p 工作流、IC-LoRA 控制	4K/8K 大画布 TiledFusion
¥30000 以上	RTX 5090 32GB / A6000 48GB + 128GB DDR5 + 4TB SSD	dev 完整版、TiledFusion 4K/8K、批量出片	—(注意电源留 30% 余量)

配好机器后,在 GPU 终端跑一条命令确认显存真实数值:

nvidia-smi --query-gpu=name,memory.total,memory.free --format=csv,noheader

预期输出类似 NVIDIA GeForce RTX 4090, 24564 MiB, 24100 MiB。判读标准:memory.total 除以 1024 就是可用显存(GB)。它低于 32GB 时,后文所有路线默认走 distilled + LowVRAM 组合;接近 0 的 memory.free 说明有程序占着卡,先清掉再开始。

把插件装到真正能跑:ComfyUI 插件安装报错对照

重启 ComfyUI 之后,右键节点菜单里翻不到 LTXV 分类,或者启动日志滚了一屏红字——多数情况不是代码问题,而是环境没对齐。

前置检查(两分钟)

1. ComfyUI 本体能正常启动,安装目录只含英文、数字、下划线;
2. 终端里 python --version 确认当前解释器与 ComfyUI 实际使用的一致(建议 3.10 及以上);
3. models 目录所在磁盘剩余空间 ≥100GB,这是模型加缓存的底线。

逐步安装

git clone https://gitcode.com/GitHub_Trending/co/ComfyUI-LTXVideo ComfyUI/custom_nodes/ComfyUI-LTXVideo
pip install -r requirements.txt

也完全可以走 ComfyUI Manager:启动后按 Ctrl+M,选 Install Custom Nodes,搜索 "LTXVideo" 安装,再重启一次。无论哪条路,重启后节点菜单应出现 lightricks/LTXV 分类;requirements.txt 里依赖 diffusers、einops、kornia、transformers[timm]、openimageio 等包,装完跑 pip check 确认无冲突。

报错对照(现象 / 原因 / 处置)

现象	原因	处置
节点菜单没有 LTXV 分类	依赖装进了别的 Python 环境,插件导入失败	看启动日志第一条报错,在 ComfyUI 同一环境重装 requirements
ModuleNotFoundError: kornia / einops	requirements.txt 未装全	确认虚拟环境后重跑 pip install -r requirements.txt
启动即 RuntimeError: CUDA error	torch 与显卡驱动/CUDA 版本不匹配	按当前驱动重装对应 CUDA 版本的 torch,重启
Q8 kernels are not available	未安装 q8_kernels 扩展	先安装 q8_kernels 包,再连 LTXQ8Patch 节点
文件下好了但下拉框选不到	模型没放进 models/ 对应子目录	按下一章的路径结构移动,重启 ComfyUI

LTX-2 模型版本怎么选:dev 与 distilled 别一上来就拉满 ⚠️

"显存够、机器不卡,但出片质量忽高忽低"——多半是版本混搭了。LTX-2.3 的主模型有两个,选法很直接:

版本	文件名	出片速度	质量	显存压力	适合场景
完整版	ltx-2.3-22b-dev.safetensors	慢	上限最高	大(≥32GB 才舒服)	最终成品、精细运镜镜头
蒸馏版	ltx-2.3-22b-distilled-1.1.safetensors	快数倍	略低,细节稍逊	小(配合 LowVRAM 可进 16GB)	日常迭代、两阶段流水线第一段

蒸馏版还要求配套 ltx-2.3-22b-distilled-lora-384-1.1.safetensors;两阶段工作流另需空间上采样器 ltx-2.3-spatial-upscaler-x2-1.1.safetensors 与时间上采样器 ltx-2.3-temporal-upscaler-x2-1.0.safetensors;所有工作流都要 Gemma 3 文本编码器。版本之间不要混用——distilled 模型配 dev 的 LoRA 只会得到更差的结果。

关于 FP8 量化,三句话说清:FP8 是 8 位浮点参数表示,显存占用约为 BF16 的四分之一,加载时间和峰值占用同步下降;ComfyUI-LTXVideo 提供 LTXQ8Patch 节点,可选 0.9.8、ltxv2 等量化预设,并单独开关 FP8 attention;代价是画质有小幅损失,适合先出预览,交付前换回 BF16 复跑一遍。

文件统一放在 ComfyUI/models/ 下,目录结构如下:

models/
├── checkpoints/            ltx-2.3-22b-distilled-1.1.safetensors(或 dev 版)
├── latent_upscale_models/  ltx-2.3-spatial-upscaler-x2-1.1.safetensors
│                           ltx-2.3-temporal-upscaler-x2-1.0.safetensors
├── loras/                  ltx-2.3-22b-distilled-lora-384-1.1.safetensors
└── text_encoders/          gemma-3-12b-it-qat-q4_0-unquantized/(整目录放置)

文件名和节点下拉列表必须逐字一致,多一个空格都会被当成缺失文件。

1080p 输出怎么提速:采样与加速参数的收益-代价表

一段 97 帧的 768×512 视频跑了二十分钟,想砍掉一半时间——提速手段都有代价,按收益排序挑着上:

配置(节点 / 参数)	预期收益	代价
LTXQ8Patch:quantization_preset 选 0.9.8,use_fp8_attention 打开	显存峰值明显下降,推理提速,小卡从"跑不动"变"跑得动"	细节有轻微损失,成片前建议 BF16 复核
LowVRAM 加载器+ 启动参数 python -m main --reserve-vram 5	模型串行换入换出,峰值压到 32GB 以内	每次换模型都有搬运时间,总时长变长
STGGuider + LTXVApplySTG 指定 block "14, 19"	结构更稳、运动更连贯,畸形和漂移减少	每个去噪步多一次前向,整体变慢
DynamicConditioning:power 1.3~2.0,only_first_frame 开	图生视频首帧贴合更紧,构图不易漂	power 给过头,画面会"钉"在参考帧上,运动变僵
LTXVLoopingSampler:temporal_tile_size 80、temporal_overlap 24	长视频按时间 tile 分段生成,显存只按 tile 计	总时长增加,注意重叠区条件强度 0.5 附近的取舍
LTXVTiledFusionSampler	突破训练窗口,出 4K/8K 大画布且少接缝	耗时最高;显存取决于 tile 尺寸而非整幅画布

生成期间开一个终端观察 GPU 占用:

nvidia-smi -l 2

重点看两列:memory.used 的峰值(离总显存留 10% 以上余量,防碎片化 OOM)和 GPU-Util。如果 util 长期低于 70%,瓶颈往往不在采样,而在模型换入换出或 VAE 解码——优先开量化或换 distilled 版,而不是继续降步数。

出问题时这样查:配置自检清单与错误速查

机器时好时坏:同一条工作流今天能出片,明天卡到一半——先把清单走完,再谈调参。

跑片前自检

•  显存档位与所选版本匹配:dev 版按 ≥32GB 规划,16GB 卡固定走 distilled + LowVRAM
•  各模型文件位于正确子目录,文件名与节点下拉逐字一致
•  Gemma 3 文本编码器整目录就位,tokenizer 文件一个不缺
•  pip check 无冲突,requirements 装在 ComfyUI 同一环境
•  磁盘剩余 ≥100GB(模型 + 缓存 + 输出视频)
•  用 最简单阶段工作流 跑通一条,确认全链路没问题
•  采样与加速参数已按显卡档位调整(见上一节)

错误速查(错误代码 / 可能原因 / 解决步骤)

错误信息	可能原因	解决步骤
CUDA out of memory	显存不够或多模型同时驻留	① 换 distilled 版 → ② 连 LTXQ8Patch → ③ 换 LowVRAM 加载器 → ④ 加 --reserve-vram 启动参数
ModuleNotFoundError: xxx	依赖缺失或环境错乱	确认激活的是 ComfyUI 环境,重装 requirements.txt
File not found / 下拉无模型	路径或文件名不符	对照上一节目录结构移动文件,注意大小写
Q8 kernels are not available	未安装 q8_kernels	安装扩展包后重启 ComfyUI 再连节点
启动即 CUDA error	驱动与 torch 版本不匹配	重装匹配当前驱动的 CUDA 版 torch,重启
文本编码器加载报错	tokenizer 目录文件不全	重新完整下载 Gemma 3 编码器目录

清单全绿、错误表没命中,再去动采样参数。先把 distilled 工作流跑出一条 5 秒短视频,能出片说明环境已通,再按第四节的收益-代价表逐项提速。

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