# LTX2VideoDiffusionDecoderModel

Lightricks 在 LTX-2.5 中引入的扩散视频解码器。邻域注意力阶段将潜在表示上采样为上下文体积，最终阶段则基于该上下文对像素进行去噪。

它是一个解码器，而非自编码器：编码功能仍由 [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video) 负责，本模块直接消费其潜空间，因此潜变量在卷积解码器与本模块之间可以互换。由于它本身是一个扩散模型，因此由 [LTX2VideoDiffusionDecodePipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/ltx2#diffusers.LTX2VideoDiffusionDecodePipeline) 驱动，而不是作为管线的 `vae` 传入：先以 `output_type="latent"` 运行任意 LTX-2 管线，然后再进行解码。

```python
import torch
from diffusers import LTX2Pipeline, LTX2VideoDiffusionDecodePipeline, LTX2VideoDiffusionDecoderModel

pipe = LTX2Pipeline.from_pretrained("Lightricks/LTX-2.5-Diffusers", dtype=torch.bfloat16).to("cuda")  # or "mps", "xpu", "cpu"
latents = pipe(prompt="a potter shaping a clay vase", output_type="latent").frames

decoder = LTX2VideoDiffusionDecoderModel.from_pretrained(
    "Lightricks/LTX-2.5-Diffusers", subfolder="diffusion_decoder", dtype=torch.bfloat16
).to("cuda")
decode_pipe = LTX2VideoDiffusionDecodePipeline(diffusion_decoder=decoder, scheduler=pipe.scheduler)

# `denormalize=False`: `output_type="latent"` already applied the latent statistics, so applying them
# again here would scale every channel by its std a second time.
# The decoder also draws the noise it denoises, so decoding is only reproducible with a generator.
video = decode_pipe(
    latents, generator=torch.Generator("cuda").manual_seed(0), denormalize=False
).frames[0]
```

`vae` 是解码流水线中的一个可选组件：仅当 `denormalize=True` 时才会查询其潜在统计量，而解码器自身已包含这些统计量，因此仅执行解码的工作流程无需加载第二个自编码器。

## 注意力后端

邻域注意力窗口以 `BlockMask` 的形式表示，因此解码器默认使用 `flex` 注意力后端，无需额外依赖。除非明确要求，否则 PyTorch 不会编译 `flex_attention`，而未编译时会实例化完整的分数矩阵——在全分辨率序列长度下这并不实用。对于这种情况，可以编译解码器，或者切换到 [NATTEN](https://github.com/SHI-Labs/NATTEN) 的内核，原始实现也使用了这些内核。处理器通过 [`kernels`](https://github.com/huggingface/kernels) 包从 Hub 获取 NATTEN（[`shi-labs/natten`](https://huggingface.co/shi-labs/natten)），因此需要 `pip install kernels`，而不是本地构建 NATTEN：

```python
from diffusers.models.autoencoders.ltx2_diffusion_decoder import LTX2VideoVaeNeighborhoodNattenProcessor

decoder.set_attn_processor(LTX2VideoVaeNeighborhoodNattenProcessor())
```

从 Hub 获取内核下载代码，因此当全局禁用远程代码（即 `DIFFUSERS_DISABLE_REMOTE_CODE=true`）时，处理器会抛出异常。

解码器中的每个注意力模块都是相同的邻域注意力（诸如核大小之类的逐阶段差异存在于模块上，而非处理器上），因此 `set_attn_processor` 会用一个共享实例替换所有这些模块。

将 *backend*（`decoder.set_attention_backend(...)`）切换为 `flex` 以外的任何值都会引发错误：没有其他后端接受 `BlockMask`。请改用上述 NATTEN 处理器。

## 平铺

`decoder.enable_tiling()` 通过重叠的瓦片进行解码，并将这些瓦片混合回原图，从而将峰值内存限制在瓦片大小而非视频大小。廉价的早期上采样阶段仍然会看到完整的潜在表示——只有主导解码内存的最后一级上采样阶段和扩散阶段是按瓦片运行的——因此瓦片化仅会在瓦片边界附近改变输出。由于扩散阶段对每个瓦片分别进行去噪，瓦片化解码无法精确复现非瓦片化结果；默认的瓦片和重叠大小与参考实现一致。邻域注意力会拒绝任何小于其核大小的网格，因此末尾的残余瓦片会被合并到其相邻瓦片中，而不是单独解码。

## LTX2VideoDiffusionDecoderModel[[diffusers.LTX2VideoDiffusionDecoderModel]]

#### diffusers.LTX2VideoDiffusionDecoderModel[[diffusers.LTX2VideoDiffusionDecoderModel]]

```python
diffusers.LTX2VideoDiffusionDecoderModel(out_channels: int = 3, latent_channels: int = 128, patch_size: int = 4, scaling_factor: float = 1.0, decoder_head_dim: int = 64, decoder_stage_channels: tuple[int, ...] = (2048, 1024, 512, 512, 256), decoder_stage_depths: tuple[int, ...] = (4, 6, 4, 2, 8), decoder_stage_kernels: tuple[tuple[int, int, int], ...] = ((3, 7, 7), (3, 7, 7), (3, 5, 5), (3, 5, 5)), decoder_upsample_strides: tuple[tuple[int, int, int], ...] = ((1, 2, 2), (2, 1, 1), (2, 2, 2), (2, 2, 2)), decoder_upsample_channel_reductions: tuple[int, ...] = (2, 2, 1, 2), decoder_stage5_kernel: tuple[int, int, int] = (11, 11, 11), decoder_t_emb_dim: int = 384, decoder_timestep_scale_multiplier: float = 1000.0, decoder_model_output_type: str = 'x0', decoder_num_inference_steps: int = 1, spatial_compression_ratio: int = 32, temporal_compression_ratio: int = 8)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L700)

LTX-2.5 中引入的 LTX-2 扩散视频解码器。

这是一个解码器，而非自编码器：它没有编码器，也无法生成潜在表示。编码仍由 [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video) 负责，本模型直接沿用其潜在空间，因此卷积解码器与本模型之间的潜在表示可以互换使用。

它同样是一个扩散模型，而非确定性解码器——它基于由潜在变量构建的上下文体积对像素进行去噪——因此它由 [LTX2VideoDiffusionDecodePipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/ltx2#diffusers.LTX2VideoDiffusionDecodePipeline) 驱动，而不是作为流水线的 `vae` 传入。

潜变量统计量在此处作为缓冲区传递，以便解码流水线能够进行反归一化，而无需仅为两个向量额外加载一个自编码器。

该模型继承自 [ModelMixin](/docs/diffusers/v0.43.0/zh/api/models/overview#diffusers.ModelMixin)。请查阅其父类文档，了解为所有模型实现的通用方法（例如下载或保存）。

#### decode[[diffusers.LTX2VideoDiffusionDecoderModel.decode]]

```python
decode(z: Tensor, generator: typing.Optional[torch.Generator] = None, num_inference_steps: int | None = None, return_dict: bool = True)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L988)

解码一批潜在变量。

`z` 预期已经过反归一化处理（流水线会应用 `latents_mean` / `latents_std`），与 [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video) 保持一致。由于该解码器执行去噪操作，请传入 `generator` 以确保可复现性。

#### enable_tiling[[diffusers.LTX2VideoDiffusionDecoderModel.enable_tiling]]

```python
enable_tiling(tile_sample_min_height: int | None = None, tile_sample_min_width: int | None = None, tile_sample_min_num_frames: int | None = None, tile_sample_stride_height: int | None = None, tile_sample_stride_width: int | None = None, tile_sample_stride_num_frames: int | None = None)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L787)

**参数：**

tile_sample_min_height (`int`, *可选*) : 单个解码瓦片的高度，以像素为单位。

tile_sample_min_width (`int`, *可选*) : 单个解码瓦片的宽度，以像素为单位。

tile_sample_min_num_frames (`int`, *可选*) : 单个解码瓦片的帧数。

tile_sample_stride_height (`int`, *可选*) : 两个连续垂直瓦片顶部之间的像素距离；与 `tile_sample_min_height` 的差值即为混合重叠区域。

tile_sample_stride_width (`int`, *可选*) : 两个连续水平瓦片左边缘之间的像素距离。

tile_sample_stride_num_frames (`int`, *可选*)：两个连续时间块起始位置之间的帧数距离。

启用分块解码。最后一个阶段之前的确定性上采样阶段始终处理完整的潜在表示（它们在低分辨率下运行，开销较小）；而最后一个阶段以及第 5 阶段的扩散块——它们主导了解码内存占用——则在重叠的分块上运行，其接缝通过线性混合进行融合。

#### disable_tiling[[diffusers.LTX2VideoDiffusionDecoderModel.disable_tiling]]

```python
disable_tiling()
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L824)

