LTX-2

LTX-2 是首个基于 DiT 的音视频基础模型，它将现代视频生成的所有核心能力整合到一个模型中：音视频同步、高保真度、多种性能模式、可直接用于生产的输出、API 访问以及开放获取。

🚀 快速入门

# 克隆仓库
git clone https://github.com/Lightricks/LTX-2.git
cd LTX-2

# 设置环境
uv sync --frozen
source .venv/bin/activate

必需模型

从 LTX-2.3 HuggingFace 仓库 下载以下模型：

LTX-2.3 模型检查点（选择并下载以下其中之一）

• ltx-2.3-22b-dev.safetensors - 下载
• ltx-2.3-22b-distilled.safetensors - 下载

空间超分辨率模型 - 当前仓库中两阶段流水线实现所必需

• ltx-2.3-spatial-upscaler-x2-1.0.safetensors - 下载
• ltx-2.3-spatial-upscaler-x1.5-1.0.safetensors - 下载

时间超分辨率模型 - 模型支持，未来流水线实现将需要

• ltx-2.3-temporal-upscaler-x2-1.0.safetensors - 下载

蒸馏 LoRA - 当前仓库中两阶段流水线实现所必需（除 DistilledPipeline 和 ICLoraPipeline 外）

• ltx-2.3-22b-distilled-lora-384.safetensors - 下载

Gemma 文本编码器（从仓库下载所有资产）

• Gemma 3

LoRAs

• LTX-2.3-22b-IC-LoRA-Union-Control - 下载
• LTX-2.3-22b-IC-LoRA-Motion-Track-Control - 下载
• LTX-2-19b-IC-LoRA-Detailer - 下载
• LTX-2-19b-IC-LoRA-Pose-Control - 下载
• LTX-2-19b-LoRA-Camera-Control-Dolly-In - 下载
• LTX-2-19b-LoRA-Camera-Control-Dolly-Left - 下载
• LTX-2-19b-LoRA-Camera-Control-Dolly-Out - 下载
• LTX-2-19b-LoRA-Camera-Control-Dolly-Right - 下载
• LTX-2-19b-LoRA-Camera-Control-Jib-Down - 下载
• LTX-2-19b-LoRA-Camera-Control-Jib-Up - 下载
• LTX-2-19b-LoRA-Camera-Control-Static - 下载

可用的流水线

• TI2VidTwoStagesPipeline - 具有 2 倍超分辨率的生产级文本/图像到视频生成（推荐）
• TI2VidTwoStagesHQPipeline - 与上述相同的两阶段流程，但使用 res_2s 二阶采样器（步骤更少，质量更高）
• TI2VidOneStagePipeline - 单阶段生成，适用于快速原型设计
• DistilledPipeline - 使用 8 个预定义 sigma 的最快推理
• ICLoraPipeline - 视频到视频和图像到视频的转换（使用蒸馏模型）
• KeyframeInterpolationPipeline - 在关键帧图像之间进行插值
• A2VidPipelineTwoStage - 根据输入音频文件条件生成音频到视频
• RetakePipeline - 重新生成现有视频中的特定时间段

⚡ 优化建议

• 使用 DistilledPipeline - 仅使用 8 个预定义的 sigma 进行最快推理（阶段 1 8 步，阶段 2 4 步）
• 启用 FP8 量化 - 可降低内存占用：--quantization fp8-cast（命令行）或 quantization=QuantizationPolicy.fp8_cast()（Python）。fp8-cast 应与 bf16 检查点一起使用，它会实时将其降为 FP8 格式。对于配备 TensorRT-LLM 的 Hopper GPU，请使用 --quantization fp8-scaled-mm 进行 FP8 缩放矩阵乘法。fp8-scaled-mm 应与 FP8 检查点一起使用。
• 安装注意力优化库 - 使用 xFormers（uv sync --extra xformers）或针对 Hopper GPU 的 Flash Attention 3
• 使用梯度估计 - 在保持质量的同时，将推理步骤从 40 步减少到 20–30 步（参见 管道文档）
• 跳过内存清理 - 如果显存充足，可禁用各阶段之间的自动内存清理，以加快处理速度
• 选择单阶段管道 - 当不需要高分辨率时，可使用 TI2VidOneStagePipeline 进行更快的生成

✍️ LTX-2 的提示词编写

编写提示词时，应专注于对动作和场景的详细、按时间顺序的描述。包含具体的动作、外观、摄像机角度和环境细节——所有内容都应写在一个连贯的段落中。直接从动作开始，并保持描述的字面性和精确性。想象自己是一名摄影师，正在描述镜头清单。字数控制在 200 字以内。为获得最佳效果，可按照以下结构构建提示词：

• 用一句话概述主要动作
• 添加关于动作和手势的具体细节
• 精确描述角色或物体的外观
• 包括背景和环境细节
• 指定摄像机角度和运动
• 描述光线和色彩
• 注意任何变化或突发事件

如需更多提示词编写指导，请参阅 https://ltx.video/blog/how-to-prompt-for-ltx-2

自动提示词增强

LTX-2 管道支持通过 enhance_prompt 参数进行自动提示词增强。

🔌 ComfyUI 集成

如需将我们的模型与 ComfyUI 集成，请按照 https://github.com/Lightricks/ComfyUI-LTXVideo/ 中的说明操作。

📦 软件包

本仓库采用 monorepo 结构，包含三个主要软件包：

