LTX-2.5 22B 本地部署：ModelScope 下载、8 步推理与图生视频命令

LTX-2.5 是 Lightricks 开放权重的 22B 音画生成模型，可根据文本、图片和视频条件生成同步音画。本文把模型变化、AutoDL 环境安装、ModelScope 权重下载、Distilled 文生视频、首帧图生视频和平台接入边界整理到一篇可执行的记录中。

本文同时覆盖本地部署和在线体验。只想验证效果时，可以先使用两个在线入口；需要控制权重、工作流和硬件环境时，再按后文完成本地部署。

01_总览

1. 核心更新

新的 Diffusion Video Decoder，改善动态画面

LTX-2.5 使用新的扩散视频解码器替换此前的 VAE 重建阶段，重点改善人脸、纹理、画面文字和运动中的可见瑕疵。在越野摩托穿过泥水的官方案例中，画面同时包含高速主体运动、飞溅泥点、积水和镜头跟随，适合观察复杂动态下的稳定性。

02_新的扩散视频解码器

原生多镜头，一次生成连续场景

LTX-2.5 支持在一次生成中组织多个相互衔接的镜头，并在切镜后延续人物、环境、光照、声音和视觉风格。官方以极光下的探索者展示了同一段视频内的景别变化与镜头衔接。

03_原生多镜头

复杂 Prompt 理解更完整

模型使用定制的 Gemma 4 12B 文本编码器，并加入 Prompt Enhancer，用于处理多人物、动作、镜头运动和光照要求等复杂描述，减少长提示词中的指令遗漏。

04_复杂Prompt理解

根据动作自动判断视频时长

LTX-2.5 新增可选的 Duration Predictor。用户不手动指定帧数时，模型可以根据提示词中的动作判断所需时长，再设置生成帧数，使镜头长度与动作节奏更匹配。

05_自动判断视频时长

面向专业制作的 4K HDR 与 RAW 工作流

官方还展示了原生 4K HDR 和 RAW/EXR 工作流，面向调色、合成等后期制作环节。该能力对应完整的模型与制作流程，本地可达到的分辨率、速度和显存占用仍取决于权重格式、VAE、上采样流程和硬件配置。

06_4K_HDR_RAW工作流

2. 技术细节

新的扩散视频解码器

Diffusion Video Decoder 将视频潜变量还原为最终画面，替代此前的 VAE 重建阶段，改善人脸、纹理、画面文字和运动稳定性。权重包同时提供速度优先的卷积 VAE，可以根据画质、速度和显存条件选择解码方式。

提示词增强与自动时长预测

定制的 Gemma 4 12B 文本编码器配合 Prompt Enhancer，将复杂提示词转换为模型使用的条件信息。可选的 Duration Head 根据提示词中的动作预测所需帧数：未指定 num_frames 时自动确定片段长度，手动指定后则按用户设置生成。

Diffusion Fidelity Rendering

LTX-2.5 引入 Diffusion Fidelity Rendering，根据场景复杂度分配渲染计算。官方表示，该方法用于在控制计算开销的同时保持逐帧像素质量。

07_Diffusion_Fidelity

3. 开源模型权重

4. 模型下载与推理

4.1 硬件和软件准备

24GB 显存应使用量化、CPU offload 或专用 ComfyUI 工作流。完整 BF16 不适合按 24GB 单卡路径直接加载。建议内存 64GB 起步，offload 场景预留 96GB 到 128GB，硬盘至少预留 100GB。

官方当前建议 Python 3.12、CUDA 12.7 及以上、PyTorch 2.7 左右。如果现有日志显示 Python 3.11，出现兼容问题时应先升级 Python。

4.2 安装

git clone https://github.com/Lightricks/LTX-2.git
cd LTX-2
uv sync
source .venv/bin/activate

4.3 用 ModelScope 下载所需权重

python -m pip install -U modelscope \
  -i http://mirrors.aliyun.com/pypi/simple \
  --trusted-host mirrors.aliyun.com

cd /root/LTX-2

modelscope download \
  --model Lightricks/LTX-2.5 \
  --include \
    "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" \
    "model_patches/ltx-2.5-duration-head-bf16.safetensors" \
  --local_dir models/ltx-2.5

