LTX-2 部署完全指南：从 22B 检查点下载跑到第一条音视频
【免费下载链接】LTX-2Official Python inference and LoRA trainer package for the LTX-2 audio–video generative model.项目地址: https://gitcode.com/GitHub_Trending/lt/LTX-2
LTX-2 是 Lightricks 的音视频生成模型，拥有 220 亿参数，可以从文本或图像生成画面，并同步产出对应的声音轨道。本文以"跑通第一条视频"为目标倒推，把 LTX-2 模型下载和 LTX-2 部署过程中最常被卡住的环节一次讲清：到底要拿哪几个文件、显存和磁盘要准备多少、生成命令怎么拼、显存不够时有哪些开关可以打开。
🎯 先定目标：按使用场景选管道
部署之前先想清楚要做什么，因为不同的生成任务对应不同的推理管道，下载的文件清单和启动命令都不一样。仓库内所有管道都可以直接用python -m启动，完整清单见 安装与使用文档。
| 管道模块 | 适用场景 | 说明 |
|---|---|---|
ltx_pipelines.ti2vid_two_stages | 生产级文本/图像到视频 | 两阶段流程，质量最好，本文主角 |
ltx_pipelines.distilled | 快速推理 | 只用蒸馏模型，速度最快 |
ltx_pipelines.ic_lora | 视频到视频转换 | 基于参考视频/图像做风格或内容迁移 |
ltx_pipelines.a2vid_two_stage | 音频到视频 | 以一段输入音频为条件生成视频 |
建议新手先跑ti2vid_two_stages：它能覆盖最常见的文生视频需求，而且后面学的所有调优手段（量化、offload、引导参数）在这条管道上都能用上。
📥 LTX-2 模型下载：22B 检查点与配套文件清单
LTX-2 模型下载一共涉及四类文件，全部存放在 Hugging Face 的Lightricks/LTX-2.3仓库中，可以用huggingface-hub库的snapshot_download拉取，也可以直接在浏览器里下载。
1. 主模型检查点（二选一）
ltx-2.3-22b-dev.safetensors：开发版本，功能完整，配合两阶段引导管道使用ltx-2.3-22b-distilled-1.1.safetensors：蒸馏版本——可以理解为把大模型"压缩"后的小模型，用更少的推理步数就能逼近原模型效果，适合追求速度的场景
2. 空间上采样器（两阶段管道必需）
ltx-2.3-spatial-upscaler-x2-1.1.safetensors：2 倍上采样ltx-2.3-spatial-upscaler-x1.5-1.0.safetensors：1.5 倍上采样
两阶段管道的第二阶段会用它把分辨率放大，最终画面清晰度主要靠它。
3. 蒸馏 LoRA（两阶段推理必需）
ltx-2.3-22b-distilled-lora-384-1.1.safetensors
LoRA 是一组体积很小的适配器权重。这个蒸馏 LoRA 挂在第二阶段的完整模型上，相当于把蒸馏模型学到的"少步数生成"能力借给 dev 检查点用，命令里会跟一个强度值（如 0.8）控制它的作用力度。
4. Gemma 文本编码器
需要下载完整的 Gemma 3 12B 模型，推荐目录为gemma-3-12b-it-qat-q4_0-unquantized（来自 Hugging Face 的google/gemma-3-12b-it-qat-q4_0-unquantized仓库，注意是整仓库而非单个文件）。
建议按下图组织目录，后面启动命令直接指向models/：
models/ ├── ltx-2.3-22b-dev.safetensors ├── ltx-2.3-spatial-upscaler-x2-1.1.safetensors ├── ltx-2.3-22b-distilled-lora-384-1.1.safetensors └── gemma-3-12b-it-qat-q4_0-unquantized/🛠️ 环境准备：克隆仓库、装依赖、确认硬件
克隆仓库并安装依赖（uv会锁住依赖版本，避免环境漂移）：
git clone https://gitcode.com/GitHub_Trending/lt/LTX-2 cd LTX-2 uv sync --frozen source .venv/bin/activate硬件与软件基线：
- GPU 显存：至少 24GB，推荐 32GB 以上
- 磁盘：模型文件约 40GB，建议预留 100GB 可用空间
- 系统：推荐 Linux（Ubuntu 20.04+）；macOS 和 Windows 可通过 Docker 运行
- 软件：Python 3.10+、PyTorch 2.0+（CUDA 11.8+）
🎬 跑第一条视频：两阶段管道启动命令
文件就位后，用下面的命令完成第一次生成（分辨率和帧数故意调小，确保先跑通再谈质量）：
python -m ltx_pipelines.ti2vid_two_stages \ --checkpoint-path models/ltx-2.3-22b-dev.safetensors \ --distilled-lora models/ltx-2.3-22b-distilled-lora-384-1.1.safetensors 0.8 \ --spatial-upsampler-path models/ltx-2.3-spatial-upscaler-x2-1.1.safetensors \ --gemma-root models/gemma-3-12b-it-qat-q4_0-unquantized \ --prompt "A beautiful sunset over the ocean with gentle waves" \ --output-path output.mp4 \ --height 512 \ --width 768 \ --num-frames 97 \ --frame-rate 25几个参数约定值得记住：
- 帧数遵循 8k+1 格式：97 帧约为 24fps 下的 4 秒，193 帧约为 8 秒
- 分辨率取 32 的倍数：512×768、768×512、1024×576 都是合法组合
--num-frames、--seed、--output-path这类参数对任意管道通用，加--help可以看到当前管道支持的全部选项
如果首次运行只是为了验证环境，也可以把分辨率和帧数再压低一档；确认输出正常后再逐步放大。
⚙️ 引导参数怎么调：CFG、STG 与模态强度
两阶段管道对视频和音频分别有一组引导参数（MultiModalGuiderParams），参考实现见 ti2vid_two_stages.py。默认取值大致是：
- 视频侧：
cfg_scale=3.0（文本引导强度）、stg_scale=1.0、rescale_scale=0.7、modality_scale=3.0、stg_blocks=[29] - 音频侧：
cfg_scale=7.0，其余与视频侧相同
用大白话说：cfg_scale控制"多听话"，数值越高画面越贴合提示词，但过高会出现过饱和和伪影；stg_blocks指定在哪些网络层施加空间时间引导（STG）；modality_scale则协调音视频两个模态之间的耦合。音频需要更强的引导（7.0 对 3.0），是因为声音细节更容易跑偏。新手先用默认值，发现"画面不听提示词"时再往上加cfg_scale，发现"音画对不上"时优先调modality_scale。
🧠 显存不够怎么办：LTX-2 FP8 显存优化
22B 参数对消费级显卡不友好，仓库提供了几层递进的开关：
- FP8 量化：加
--quantization fp8-cast，加载时把 bf16 权重即时降为 FP8，显著降低显存占用。若你在 Hopper 及以上的卡上、且手里有 FP8 检查点，可以换--quantization fp8-scaled-mm走原生 FP8 矩阵乘，性能更好 - 权重卸载：
--offload cpu把 transformer 权重留在内存里按需搬运，显存极紧时还有--offload disk从磁盘流式读取（更慢，但能活下来） - 减少推理步数：用梯度估计（gradient estimation）把去噪步数从 40 步压到 20–30 步，质量损失可控，原理与用法见 优化文档
- 跳过阶段间内存清理：显存充裕时禁用管道阶段之间的自动清理可以省时间，显存紧张则保持默认
- 选更快的管道：只求速度直接用
ltx_pipelines.distilled（蒸馏检查点 + 少量固定步数）；追求极致速度时再考虑安装注意力后端——数据中心 Blackwell（B200）可装 FlashAttention 4，Hopper 装 FlashAttention 3，其他 CUDA 卡会自动落到 PyTorch SDPA；再配合torch.compile编译优化
🩺 部署问题速查
| 症状 | 处理方式 |
|---|---|
| 模型文件不完整、加载报缺失张量 | 改用huggingface-hub的snapshot_download重新完整拉取 |
| 下载慢或中断 | 设置代理，或改用国内镜像站点拉取 Hugging Face 文件 |
| CUDA out of memory | 依次叠加--quantization fp8-cast与--offload cpu（或disk），或降低分辨率/帧数 |
| 依赖冲突、环境装不上 | 确认用uv管理并激活了.venv，不要在系统 Python 里直接 pip |
| 模型加载失败 | 核对文件是否下载完整（大小与官方一致）以及四个路径参数是否指向真实位置 |
| 视频质量差 | 增加推理步数到 40–50 步 |
| 音画不同步 | 调整音视频模态引导参数（modality_scale） |
| 分辨率偏低 | 确认第二阶段使用了空间上采样器（--spatial-upsampler-path） |
📚 下一步：训练自己的 LoRA 与延伸阅读
跑通推理之后，下一步通常是微调。训练配置目录 里有一批开箱即用的 YAML：t2v_lora.yaml用于文本到视频 LoRA，t2v_lora_low_vram.yaml是低显存版本，v2v_ic_lora.yaml面向 IC-LoRA 视频到视频训练。训练流程与数据集准备见 ltx-trainer 文档。
其他值得常翻的入口：
- LTX-Core 文档：核心模型结构、VAE、加载器与量化实现
- 管道清单与参数文档：每条管道的输入输出与专属参数
- HDR 支持：EXR 输入与 BT.2020/HLG 输出的进阶玩法
最后一条实操建议：第一次部署务必用小的分辨率和帧数验证全链路（检查点、LoRA、上采样器、Gemma 目录四个路径缺一不可），确认输出正常后再上 1024×576 以上的正式规格。
【免费下载链接】LTX-2Official Python inference and LoRA trainer package for the LTX-2 audio–video generative model.项目地址: https://gitcode.com/GitHub_Trending/lt/LTX-2
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
