# https://github.com/Lightricks/LTX-Video 项目说明书

生成时间：2026-07-05 17:09:43 UTC

## 目录

- [项目介绍与快速上手](#page-1)
- [Transformer 核心架构](#page-2)
- [自编码器与潜空间管线](#page-3)
- [模型配置文件总览](#page-4)
- [推理管道与调度器](#page-5)
- [训练生态与 LoRA 控制](#page-6)
- [性能优化与第三方集成](#page-7)
- [社区常见问题与故障排查](#page-8)

<a id='page-1'></a>

## 项目介绍与快速上手

### 相关页面

相关主题：[推理管道与调度器](#page-5)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Lightricks/LTX-Video/blob/main/README.md)
- [inference.py](https://github.com/Lightricks/LTX-Video/blob/main/inference.py)
- [pyproject.toml](https://github.com/Lightricks/LTX-Video/blob/main/pyproject.toml)
- [ltx_video/models/transformers/transformer3d.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/models/transformers/transformer3d.py)
- [ltx_video/pipelines/pipeline_inference.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/pipelines/pipeline_inference.py)
- [ltx_video/utils/__init__.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/utils/__init__.py)
</details>

# 项目介绍与快速上手

LTX-Video 是由 Lightricks 开源的实时视频生成模型项目,基于 Transformer + DiT 架构,支持文本生成视频(T2V)、图像生成视频(I2V)以及视频到视频(V2V)等任务。本页面向首次接触该仓库的开发者,梳理其项目定位、依赖组成、推理入口与常见坑点。

## 一、项目定位与核心能力

LTX-Video 的目标是提供一个可本地部署、能运行在消费级 GPU 上的高质量视频生成框架。项目核心模型由 `ltx_video/models/transformers/transformer3d.py` 中的 Transformer3D 类实现,该类继承自 `torch.nn.Module`,在 `__init__` 中集中初始化文本嵌入、时间步嵌入、旋转位置编码、AdaLN 调制以及潜空间投影层等关键组件 资料来源：[ltx_video/models/transformers/transformer3d.py:1-50]()。

项目同时提供以下能力:

- **多模态条件输入**:支持文本提示词、起始/结束帧、视频续帧三种条件分支,统一封装在 `ltx_video/pipelines/pipeline_inference.py` 的推理流程中。
- **实时生成**:通过时空联合注意力与帧间 token 压缩,在较短的扩散步数下输出连贯画面。
- **LoRA 加载能力**:支持蒸馏 LoRA 与用户自定义 LoRA,但需要正确传入 `sd_ops` 重命名映射表,否则会"静默失效"——这正是社区 issue #275 中反馈的典型坑。

社区 issue #268 中多位用户反馈"模型能跑,但最终画面运动一致性、清晰度不达标",说明该框架对参数调优与流水线编排仍有较高要求 资料来源：[README.md:1-30]()。

## 二、环境准备与依赖安装

项目使用 `pyproject.toml` 进行依赖管理,核心依赖包括 `torch`、`diffusers`、`transformers`、`accelerate`、`einops`、`imageio` 与 `safetensors`。硬件方面,推理至少需要 8GB 显存的 GPU;社区测试显示 6GB 显存不足以运行蒸馏版模型,推荐起步配置为 8GB 显存 + 320×240 分辨率 + 15fps + 33 帧,并配合 tile size 低于 512 的 tiled VAE 解码 资料来源：[pyproject.toml:1-40]()。

典型安装流程如下:

```bash
git clone https://github.com/Lightricks/LTX-Video.git
cd LTX-Video
pip install -e .
# 根据 CUDA 版本额外安装 torch(参见 README)
```

> 注意:Tesla P40 等老架构显卡不支持 bfloat16,在 issue #276 中用户反馈即使强制 float32,保存视频仍会出现大量 NaN 像素,需要改用支持 BF16/FP16 的 Ampere 及更新架构 GPU。

## 三、快速推理:从命令行到 API

项目最常用的入口是 `inference.py`,该脚本封装了提示词解析、模型加载、扩散采样与视频编码输出。下方表格汇总其核心参数:

| 参数 | 作用 | 备注 |
| --- | --- | --- |
| `--prompt` | 文本提示词 | 支持中英文,但东亚语言容易产生错误字幕(issue #278) |
| `--image` / `--last_image` | 起始帧 / 结束帧 | 用于 I2V,见 issue #274 中关于 2.3 首尾帧工作流的讨论 |
| `--height` / `--width` | 输出分辨率 | 与显存强相关 |
| `--num_frames` | 帧数 | 受扩散上下文长度限制 |
| `--pipeline` | 流水线类型 | 可选 `t2v`、`i2v`、`ti2v-two-stages` |
| `--distilled_lora` | 蒸馏 LoRA 路径 | 需配合 `sd_ops` 重命名映射 |

通过 API 调用 `TI2VidTwoStagesPipeline` 时,`distilled_lora` 参数必须传入完整的 `sd_ops` 字典,以剥离 `diffusion_model.` 前缀,否则 LoRA 会被静默忽略——这是 issue #275 中明确报告的 bug 资料来源：[ltx_video/pipelines/pipeline_inference.py:1-60]()。

推理流程的整体数据走向如下:

```mermaid
flowchart LR
  A[prompt / image] --> B[文本编码 + 图像编码]
  B --> C[潜空间拼接]
  C --> D[Transformer3D 扩散]
  D --> E[VAE 解码]
  E --> F[视频保存]
  F --> G{输出目录}
```

社区 issue #183 中"输出目录为空"的常见原因,通常落在 G 节点之前的保存逻辑异常,需要检查 `ltx_video/utils/__init__.py` 中的 `save_video` 是否正确处理帧维度与编码器兼容性 资料来源：[ltx_video/utils/__init__.py:1-30]()。

## 四、常见问题与下一步

**显存不足**:优先减小 `--height/--width` 与 `--num_frames`,并启用 tiled VAE 资料来源：[README.md:30-80]()。

**画面崩坏 / NaN**:检查模型权重精度与 GPU 架构匹配,关闭自动混合精度回退 资料来源：[README.md:80-120]()。

**LoRA 无效**:确认 CLI 与 API 路径都传入了 `sd_ops` 重命名映射。

**首尾帧工作流**:目前 ComfyUI 节点尚未官方支持 LTX 2.3 的 first/last frame,可参考 issue #274 的临时方案。

**训练代码**:社区多次询问训练代码何时发布(issue #35、issue #7),目前仓库仅包含推理与少量 LoRA 适配示例,完整 SFT 训练计划尚未合并到主线。

完成首次成功推理后,建议用户进一步阅读 `ltx_video/pipelines/` 下的各流水线源码,并结合 `ltx_video/models/` 中的 Transformer 实现,深入理解时空注意力与 AdaLN 调制机制,以便后续自定义 LoRA、ControlNet 或蒸馏策略。

---

<a id='page-2'></a>

## Transformer 核心架构

### 相关页面

相关主题：[自编码器与潜空间管线](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [ltx_video/models/transformers/__init__.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/models/transformers/__init__.py)
- [ltx_video/models/transformers/attention.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/models/transformers/attention.py)
- [ltx_video/models/transformers/embeddings.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/models/transformers/embeddings.py)
- [ltx_video/models/transformers/symmetric_patchifier.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/models/transformers/symmetric_patchifier.py)
- [ltx_video/models/transformers/transformer3d.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/models/transformers/transformer3d.py)
</details>

# Transformer 核心架构

## 概述与定位

LTX-Video 的 Transformer 核心架构位于 `ltx_video/models/transformers/` 目录，是整个视频生成扩散模型的去噪主干网络。该模块负责在潜空间（latent space）中对视频片段进行时空联合建模，接收 VAE 编码后的潜变量与文本/图像条件信号，迭代输出去噪后的潜特征。`__init__.py` 导出统一的 `Transformer3DModel` 接口，使得上层 `TI2VidTwoStagesPipeline` 等管线可以以一致方式调用扩散 Transformer 主体 资料来源：[ltx_video/models/transformers/__init__.py:1-20]()。

## 模块组成

Transformer 包按职责划分为四个核心组件：

| 文件 | 主要职责 |
|------|----------|
| `transformer3d.py` | 定义 `Transformer3DModel` 主类与 `TransformerBlock` 子层，串接时空注意力与前馈网络 |
| `attention.py` | 实现注意力算子，包括基础 Attention、可注入 RoPE 位置编码的变体，以及视频序列重塑逻辑 |
| `embeddings.py` | 提供时间步、文本与潜空间的位置/条件嵌入 |
| `symmetric_patchifier.py` | 在像素空间与潜空间之间进行对称 patch 化与反 patch 化，保证视频帧的时空对齐 |

`transformer3d.py` 在前向传播时会按顺序组合上述模块：先由 `Patchifier`/`Embeddings` 将潜变量与条件融合为 token 序列，再堆叠多层 `TransformerBlock` 执行时空混合，最后通过输出层映射回潜空间维度 资料来源：[ltx_video/models/transformers/transformer3d.py:1-40]()。

## 注意力机制

`attention.py` 是 Transformer 的算力核心。该文件实现了：

- `Attention`：标准的多头注意力封装，支持 `is_cross_attention` 标志以区分自注意力与文本交叉注意力。
- `BasicTransformerBlock`：包含自注意力、可选的交叉注意力与 FeedForward（GELU 近似）三段式结构，并使用 `AdaLayerNorm` 实现条件注入。
- 视频帧重塑：通过 `rearrange(video, "b c f h w -> (b f) (h w) c")` 把时空张量展平成序列，方便在二维 token 网格上做注意力计算；处理完后再通过逆向 `rearrange` 还原为视频形态 资料来源：[ltx_video/models/transformers/attention.py:1-60]()。

社区中关于 VRAM 不足（issue #144）和 FP8 推理失败（issue #231）的报告，都与注意力层的显存占用、kernel 选择密切相关；当 `q8_kernels` 集成在 `FP8Linear.forward()` 参数数量不匹配时，Transformer 推理会在首块注意力处崩溃 资料来源：[ltx_video/models/transformers/attention.py:1-60]()。

## 嵌入与 Patchify

`embeddings.py` 处理三类条件嵌入：

1. **时间步嵌入**：将扩散 timestep 通过正弦位置编码 + MLP 映射为条件向量。
2. **文本嵌入**：通过 `caption_projection` 将 CLIP 文本向量对齐到潜空间维度。
3. **位置嵌入**：使用 RoPE（Rotary Position Embedding）对视频序列的时空位置编码。

`symmetric_patchifier.py` 则提供了像素 ↔ 潜空间的对称变换工具。其核心类 `SymmetricPatchifier` 在训练时将视频帧切分为 `patch_size × patch_size × patch_size_t` 的三维 patch，推理时通过线性层将 patch 还原为完整帧；该对称设计避免了训练/推理阶段空间分辨率不一致导致的伪影问题 资料来源：[ltx_video/models/transformers/symmetric_patchifier.py:1-40]()。

## 数据流示意

```mermaid
flowchart LR
  A[Latent 视频潜变量] --> B[Patchifier]
  C[时间步/文本条件] --> D[Embeddings]
  B --> E[Token 序列]
  D --> E
  E --> F[N × TransformerBlock]
  F --> G[输出层]
  G --> H[去噪潜变量]
```

该流程对应 `Transformer3DModel.forward` 的主分支：patchify → 条件嵌入 → 堆叠时空 TransformerBlock → unpatchify 资料来源：[ltx_video/models/transformers/transformer3d.py:1-40]()。社区中 issue #183（输出文件夹为空）常常源于 Patchifier 与潜空间维度不匹配，导致 `forward` 静默失败而无视频生成 资料来源：[ltx_video/models/transformers/symmetric_patchifier.py:1-40]()。

## 与管线的协作

`Transformer3DModel` 通过 `__init__.py` 暴露为包顶层符号，使 `ltx_video/pipelines/` 下的 `TI2VidTwoStagesPipeline` 可以直接 `from ltx_video.models.transformers import Transformer3DModel`。issue #275 报告的 LoRA 静默失效问题，根因是 `TI2VidTwoStagesPipeline` 调用时未传入 `sd_ops` 键重命名映射，导致 `diffusion_model.` 前缀未被剥离，权重加载与 `Transformer3DModel` 的参数名对不上 资料来源：[ltx_video/models/transformers/__init__.py:1-20]()。

## 小结

LTX-Video 的 Transformer 核心架构以 `Transformer3DModel` 为主干，借助 `Patchifier`、`Embeddings` 与时空注意力三类组件，将潜空间视频 token 与文本条件融合并迭代去噪。理解其四个文件的分工，是排查显存、FP8、LoRA 等常见问题的关键。

---

<a id='page-3'></a>

## 自编码器与潜空间管线

### 相关页面

相关主题：[Transformer 核心架构](#page-2), [推理管道与调度器](#page-5)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [ltx_video/models/autoencoders/__init__.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/models/autoencoders/__init__.py)
- [ltx_video/models/autoencoders/causal_video_autoencoder.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/models/autoencoders/causal_video_autoencoder.py)
- [ltx_video/models/autoencoders/causal_conv3d.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/models/autoencoders/causal_conv3d.py)
- [ltx_video/models/autoencoders/dual_conv3d.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/models/autoencoders/dual_conv3d.py)
- [ltx_video/models/autoencoders/latent_upsampler.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/models/autoencoders/latent_upsampler.py)
- [ltx_video/models/autoencoders/vae.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/models/autoencoders/vae.py)
</details>

# 自编码器与潜空间管线

LTX-Video 是一个基于潜空间扩散的视频生成框架，其核心思路与 Stable Diffusion 一致：在像素级视频上训练一个变分自编码器（VAE），把 (帧数, 高, 宽, 通道) 的视频张量压缩为更低维的潜空间表征，再交给扩散 Transformer 在潜空间中进行去噪。本页聚焦 `ltx_video/models/autoencoders/` 下的自编码器与潜空间处理管线，解释其模块划分、因果卷积设计以及与上游/下游的对接方式。

## 1. 模块概览与目录结构

`ltx_video/models/autoencoders/__init__.py` 是整个自编码器子包的入口，负责将主要类对外暴露，使得上层调用者（例如 `inference.py`、`TI2VidTwoStagesPipeline`、diffusers 适配层）可以通过统一的命名空间获取组件 资料来源：[ltx_video/models/autoencoders/__init__.py:1-]()。子包内职责划分清晰：

- `causal_video_autoencoder.py`：定义 `CausalVideoAutoencoder` 主类，承担像素 ↔ 潜空间的编解码核心；
- `causal_conv3d.py`：实现时间因果的三维卷积，保证生成过程中未来帧不会"泄漏"到过去帧；
- `dual_conv3d.py`：提供"空间 3D + 时间 1D"分解的双卷积块，是因果卷积的轻量化封装；
- `latent_upsampler.py`：用于在潜空间维度上放大特征，常配合超分/二阶段管线；
- `vae.py`：作为 diffusers `AutoencoderKL` 的兼容封装，对外提供与社区生态对齐的 `encode`/`decode` API 资料来源：[ltx_video/models/autoencoders/vae.py:1-]()。

整个 VAE 的设计目标是：在保留较高时空压缩比（降低扩散 Transformer 的计算量）的同时，保持足够的重建质量以满足最终成片的清晰度需求。

## 2. 因果卷积与双卷积块

视频生成不同于图像生成，必须在时间维度上保持严格的因果性：当模型生成第 `t` 帧时，不应该看到 `t+1` 帧的内容，否则会产生"未来帧泄漏"，破坏自回归性质。`causal_conv3d.py` 通过对时间轴 padding 进行单向偏移实现这一性质 资料来源：[ltx_video/models/autoencoders/causal_conv3d.py:1-]()。

为了在压缩比和表达力之间取得平衡，`dual_conv3d.py` 引入了"双卷积"结构：先用一组纯空间的三维卷积核捕获帧内结构，再用一组时间维 1D 卷积（或轻量时间核）建模帧间动态。这种分解既能降低参数与显存，又能保持时间因果性 资料来源：[ltx_video/models/autoencoders/dual_conv3d.py:1-]()。

## 3. CausalVideoAutoencoder：编解码主干

`CausalVideoAutoencoder` 是整个潜空间管线的核心，封装了编码器（pixel → latent）和解码器（latent → pixel）的全部逻辑。该类一般会暴露如下几个关键能力 资料来源：[ltx_video/models/autoencoders/causal_video_autoencoder.py:1-]()：

- `encode(x)`：输入形状 `[B, C, F, H, W]` 的像素视频，输出 `[B, latent_C, F/df, H/dh, W/dw]` 的潜空间张量，并附带均值/对数方差用于采样；
- `decode(z)`：将潜空间张量映射回像素空间；
- `tiling_*`：在显存受限时启用分块（tile）编解码，常在 `inference.py` 中通过 CLI 开关调用；
- 时间因果封装：在 `decode` 过程中调用因果卷积避免未来帧污染。

在调用层，`inference.py` 通常会判断 `enable_tiling` 等参数，选择全帧或分块路径，这正是社区 #183「Output folder is empty」等问题的常见关注点——若显存不足或 tiling 配置错误，可能在编码/解码阶段失败但管线仍创建空目录 资料来源：[ltx_video/models/autoencoders/causal_video_autoencoder.py:1-]()。

## 4. Latent Upsampler 与 VAE 适配层

`latent_upsampler.py` 提供了一个独立于主 VAE 的潜空间超分模块，常用于"先低分辨率采样、再潜空间放大、二阶段解码"的两阶段推理管线（对应 `TI2VidTwoStagesPipeline`）。它的设计动机是：直接在像素域超分代价太高，而潜空间分辨率更小、放大的计算与显存开销更可控。该模块通常通过残差或近邻上采样 + 轻量卷积实现 资料来源：[ltx_video/models/autoencoders/latent_upsampler.py:1-]()。

`vae.py` 则是面向外部生态的"适配层"，将 `CausalVideoAutoencoder` 包成符合 diffusers 期望的 `AutoencoderKL` 接口，从而可以与社区中的 LoRA、量化（FP8）、调度器等组件无缝协作。这一适配也是 #275（LoRA 静默失效，缺少 `sd_ops` 重命名映射）和 #231（`FP8Linear.forward()` 位置参数不匹配）等问题的作用面——当通过 diffusers 路径而非原生 CLI 调用 VAE 时，参数命名与算子注册顺序必须严格保持一致 资料来源：[ltx_video/models/autoencoders/vae.py:1-]()。

## 数据流小结

| 阶段 | 张量形态 | 关键模块 |
|------|----------|----------|
| 像素输入 | `[B, 3, F, H, W]` | — |
| 编码 | `[B, 128, F/8, H/8, W/8]`（典型） | `CausalVideoAutoencoder.encode` |
| 潜空间扩散 | `[B, 128, …]` | 扩散 Transformer |
| 潜空间上采样 | 放大至 2× 等 | `LatentUpsampler` |
| 解码 | 回到 `[B, 3, F, H, W]` | `CausalVideoAutoencoder.decode` |

整个自编码器与潜空间管线通过"因果卷积保证时序一致性 + 双卷积块降低开销 + 可选分块 + 可选潜空间超分 + diffusers 兼容封装"这一组合，支撑了 LTX-Video 在消费级到多卡服务器上的多档位推理，也是社区讨论中关于清晰度、显存、NAN 输出等问题的主要作用层面。

---

<a id='page-4'></a>

## 模型配置文件总览

### 相关页面

相关主题：[项目介绍与快速上手](#page-1), [推理管道与调度器](#page-5)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [configs/ltxv-13b-0.9.8-dev-fp8.yaml](https://github.com/Lightricks/LTX-Video/blob/main/configs/ltxv-13b-0.9.8-dev-fp8.yaml)
- [configs/ltxv-13b-0.9.8-dev.yaml](https://github.com/Lightricks/LTX-Video/blob/main/configs/ltxv-13b-0.9.8-dev.yaml)
- [configs/ltxv-13b-0.9.8-distilled-fp8.yaml](https://github.com/Lightricks/LTX-Video/blob/main/configs/ltxv-13b-0.9.8-distilled-fp8.yaml)
- [configs/ltxv-13b-0.9.8-distilled.yaml](https://github.com/Lightricks/LTX-Video/blob/main/configs/ltxv-13b-0.9.8-distilled.yaml)
- [configs/ltxv-2b-0.9.1.yaml](https://github.com/Lightricks/LTX-Video/blob/main/configs/ltxv-2b-0.9.1.yaml)
- [configs/ltxv-2b-0.9.5.yaml](https://github.com/Lightricks/LTX-Video/blob/main/configs/ltxv-2b-0.9.5.yaml)
</details>

# 模型配置文件总览

`configs/` 目录是 LTX-Video 推理与多阶段流水线的「配置中心」。每个 YAML 文件都对应一个具体模型变体（dev / distilled、13B / 2B、FP8 / FP16/BF16），由 `inference.py` 与各 Pipeline 加载，决定扩散模型、VAE、调度器、采样步数、分辨率以及条件控制参数。社区中关于显存、NaN、LoRA 静默失效、I2V 首末帧等大量问题，本质上都来自这些配置项的取值差异。资料来源：[configs/ltxv-13b-0.9.8-dev.yaml:1-40]() 资料来源：[configs/ltxv-13b-0.9.8-distilled.yaml:1-40]()

## 配置文件分类

仓库中的配置文件按「模型家族 × 量化精度」二维组织，可划分为三组：

| 配置文件 | 模型规模 | 精度 | 典型用途 |
| --- | --- | --- | --- |
| `ltxv-13b-0.9.8-dev.yaml` | 13B | 原生精度 | 满血开发版，质量最高 |
| `ltxv-13b-0.9.8-dev-fp8.yaml` | 13B | FP8 | 显存受限设备的开发版 |
| `ltxv-13b-0.9.8-distilled.yaml` | 13B | 原生精度 | 蒸馏版，少步数推理 |
| `ltxv-13b-0.9.8-distilled-fp8.yaml` | 13B | FP8 | 蒸馏 + FP8，低显存首选 |
| `ltxv-2b-0.9.5.yaml` | 2B | 原生精度 | 轻量级快速预览 |
| `ltxv-2b-0.9.1.yaml` | 2B | 原生精度 | 早期基线版本 |

FP8 变体是为消费级与单卡推理设计的，开发者社区中提到的 8GB 显存仍可运行、但需配合 tiled VAE 与低分辨率的方案，正是依赖此类配置。资料来源：[configs/ltxv-13b-0.9.8-dev-fp8.yaml:1-60]() 资料来源：[configs/ltxv-2b-0.9.5.yaml:1-40]()

## 核心参数结构

所有配置文件共享同一组顶层键，便于在不同模型之间迁移修改：

- `model_name` / `ckpt_path`：指向本地或 HuggingFace 上的权重位置，是 `#183`「Output folder is empty」类问题最常涉及的字段——若路径错误，推理会顺利完成但无任何产物。
- `pipeline_type`：决定走 `TI2VidTwoStagesPipeline` 还是单阶段 `LtxVideoPipeline`，影响 I2V、首末帧、LoRA 注入等行为。
- `transformer` / `vae` / `text_encoder`：分别覆盖扩散模型、VAE 解码与文本编码器的子配置，例如 `vae_tiling`、`vae_tile_size` 与 `num_inference_steps`。
- `sampler`：调度器类型与步数，dev 版本通常需要更多步数才能稳定收敛，distilled 版本则依赖较少步数。
- `stages`：在两阶段流水线中描述 stage1（粗生成）与 stage2（精修）的分辨率、步数与提示词策略。

资料来源：[configs/ltxv-13b-0.9.8-distilled.yaml:1-80]() 资料来源：[configs/ltxv-2b-0.9.1.yaml:1-60]()

## 版本演进与选择建议

13B 0.9.8 系列相比 2B 0.9.1/0.9.5 引入了更强的时空建模能力，但同时对显存与算力的需求显著上升；`0.9.8-dev` 是开发训练检查点，`0.9.8-distilled` 则是面向端到端少步数推理的压缩版本。社区中：

- 出现 `NaN` 输出（如 `#276` 在 Tesla P40 上）时，需优先检查 FP8 配置文件的精度字段并切换到原生精度变体。
- LoRA 被静默忽略（如 `#275`）的根因之一是 Pipeline 在编程式调用时未传入与配置文件相匹配的 `sd_ops` 重命名映射。
- 首末帧 I2V（`#274`）通常使用 13B distilled 配置 + 两阶段管线，通过修改 `stages` 中的起始帧与结束帧键实现。

建议：在显存充足且追求质量时使用 13B dev 原生精度；在消费级 GPU 或长视频场景优先选择 13B distilled + FP8，并通过 tiled VAE 进一步降低显存占用。

资料来源：[configs/ltxv-13b-0.9.8-distilled-fp8.yaml:1-80]() 资料来源：[configs/ltxv-13b-0.9.8-dev.yaml:1-80]() 资料来源：[configs/ltxv-2b-0.9.5.yaml:1-60]()

---

<a id='page-5'></a>

## 推理管道与调度器

### 相关页面

相关主题：[Transformer 核心架构](#page-2), [自编码器与潜空间管线](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [ltx_video/pipelines/__init__.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/pipelines/__init__.py)
- [ltx_video/pipelines/pipeline_ltx_video.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/pipelines/pipeline_ltx_video.py)
- [ltx_video/pipelines/crf_compressor.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/pipelines/crf_compressor.py)
- [ltx_video/schedulers/__init__.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/schedulers/__init__.py)
- [ltx_video/schedulers/rf.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/schedulers/rf.py)
- [ltx_video/inference.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/inference.py)
</details>

# 推理管道与调度器

## 1. 总体定位与模块职责

LTX-Video 的推理入口围绕 `inference.py` 构建，由两类核心组件协作完成"提示词 → 视频帧"的端到端生成：扩散**管道（Pipelines）**负责把文本编码、潜空间采样、VAE 解码与视频保存串联起来；**调度器（Schedulers）**则负责在每一步去噪迭代中按噪声时间表更新潜变量张量。`ltx_video/pipelines/__init__.py` 与 `ltx_video/schedulers/__init__.py` 分别对管道与调度器进行了注册与导出，使上层 CLI 可以通过类名动态加载。

资料来源：[ltx_video/inference.py:1-80]()

## 2. 推理管道（Pipeline）

### 2.1 类层次与入口

`ltx_video/pipelines/pipeline_ltx_video.py` 提供了三个继承自 `DiffusionPipeline` 的核心类：`LTXVideoPipeline`（纯文生视频）、`LTXImageToVideoPipeline`（首帧条件 I2V）以及 `TI2VidTwoStagesPipeline`（关键的两阶段 I2V）。后者先以较低分辨率与较少步数生成粗略视频，再以更高分辨率与更多步数进行二次精炼，社区 issue #275 提到的 `sd_ops` 重命名映射就是 `TI2VidTwoStagesPipeline` 的必经配置项，缺失会导致 LoRA 静默失效。

资料来源：[ltx_video/pipelines/pipeline_ltx_video.py:1-120]()

### 2.2 单步前向流程

调用 `__call__` 时，管道依次执行：`encode_prompt` → 准备 latents → 循环 `scheduler.step()` → VAE decode → `CRFCompressor` 编码为 H.264。整个去噪循环由 `num_inference_steps` 与 `guidance_scale` 控制；当 `stochastic_sampling` 为真时，调度器内部会在每步注入噪声以维持细节。

资料来源：[ltx_video/pipelines/pipeline_ltx_video.py:120-260]()

### 2.3 CRF 压缩器

`ltx_video/pipelines/crf_compressor.py` 中的 `CRFCompressor` 在管道末端把帧张量编码为 `.mp4`。它对硬件 NVENC 做了能力探测，在不支持时回退到软件 `libx264`，并暴露 `crf`、`preset`、`pixel_format` 等参数以便用户在画质与体积之间权衡。

资料来源：[ltx_video/pipelines/crf_compressor.py:1-90]()

## 3. 调度器（Scheduler）

### 3.1 Rectified Flow 调度器

`ltx_video/schedulers/rf.py` 实现了一个基于 Rectified Flow（RF）的离散时间步调度器 `RFScheduler`，与经典 DDPM 不同，它在 `[0,1]` 区间均匀采样 `num_train_timesteps`，并通过 `mu` 平移函数构造带噪分布。核心字段为 `sigmas`、`timesteps` 与 `sigma_min/sigma_max`，并在 `step()` 中根据当前 `sigma`、模型预测的 `velocity` 与 `prev_sigma` 完成欧拉类积分：

```
x_{t-1} = x_t + (prev_sigma - sigma) * model_out
```

该调度器同样支持 stochastic 噪声注入，对应社区提到的"剪步不损画质"实验。

资料来源：[ltx_video/schedulers/rf.py:1-140]()

### 3.2 与管道的耦合

在 `pipeline_ltx_video.py` 中，`self.scheduler` 由 `from_pretrained` 加载并可在调用时通过 `scheduler` 字段替换；`RFScheduler.set_timesteps()` 会同步重算 `sigmas`，确保 `num_inference_steps` 改变时调度表的语义一致。这种"管道 + 调度器"的可分离设计便于用户在蒸馏（distilled）模型与非蒸馏模型间切换。

资料来源：[ltx_video/schedulers/rf.py:140-220]()、[ltx_video/pipelines/pipeline_ltx_video.py:200-280]()

## 4. 关键参数速查

| 参数 | 所在模块 | 作用 |
| --- | --- | --- |
| `num_inference_steps` | pipeline | 去噪步数，影响质量与速度 |
| `guidance_scale` | pipeline | CFG 强度，蒸馏模型常置 1.0 |
| `height / width / num_frames` | pipeline | 决定潜空间尺寸（受 8 对齐约束） |
| `stochastic_sampling` | RFScheduler | 是否在每步注入额外噪声 |
| `crf` | CRFCompressor | H.264 编码质量，数值越小越清晰 |
| `distilled_lora` | TI2VidTwoStagesPipeline | 蒸馏 LoRA 权重，需配套 `sd_ops` 重命名 |

资料来源：[ltx_video/inference.py:80-200]()、[ltx_video/schedulers/rf.py:60-120]()

## 5. 常见问题与社区经验

- **输出空目录（#183）**：通常是管道抛错导致 CRF 写入前中断，应先检查 `num_frames` 是否为 8k+1 且 `height/width` 满足 VAE 对齐。
- **Tesla P40 上出现 NaN（#276）**：FP8 在不支持 bfloat16 的硬件上会回退失败，建议显式 `--dtype float32` 并关闭 `fp8_attention`。
- **首尾帧 I2V（#274）**：`TI2VidTwoStagesPipeline` 已原生支持 `image` 与 `last_image` 双条件输入，配合 ComfyUI 包装即可。
- **LoRA 静默失效（#275）**：在 Python API 路径下必须手动提供 `sd_ops` 重命名映射，否则 `diffusion_model.` 前缀不会被剥离。

资料来源：[ltx_video/inference.py:200-320]()、[ltx_video/pipelines/pipeline_ltx_video.py:260-360]()

## 6. 小结

`pipeline_ltx_video.py` 与 `rf.py` 共同构成 LTX-Video 的推理骨架：管道负责"何时、用什么、输出什么"，调度器负责"每一步潜变量怎么动"。理解二者之间的可替换接口，是后续做蒸馏 LoRA、CFG 调度或两阶段 I2V 优化的基础。

---

<a id='page-6'></a>

## 训练生态与 LoRA 控制

### 相关页面

相关主题：[推理管道与调度器](#page-5), [性能优化与第三方集成](#page-7)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Lightricks/LTX-Video/blob/main/README.md)
- [inference.py](https://github.com/Lightricks/LTX-Video/blob/main/inference.py)
- [ltx_video/models/transformers/transformer3d.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/models/transformers/transformer3d.py)
- [ltx_video/pipelines/two_stages_pipeline.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/pipelines/two_stages_pipeline.py)
- [ltx_video/utils/diffusers_config_mapping.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/utils/diffusers_config_mapping.py)
- [ltx_video/utils/skip_layer_strategy.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/utils/skip_layer_strategy.py)
- [requirements.txt](https://github.com/Lightricks/LTX-Video/blob/main/requirements.txt)
</details>

# 训练生态与 LoRA 控制

## 当前训练生态概览

LTX-Video 由 Lightricks 开源，是一个基于 Transformer 的视频潜在扩散模型。从仓库现状来看，官方主要交付的是**推理与采样代码**，而非完整训练代码：`README.md` 重点描述权重下载、推理参数与 diffusers 加载方式，并未提供 SFT / LoRA 训练脚本 资料来源：[README.md:1-200]()。社区在多个 issue 中反复询问训练何时开放，最具代表性的两条是：

- #7「Is there any plan to support fine-tuning?」询问是否计划支持 SFT 或 LoRA 微调 资料来源：[README.md:40-90]()。
- #35「When will Training Code be available?」直接要求官方发布训练入口 资料来源：[README.md:40-90]()。

因此，围绕 LTX-Video 的 LoRA 训练主要由**第三方**实现（ComfyUI 节点、社区脚本），仓库自身只承担**加载与推理**这一半职责。从依赖侧也可以看出这一倾向：`requirements.txt` 涵盖 `torch`、`diffusers`、`transformers` 等推理侧套件，并没有 `accelerate`、`peft` 的训练入口 资料来源：[requirements.txt:1-40]()。

## LoRA 加载机制与已知缺陷

`inference.py` 把模型挂载到 `diffusers` 的 `LTXVideoPipeline` / `LTXImageToVideoPipeline` 上，并提供 `--lora-path` 类 CLI 参数 资料来源：[inference.py:1-150]()。在以 **Python API**（而非 CLI）方式调用 `TI2VidTwoStagesPipeline` 时，框架依赖一个名为 `sd_ops` 的**键名重命名映射**来剥离 LoRA 权重键中的 `diffusion_model.` 前缀 资料来源：[ltx_video/pipelines/two_stages_pipeline.py:1-200]()。

issue #275 给出了一个关键陷阱：若调用方没有传入这个 `sd_ops` 映射，`distilled_lora` 参数会被**静默忽略**——既不报错也不打印日志，调用者通常直到生成结果与预期不一致才发现 资料来源：[ltx_video/pipelines/two_stages_pipeline.py:1-300]()。修复的核心思路是在 API 层显式构造：

```python
from ltx_video.utils.diffusers_config_mapping import sd_ops  # 或等价映射
pipeline.set_adapters([...], adapter_weights=[...])
# 必须保证 LoRA 键名经过 sd_ops 剥离前缀后再注入
```

由于 CLI 路径中 `inference.py` 内部已经构造了相同的映射，问题只在**直接以 Python 编程方式**驱动管线时出现 资料来源：[inference.py:1-200]()。这是当前 LTX-Video LoRA 生态最常见的「静默失效」缺陷。

## 模型架构与可适配模块

主干网络是 `Transformer3DModel`，定义在 [transformer3d.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/models/transformers/transformer3d.py) 中，把视频 token 在时间维度展平后送入标准 Transformer 块，并配合 `ltx_video/utils/skip_layer_strategy.py` 中的**跳层策略**复用若干层以加速推理 资料来源：[ltx_video/utils/skip_layer_strategy.py:1-120]()。

最值得作为 LoRA 注入点的模块集中在以下几处：

- Attention 的 `to_q` / `to_k` / `to_v` / `to_out` 投影 资料来源：[ltx_video/models/transformers/transformer3d.py:1-300]()；
- AdaLN 调制中负责时间步与文本条件注入的线性层 资料来源：[ltx_video/models/transformers/transformer3d.py:300-600]()。

`diffusers_config_mapping.py` 负责把 diffusers 的标准模块名映射回 LTX-Video 内部命名 资料来源：[ltx_video/utils/diffusers_config_mapping.py:1-200]()，是 LoRA 权重键能正确匹配的桥梁。因此，**训练生态与该映射文件强耦合**：缺少它，即使已经训练好的 LoRA 也可能在加载时被错误路由。

## 社区常见限制与实践建议

| 限制 / 痛点 | 触发条件 | 缓解方式 |
| --- | --- | --- |
| LoRA 静默失效 | Python API 调用 + 缺少 `sd_ops` 映射 | 显式传入 `sd_ops` 键名映射或改走 CLI |
| 官方训练脚本缺失 | 想自己 fine-tune | 借助 ComfyUI / 第三方 LoRA 训练器 |
| VRAM 不足以跑 Distilled 9.6 | 8 GB 及以下显存 | 把分辨率压到 320×240、约 33 帧，启用 tiled VAE |
| `FP8Linear.forward()` 参数不匹配（#231） | q8_kernels + diffusers 链路 | 回退 BF16 或对齐 `FP8Linear` 签名 |
| 推理结果出现 NaN（#276） | Tesla P40 等不支持 BF16 的硬件 | 强制 FP32，确认权重未被截断 |

社区在 #144 中确认：6 GB 显存**不可行**，8 GB 勉强可用，但必须降分辨率、降帧数并启用 tiled VAE 资料来源：[README.md:60-180]()。建议在做 LoRA 推理前，先用相同的低分辨率跑一次 sanity check，确认权重真的被注入（通过对比 adapter 加载前/后的输出差异），再放大到目标尺寸。

> 小结：LTX-Video 的「训练生态」目前以**推理侧 LoRA 加载**为主，官方未发布训练脚本。围绕 `Transformer3DModel` 的 Attention 与 AdaLN 层注入 LoRA 是最稳妥的路径，但必须严格经过 `diffusers_config_mapping.py` 的键名映射，否则极易在 Python API 场景下触发 #275 报告的「静默忽略」。

---

<a id='page-7'></a>

## 性能优化与第三方集成

### 相关页面

相关主题：[推理管道与调度器](#page-5), [社区常见问题与故障排查](#page-8)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [ltx_video/utils/__init__.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/utils/__init__.py)
- [ltx_video/utils/diffusers_config_mapping.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/utils/diffusers_config_mapping.py)
- [ltx_video/utils/prompt_enhance_utils.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/utils/prompt_enhance_utils.py)
- [ltx_video/utils/skip_layer_strategy.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/utils/skip_layer_strategy.py)
- [ltx_video/utils/torch_utils.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/utils/torch_utils.py)
- [README.md](https://github.com/Lightricks/LTX-Video/blob/main/README.md)
</details>

# 性能优化与第三方集成

LTX-Video 在 `ltx_video/utils/` 目录中集中维护了一组用于加速推理、对接第三方生态（Hugging Face `diffusers`、`q8_kernels`、外部 LLM 等）的工具模块。本页梳理这些模块的职责、典型工作流，以及社区反馈中暴露的兼容性陷阱，便于二次开发和性能调优。

## 1. 模块职责与边界

各工具模块定位清晰、互不重叠：

| 工具模块 | 主要职责 |
| --- | --- |
| `torch_utils.py` | 管理设备迁移、dtype 强制（如 `bfloat16`/`float32`）、`torch.compile` 开关与随机种子等基础设施 |
| `skip_layer_strategy.py` | 提供 Skip Layer Guidance（跳层引导）策略，减少 UNet 跳层采样时的算力开销 |
| `diffusers_config_mapping.py` | 在自有推理管线与 `diffusers` 之间转换键名与配置字段 |
| `prompt_enhance_utils.py` | 封装外部 LLM 调用，对用户提示词进行扩写以提升视频生成质量 |
| `utils/__init__.py` | 统一导出公共 API，重排相对导入路径 |

资料来源：[ltx_video/utils/__init__.py:1-40](), [ltx_video/utils/torch_utils.py:1-30](), [ltx_video/utils/skip_layer_strategy.py:1-20]()

## 2. 推理性能优化工作流

`torch_utils.py` 与 `skip_layer_strategy.py` 共同提供推理期的性能与稳定性保障：

- **数值稳定性**：保存视频前需显式转换到 `float32`，并对 NaN/Inf 钳制，避免在 Tesla P40 等不支持 `bfloat16` 的设备上输出损坏帧。社区已记录 LTX 2.3 在 8× Tesla P40 上完成推理但保存时整段视频均为 NaN 的案例。
- **torch.compile**：在支持的 GPU（A100/H100）上，首次推理后会自动触发图编译，对短、长视频均能获益。Tesla P40 等老卡则需手动禁用编译，否则可能触发非法 dtype。
- **显存策略**：distilled 9.6 模型最低可工作于 8 GB 显存，但应启用 tiled VAE 并把 tile 调至 512 以下、起始分辨率压到 320×240、帧数约 33 帧。
- **跳层引导（Skip Layer Guidance）**：在采样过程中跳过若干 UNet 跳层，可显著降低扩散步数，是 distilled 8B/9B/13B 等模型的推荐加速手段。

资料来源：[ltx_video/utils/torch_utils.py:30-180](), [ltx_video/utils/skip_layer_strategy.py:20-120](), [README.md:80-260]()

整体推理管线可描述为如下数据流：

```mermaid
graph LR
    A[用户 prompt] --> B[prompt_enhance_utils]
    B --> C[skip_layer_strategy]
    C --> D[torch_utils 设备/dtype/compile]
    D --> E[diffusers_config_mapping]
    E --> F[LTX 推理管线]
    F --> G[保存前 NaN 钳制]
    G --> H[MP4 输出]
```

## 3. 提示词增强与外部 LLM 集成

`prompt_enhance_utils.py` 封装对外部 LLM 的调用，将简短的提示词自动扩写为更详尽的镜头描述（包含镜头运动、光照、景深等），从而提高画面一致性与真实感。`README.md` 中通常给出 LLM 模型名、提示词模板与采样参数等开关，开发者也可绕开该模块直接传入精炼提示词。资料来源：[ltx_video/utils/prompt_enhance_utils.py:1-120](), [README.md:1-200]()

## 4. Diffusers 兼容性与常见陷阱

`diffusers_config_mapping.py` 负责在 LTX 内部组件命名（如 `diffusion_model.` 前缀）与 `diffusers` 约定命名之间互相翻译，是与第三方分发与生态对接的关键桥梁。社区已记录两类典型问题：

- **LoRA 静默丢失**：通过 `TI2VidTwoStagesPipeline` 的 Python API 传入 `distilled_lora` 时，若缺少 `sd_ops` 重命名映射，权重键不会被重新映射，LoRA 会被静默忽略。CLI 路径会自动完成该映射，因此该问题仅在编程式调用时显现。
- **FP8 内核参数不匹配**：在集成 `q8_kernels` 的 diffusers 管线中，`FP8Linear.forward()` 收到 5 个位置参数而仅接受 2–4 个，导致 `TypeError` 并中断推理。需保证 `FP8Linear` 的前向签名与 diffusers 的调用约定一致，或回退到标准 `nn.Linear`。

资料来源：[ltx_video/utils/diffusers_config_mapping.py:1-220](), 社区 issue #275 与 #231

## 5. 实践建议

1. 在受限显存场景下先调小 `tile_size` 与分辨率，再启用 tiled VAE，避免直接 OOM。
2. 在非 Ampere 及更新的 GPU 上务必显式指定 `float32`，并禁用 `torch.compile`。
3. 通过 Python API 调用管线时，将 LoRA `sd_ops` 重命名映射与 `distilled_lora` 一同传入；CLI 用户不受影响。
4. 使用外部 LLM 增强提示词时，建议在请求中明确指定输出语言与镜头风格，减少东亚语言产生乱码字幕的概率。

---

<a id='page-8'></a>

## 社区常见问题与故障排查

### 相关页面

相关主题：[推理管道与调度器](#page-5), [性能优化与第三方集成](#page-7)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [inference.py](https://github.com/Lightricks/LTX-Video/blob/main/inference.py)
- [ltx_video/inference.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/inference.py)
- [ltx_video/pipelines/pipeline_ltx_video.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/pipelines/pipeline_ltx_video.py)
- [ltx_video/pipelines/ti2vid_two_stages_pipeline.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/pipelines/ti2vid_two_stages_pipeline.py)
- [ltx_video/utils/diffusers_config_mapping.py](https://github.com/Lightricks/LTX-Video/blob/main/ltx_video/utils/diffusers_config_mapping.py)
- [README.md](https://github.com/Lightricks/LTX-Video/blob/main/README.md)

</details>

# 社区常见问题与故障排查

本文汇总 GitHub Issues 与社区帖中频繁出现的故障模式，聚焦推理流程中的报错、API 调用陷阱、生成内容瑕疵以及硬件门槛四类问题，按"现象 → 根因 → 排查"的方式逐项整理。

## 一、推理运行时的关键故障

### 1. 输出目录为空

最常见的表现：执行 `python inference.py` 后输出根目录和日期子目录都被创建，但其中没有任何视频或图像文件（Issue #183）。该现象通常不代表代码崩溃，而是以下三类根因之一：

- CUDA OOM 在视频保存前的 `decode` 步骤触发，导致异常被静默吞掉；
- 命令行 `--prompt` 为空字符串或文件路径不存在，参数解析后提前 return；
- VAE 解码返回 `NaN` 张量，写入时被 `make_video` 跳过。

排查时应先阅读 `inference.py` 中 `main()` 的参数分支，并在 `ltx_video/inference.py` 入口处打印 `args.__dict__` 与构建好的 `pipeline`，再观察保存函数是否实际被调用 `资料来源：[inference.py:1-150]()` `资料来源：[ltx_video/inference.py:1-200]()`。

### 2. NaN 全帧输出

Issue #276 报告在 8× Tesla P40 上以 `float32` 强制加载 LTX 2.3 模型后，生成的视频全部为 NaN。P40 的硬件能力仅支持 FP16，不支持 `bfloat16`；当权重以 bf16 训练、加载脚本未做转换时，反量化阶段会产出 `inf`，进而污染整条解码链。

修复思路：调用 `pipeline.enable_model_cpu_offload()` 或确保 `.to(torch.float32)` 已经在 `transformer` 之前执行，并在 VAE 解码后对 `latents` 调用 `torch.nan_to_num` `资料来源：[ltx_video/pipelines/pipeline_ltx_video.py:1-150]()`。

### 3. FP8Linear 参数数量不匹配

Issue #231 报告 `TypeError: FP8Linear.forward() takes from 2 to 4 positional arguments but 5 were given`。错位源于 `q8_kernels` 与 `diffusers` 流水线版本不匹配：部分流水线在新版中传入 `scale` 或 `bias` 之外的额外参数。处理方式为升级 diffusers 到与 `ltx_video` pin 的版本一致，或把 `FP8Linear.forward` 替换为可变参数签名 `资料来源：[ltx_video/pipelines/pipeline_ltx_video.py:200-400]()`。

## 二、API 调用与 LoRA 加载陷阱

通过 Python 直接构造 `TI2VidTwoStagesPipeline` 调用时，`distilled_lora` 可能被静默忽略（Issue #275）。原因在于 diffusers 的 LoRA 加载器期望键名以 `transformer.` 开头，而仓库内的 LoRA 权重键使用 `diffusion_model.` 前缀；CLI 在内部通过 `sd_ops` 重命名映射做了剥离，但 Python API 不会自动应用。

```python
sd_ops = {"diffusion_model.": "transformer."}
pipeline.load_distilled_lora("path/to/lora.safetensors", sd_ops=sd_ops)
```

同时应核对 `ltx_video/utils/diffusers_config_mapping.py` 的调度器映射，避免使用与训练权重不匹配的 `flow_matching` 调度器 `资料来源：[ltx_video/pipelines/ti2vid_two_stages_pipeline.py:1-200]()` `资料来源：[ltx_video/utils/diffusers_config_mapping.py:1-150]()`。

## 三、生成内容瑕疵与硬件门槛

### 1. 东亚语言字幕乱码

Issue #278：当 prompt 涉及中文、日文或韩文对话时，模型有极高概率在画面叠加乱码字幕，即便使用起始图像或音频驱动唇形同步也无法避免。这是基础模型训练分布带来的固有偏差，目前没有禁用开关。可在 prompt 中追加 `no subtitles, no on-screen text` 作为启发式缓解 `资料来源：[README.md:1-200]()`。

### 2. 显存与最大时长

社区基线建议（Issue #144）：

| 显存 | 可行配置（Distilled 9.6 / LTX-2） |
| --- | --- |
| 6 GB | 不可行 |
| 8 GB | 320×240 @ 15 fps、33 帧、tile < 512 + tiled VAE |
| 16 GB+ | 默认 768×512，可尝试更长时长 |

启用 `--enable-tiling` 并降低 `--tile-size` 是关键，可显著降低 VAE 的峰值显存 `资料来源：[ltx_video/pipelines/pipeline_ltx_video.py:200-400]()`。

## 四、训练、开源与生态路线

微调（Issue #7）与训练代码（Issue #35）目前以路线图形式披露，需关注 README 的 milestone；LTX-2 开源时间（Issue #256）由官方博客决定，权重加载流程统一经过 `diffusers_config_mapping.py`，因此升级 diffusers 时优先检查该映射而不是直接覆盖 `pipeline` 参数 `资料来源：[README.md:1-100]()` `资料来源：[ltx_video/utils/diffusers_config_mapping.py:1-150]()`。

## 通用排查流程

```mermaid
flowchart TD
  A[推理报错] --> B{输出文件夹是否为空?}
  B -- 是 --> C[检查 inference.py 入参<br/>与 VAE 解码日志]
  B -- 否但全 NaN --> D[核对设备 dtype 兼容性<br/>Tesla P40 关闭 bf16]
  A --> E{FP8Linear 参数错误?}
  E -- 是 --> F[对齐 diffusers 与 q8_kernels 版本]
  A --> G{LoRA 无效果?}
  G -- 是 --> H[补传 sd_ops 重命名映射]
  A --> I{画面乱码字幕?}
  I -- 是 --> J[在 prompt 中显式禁用字幕]

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：Lightricks/LTX-Video

摘要：发现 10 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Looking for help / freelancer to finalize LTX-Video setup。

## 1. 安装坑 · 来源证据：Looking for help / freelancer to finalize LTX-Video setup

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Looking for help / freelancer to finalize LTX-Video setup
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/Lightricks/LTX-Video/issues/268 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 配置坑 · 来源证据：Video 1

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Video 1
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/Lightricks/LTX-Video/issues/279 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 安全/权限坑 · 来源证据：[BUG]FP8Linear.forward() argument mismatch in LTX-Video inference

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG]FP8Linear.forward() argument mismatch in LTX-Video inference
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Lightricks/LTX-Video/issues/231 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 来源证据：LoRA silently ignored when using TI2VidTwoStagesPipeline programmatically (missing sd_ops renaming map)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：LoRA silently ignored when using TI2VidTwoStagesPipeline programmatically (missing sd_ops renaming map)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/Lightricks/LTX-Video/issues/275 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 5. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/Lightricks/LTX-Video | README/documentation is current enough for a first validation pass.

## 6. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/Lightricks/LTX-Video | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/Lightricks/LTX-Video | no_demo; severity=medium

## 8. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/Lightricks/LTX-Video | no_demo; severity=medium

## 9. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/Lightricks/LTX-Video | issue_or_pr_quality=unknown

## 10. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/Lightricks/LTX-Video | release_recency=unknown

<!-- canonical_name: Lightricks/LTX-Video; human_manual_source: deepwiki_human_wiki -->