禁用分块解码，恢复为一次性解码整个视频。

#### forward[[diffusers.LTX2VideoDiffusionDecoderModel.forward]]

```python
forward(z: Tensor, generator: typing.Optional[torch.Generator] = None, num_inference_steps: int | None = None, return_dict: bool = True)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L1017)

**参数：**

z (`torch.Tensor`) : 形状为 `(B, C, F, H, W)` 的潜在变量，预期已经过反归一化处理（流水线会应用 `latents_mean` / `latents_std`），与 [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video) 相匹配。

generator (`torch.Generator`，*可选*)：此解码器执行去噪操作，因此请传入一个生成器以确保解码过程可复现。

num_inference_steps (`int`, *可选*) : 去噪步数。默认值为解码器的 `decoder_num_inference_steps` 配置值。

return_dict (`bool`，*可选*，默认为 `True`)：是否返回 [DecoderOutput](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl_qwenimage#diffusers.models.autoencoders.vae.DecoderOutput) 而不是普通元组。

**返回：** [DecoderOutput](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl_qwenimage#diffusers.models.autoencoders.vae.DecoderOutput) 或 `tuple`

#### tiled_decode[[diffusers.LTX2VideoDiffusionDecoderModel.tiled_decode]]

```python
tiled_decode(z: Tensor, generator: typing.Optional[torch.Generator] = None, num_inference_steps: int | None = None)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L855)

使用最后一个确定性阶段以及按块运行的扩散阶段，解码一批潜在变量。

Tiles 位于进入最后一个确定性阶段的网格上，在该阶段中，一个单元格映射到固定大小的输出像素块；`tile_sample_*` 尺寸会被转换到该网格，因此它们应当是单元格尺寸的整数倍（在生产配置中，空间方向为 8 像素，时间方向为 2 帧）。时间维度的 Tiles 遵循因果帧映射：包含 t=0 的 Tile 会丢弃时间上采样产生的重复首帧，而只有包含视频末尾的 Tile 会携带 NATTEN 边界填充。