LTX-2

环境要求

• 操作系统与显卡：natten 加速后端仅支持 Linux + CUDA，其他平台会自动跳过该后端并回退到 Triton/eager 实现
• 需要安装 uv（用于 uv sync / uv run）与 Hugging Face CLI（hf 命令）
• 磁盘空间：模型权重合计约 66 GiB
• 已在 Hugging Face 上接受 LTX-2.5 模型使用条款，并准备一个 Read 权限的访问令牌
• Python 环境（项目为 Python 包，依赖由 uv 管理），推理建议有足够显存的 NVIDIA GPU

安装与启动步骤

1. 1克隆仓库

   把官方仓库拉到本地并进入项目根目录，后续所有命令都在该目录下执行。

   git clone https://github.com/Lightricks/LTX-2.git
   cd LTX-2

   复制

2. 2安装依赖

   用 uv 安装依赖并启用 natten 额外后端；该后端仅 Linux+CUDA 生效，Windows/macOS 会自动跳过，同一条命令通用。

   uv sync --extra natten

   复制

3. 3登录 Hugging Face

   使用有读取权限的 Read token 登录；细粒度 token 需勾选“读取受限仓库”权限，否则下载会 401/403。

   hf auth login

   复制

4. 4下载模型权重

   约 66 GiB。CLI 会在 --local-dir 下保留仓库目录结构，必须下载到 models/ltx-2.5，才能匹配下一步的路径参数。

   hf download Lightricks/LTX-2.5 
       diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors 
       text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors 
       vae/ltx-2.5-video-vae-bf16.safetensors 
       vae/ltx-2.5-audio-vae-bf16.safetensors 
       latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors 
       --local-dir models/ltx-2.5

   复制

5. 5运行音视频生成

   这是 DistilledPipeline（最快起点），按提示词生成带同步音频的视频，结果写到 --output-path 指定的 output.mp4。

   uv run python -m ltx_pipelines.distilled 
       --transformer-path       models/ltx-2.5/diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors 
       --text-encoder-path      models/ltx-2.5/text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors 
       --video-vae-path         models/ltx-2.5/vae/ltx-2.5-video-vae-bf16.safetensors 
       --audio-vae-path         models/ltx-2.5/vae/ltx-2.5-audio-vae-bf16.safetensors 
       --spatial-upsampler-path models/ltx-2.5/latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors 
       --num-frames 121 
       --seed 42 
       --output-path output.mp4 
       --prompt "A medium close-up shot features a Caucasian man with a beard, wearing a green and white baseball cap and a light blue shirt over a white t-shirt. He looks intently at the camera, a quick sniff sound is heard, then he speaks with a deep male voice, saying, 'I think it's so good.' The camera remains static with a shallow depth of field."

   复制

关键配置

如何确认成功

命令正常结束后，当前目录会生成 output.mp4，播放可见画面且声音与口型描述一致即为启动成功。

常见问题

注意事项

• 命令中的权重路径依赖 --local-dir models/ltx-2.5 的目录结构，改下载目录时必须同步修改推理命令里的路径
• DistilledPipeline 是速度最快的入门管线；README 提到对生产级画质可改用 DFR 管线（更慢、更吃显存）
• 更多通用 CLI 参数见 packages/ltx-pipelines/docs/installation.md，VAE 解码后端优化见 optimization.md