• ltx-core - 核心模型实现、推理栈及工具
• ltx-pipelines - 文本到视频、图像到视频等生成模式的高级管道实现
• ltx-trainer - LoRA、全量微调和 IC-LoRA 的训练与微调工具

每个软件包都有独立的 README 和文档。请参阅下方的 文档 部分。

📚 文档

每个软件包均包含详尽的文档：

• LTX-Core README - 核心模型实现、推理栈及工具
• LTX-Pipelines README - 高级管道实现及使用指南
• LTX-Trainer README - 训练与微调文档，附详细指南

LTX-2 快速上手指南

LTX-2 是首个基于 DiT（Diffusion Transformer）架构的音视频基础模型，支持音画同步、高保真生成及多种生产级模式。本指南帮助开发者快速在本地部署并运行该模型。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐) 或 macOS
• Python: 3.10 或更高版本
• 包管理器: 推荐使用 uv (比 pip 更快)，若未安装可通过 pip install uv 获取
• 硬件要求:
  • 推荐 NVIDIA GPU (显存建议 24GB 以上以运行完整流程)
  • 若使用 Hopper 架构显卡 (如 H100)，可启用 Flash Attention 3 优化
• 依赖库: 项目使用 uv 管理依赖，自动处理虚拟环境

注意：目前官方未提供特定的中国镜像源。国内用户下载模型文件时，建议使用国内加速服务（如 huggingface.co 的镜像站）或配置代理以确保下载速度。

安装步骤

1. 克隆代码库并配置环境

使用以下命令克隆仓库并初始化 Python 虚拟环境：

# 克隆仓库
git clone https://github.com/Lightricks/LTX-2.git
cd LTX-2

# 使用 uv 同步依赖并冻结版本
uv sync --frozen

# 激活虚拟环境
source .venv/bin/activate

(可选) 如需启用注意力机制优化以提升推理速度：

# 安装 xFormers (适用于大多数 NVIDIA GPU)
uv sync --extra xformers

2. 下载模型文件

您需要从 HuggingFace 下载必要的模型权重文件。请将下载的文件放置在项目指定的模型目录中（具体路径请参考各 Pipeline 的默认配置或通过 CLI 参数指定）。

必需的核心模型：

• 主模型检查点 (二选一):
  • ltx-2.3-22b-dev.safetensors (开发版)
  • ltx-2.3-22b-distilled.safetensors (蒸馏版，推理更快)
• 空间超分模型 (当前双阶段流程必需):
  • ltx-2.3-spatial-upscaler-x2-1.0.safetensors (2 倍超分)
  • 或 ltx-2.3-spatial-upscaler-x1.5-1.0.safetensors (1.5 倍超分)
• 文本编码器:
  • Gemma 3 (需下载 google/gemma-3-12b-it-qat-q4_0-unquantized 仓库下的所有文件)

可选增强模型 (LoRAs): 根据需求下载相机控制、动作控制或细节增强所需的 LoRA 文件（如 ltx-2.3-22b-ic-lora-union-control-ref0.5.safetensors 等）。

基本使用

LTX-2 提供了多种 Pipeline 以适应不同场景。以下是使用推荐的 双阶段文生视频流程 的最小化 Python 示例。

示例：使用 TI2VidTwoStagesPipeline 生成视频

此流程先生成低分辨率视频，再进行空间超分，适合生产级质量输出。

import torch
from ltx_pipelines import TI2VidTwoStagesPipeline
from ltx_core import QuantizationPolicy

# 1. 初始化 Pipeline
# 请确保模型文件路径正确，或使用默认加载逻辑
pipeline = TI2VidTwoStagesPipeline(
    model_path="path/to/ltx-2.3-22b-distilled.safetensors",
    upscaler_path="path/to/ltx-2.3-spatial-upscaler-x2-1.0.safetensors",
    text_encoder_path="path/to/gemma-3-model",
    # 开启 FP8 量化以降低显存占用 (需 bf16 检查点)
    quantization=QuantizationPolicy.fp8_cast() 
)

# 将模型移至 GPU
pipeline.to("cuda")

# 2. 构建提示词
# LTX-2 偏好详细、按时间顺序描述的动作和场景，类似电影分镜脚本
prompt = (
    "A cinematic shot of a cyberpunk city street at night, raining heavily. "
    "Neon signs reflect on the wet pavement. A lone figure in a trench coat walks slowly "
    "from left to right, looking up at a holographic advertisement. "
    "Camera pans smoothly following the figure. Lighting is high contrast with blue and pink hues."
)

# 3. 执行生成
video_output = pipeline(
    prompt=prompt,
    num_inference_steps=25,  # 结合梯度估计可减少步数
    height=720,
    width=1280,
    frame_rate=24,
    duration=5.0,
    enhance_prompt=True  # 启用自动提示词增强
)

# 4. 保存结果
video_output.save("output_video.mp4")
print("视频生成完毕：output_video.mp4")

性能优化建议

• 极速推理: 若追求速度，可使用 DistilledPipeline，仅需 8 个采样步数（第一阶段 8 步，第二阶段 4 步）。
• 显存优化: 对于显存有限的设备，务必启用 --quantization fp8-cast 参数。
• 单阶段模式: 若不需要高分辨率输出，可使用 TI2VidOneStagePipeline 进行快速原型验证。

更多高级用法（如音频生成视频、关键帧插值、ComfyUI 集成）请参阅各子包的详细文档。