LTX-2.5 本地部署完整教程：66GiB 权重、显存优化、生成与验收


版本与资源预算

LTX-2.5 是 Lightricks 官方仓库当前推荐版本。快速开始使用 22B distilled Transformer、Gemma 4 12B 文本编码器、视频 VAE、音频 VAE 与空间放大器，合计约 66GiB。下载前至少预留 90GiB，若保留缓存、多个工作流与输出，建议独立准备 150GiB 以上 SSD。

BF16 全组件适合大显存 NVIDIA GPU。显存不足时使用 --quantization fp8-cast 并将部分组件 --offload cpu；CPU offload 需要较大的系统内存且速度下降。磁盘 offload 更慢，只用于验证。不要把社区 8GB 修改版当作官方支持配置；先以官方代码和模型为基线。

系统检查

Linux + NVIDIA 是性能和依赖兼容性最稳妥的路径；Windows/macOS 可以运行，但 natten 会自动跳过并回退到 Triton 或 eager 解码。检查 GPU、驱动、系统内存和磁盘，再开始 60GB 级下载。模型仓库可能要求先接受条款，并用具有 gated repository 读取权限的 Hugging Face Token 登录。

目录与组件

官方 Hugging Face CLI 会保留 diffusion_models/、text_encoders/、vae/ 和 latent_upscale_models/ 目录。不要随意改名；命令行参数必须精确指向相应文件。DistilledPipeline 使用 distilled Transformer；两阶段高质量管线可能需要 dev Transformer 与 distilled LoRA。LTX-2.3 与 2.5 的文件、LoRA 和文本编码器不可混用。

首次生成策略

第一次只验证最小闭环：短提示词、121 帧、固定 seed、distilled pipeline、低并发。成功标准包括：程序识别 CUDA、所有组件加载完成、输出 MP4 可以解码、有视频且音轨符合预期、日志无 NaN/显存溢出。完成后再提高分辨率、帧数或使用两阶段流程。

提示词方法

官方建议用一个连续段落，按时间顺序描述动作。先写主要动作，再写姿态与外观、环境、镜头角度与运动、灯光颜色、声音和突然事件，控制在 200 个英文单词内。音视频同步场景要明确声音发生的时间点与来源，避免互相冲突的镜头命令。

性能与稳定性

先记录基准：模型版本、命令、分辨率、帧数、seed、峰值显存、系统内存、耗时与输出哈希。OOM 时按顺序处理：关闭其他 GPU 进程 → 降低帧数/分辨率 → 使用 distilled → FP8 cast → CPU offload → 磁盘 offload。不要同时修改多项，否则无法判断瓶颈。

更新与回滚

更新前保存 git rev-parse HEAD、uv.lock、完整命令和可复现样片。先在副本中执行 git pull 与 uv sync --frozen --extra natten，通过同一 seed 的回归测试后再替换生产环境。模型文件大，更新代码时不要重复下载，使用固定模型目录。

常见报错

• Hugging Face 401/403：未接受模型条款、Token 无读取权限或没有登录。
• 文件找不到：CLI 下载目录结构与命令参数不一致。
• CUDA OOM：降低工作量或启用 FP8/offload；同时观察系统内存。
• 视频可生成但解码慢：当前平台没有使用 natten，或空间放大器/VAE 成为瓶颈。
• 输出损坏：确认磁盘空间、FFmpeg 解码和进程是否在写完前被终止。
• LoRA 效果异常：确认 LoRA 与 LTX-2.5 版本和 pipeline 匹配。

验收清单

验证冷启动、连续三次生成、固定 seed 重现、OOM 后恢复、服务重启后复用权重、输出文件权限、磁盘配额与失败日志。只有这些都通过，才适合接入队列或多人网页。