LTX2VideoDiffusionDecoderModel

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

它是一个解码器，而非自编码器：编码功能仍由 AutoencoderKLLTX2Video 负责，该解码器直接消费其潜空间，因此潜变量在卷积解码器与此解码器之间可以互换。由于它本身是一个扩散模型，因此由 LTX2VideoDiffusionDecodePipeline 驱动，而不是作为管线的 vae 传入：先以 output_type="latent" 运行任意 LTX-2 管线，然后再进行解码。

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 的内核，原始实现也使用了这些内核。处理器通过 kernels 包从 Hub 获取 NATTEN（shi-labs/natten），因此需要 pip install kernels，而不是本地构建 NATTEN：

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() 通过解码重叠的图块（tiles）并将它们混合回原图来工作，从而将峰值内存限制在图块大小而非视频大小。廉价的早期上采样阶段仍然会看到完整的潜在表示（latent）——只有主导解码内存的最后上采样阶段和扩散阶段按图块运行——因此分块（tiling）仅会在图块边界附近改变输出。由于扩散阶段对每个图块分别进行去噪，分块解码无法精确复现非分块的结果；默认的图块和重叠大小与参考实现一致。邻域注意力（Neighborhood attention）会拒绝任何小于其核（kernel）的网格，因此末尾的残余图块会被合并到其相邻图块中，而不是单独解码。

LTX2VideoDiffusionDecoderModel