Distilled 推理流程还需要 LTX-2.3 提供的空间升频器：

modelscope download \
  --model Lightricks/LTX-2.3 \
  --include "ltx-2.3-spatial-upscaler-x2-1.1.safetensors" \
  --local_dir models/ltx-2.3

4.5 Distilled 文生视频

cd /root/LTX-2

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.3/ltx-2.3-spatial-upscaler-x2-1.1.safetensors \
  --duration-head-path models/ltx-2.5/model_patches/ltx-2.5-duration-head-bf16.safetensors \
  --prompt "A golden retriever running through a sunny meadow, cinematic lighting" \
  --seed 42 \
  --output-path output_distilled.mp4

省略 --num-frames 时才会使用 Duration Predictor。手动指定时，帧数需要满足：

num_frames % 8 == 1

宽度和高度需要能被 32 整除。

4.6 首帧图生视频

cd /root/LTX-2

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.3/ltx-2.3-spatial-upscaler-x2-1.1.safetensors \
  --duration-head-path models/ltx-2.5/model_patches/ltx-2.5-duration-head-bf16.safetensors \
  --image path/to/first_frame.jpg 0 1.0 \
  --prompt "The camera slowly dollies out as wind moves through the grass" \
  --seed 42 \
  --output-path output_i2v.mp4

--image PATH FRAME_IDX STRENGTH 可传多次。帧 0 是首帧条件。

【视频位置 5：Distilled 文生视频结果】

【视频位置 6：首帧图生视频结果】

5. 两个独立的在线试用入口

如果当前目标是验证提示词或图生视频效果，不必先在业务服务器加载整套 22B 权重。下面两个地址是不同的页面，分别对应模型直达体验和完整应用流程。

试用入口一：maizitech.xyz LTX-2.5 模型直达页

入口地址：https://www.maizitech.xyz/app/video?model=ltx-2.5

该地址通过 model=ltx-2.5 直接指定模型，适合快速检查 LTX-2.5 的基础生成能力。

操作顺序：

1. 打开链接并确认模型为 LTX-2.5；
2. 选择文生视频，或上传首帧进行图生视频；
3. 填写主体、动作、运镜、环境、光线和声音要求；
4. 使用直达页为当前模型提供的时长、分辨率和比例；
5. 提交任务并查看生成结果。

试用入口二：maizimarket.com 短视频生成应用

入口地址：https://www.maizimarket.com/creative-tools/short-video-generate

该地址进入麦子市场的"短视频生成"应用。进入后需要在模型下拉框中选择 LTX-2.5。

操作顺序：

1. 选择 LTX-2.5，等待时长、清晰度和比例选项完成联动；
2. 未勾选"使用规划"时，应用按当前提示词直接提交；
3. 勾选"使用规划"后，应用会先分析参考图并整理更适合视频模型的镜头、动作和声音提示词；
4. 提交后在右侧生成区域查看结果，并通过历史记录核对任务状态和失败原因。

maizitech.xyz 适合快速验证模型；maizimarket.com 适合验证参考图分析、规划任务、积分处理、任务轮询、失败提示、历史记录和结果下载等完整链路。

6. 常见问题

ModelScope 找不到模型或文件

ModelScope 不保证每个文件都已同步。出现 model not found 或 file not found 时，改用 Hugging Face 官方仓库或可用镜像。

24GB 显存能否直接运行 BF16

不建议。24GB 路径应使用 INT8、FP8/NVFP4、CPU offload 或 ComfyUI 对应权重。BF16 权重下载成功不代表能一次性全部装入 24GB 显存。

为什么装了包仍然 import 失败

通常是 pip 指向系统 Python，而运行命令使用 /root/LTX-2/.venv/bin/python。用 python -m pip --version 检查安装位置。

为什么自动时长没有生效

确认已传 --duration-head-path，并且没有手动传 --num-frames。

7. 参考链接

• ModelScope：https://modelscope.cn/models/Lightricks/LTX-2.5
• GitHub：https://github.com/Lightricks/LTX-2
• 官方 Blog：https://ltx.io/model/ltx-2-5
• ComfyUI：https://docs.ltx.video/open-source-model/integration-tools/comfy-ui