LTX2VideoDiffusionDecoderModel

O decodificador de vídeo por difusão introduzido no LTX-2.5 pela Lightricks. Estágios de atenção de vizinhança fazem o upsample do latente em um volume de contexto, e um estágio final remove o ruído dos pixels condicionado a esse contexto.

É um decodificador, não um autoencoder: a codificação permanece com AutoencoderKLLTX2Video, cujo espaço latente este consome inalterado, de modo que os latentes são intercambiáveis entre o decodificador convolucional e este. Por ser ele próprio um modelo de difusão, é acionado por LTX2VideoDiffusionDecodePipeline em vez de ser passado como vae de um pipeline: execute qualquer pipeline LTX-2 com output_type="latent" e, em seguida, decodifique.

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 é um componente opcional no pipeline de decodificação: ele é consultado apenas para as estatísticas latentes quando denormalize=True, e o decodificador possui as suas próprias, de modo que um fluxo de trabalho somente de decodificação não precisa carregar um segundo autoencoder.

Backends de atenção

A janela de atenção de vizinhança é expressa como uma BlockMask, portanto o decodificador é executado no backend de atenção flex por padrão e não requer nenhuma dependência extra. O PyTorch não compila o flex_attention a menos que você solicite, e sem compilação ele materializa a matriz de pontuação completa — o que é impraticável em comprimentos de sequência em resolução total. Para esses casos, compile o decodificador ou alterne para os kernels do NATTEN, que também são usados pela implementação original. O processador busca o NATTEN do Hub (shi-labs/natten) por meio do pacote kernels, portanto é necessário pip install kernels em vez de uma compilação local do NATTEN:

from diffusers.models.autoencoders.ltx2_diffusion_decoder import LTX2VideoVaeNeighborhoodNattenProcessor

decoder.set_attn_processor(LTX2VideoVaeNeighborhoodNattenProcessor())

Obtendo o código de download do kernel do Hub, para que o processador gere um erro quando o código remoto estiver desabilitado globalmente com DIFFUSERS_DISABLE_REMOTE_CODE=true.

Todos os módulos de atenção no decodificador são a mesma atenção de vizinhança (diferenças por estágio, como o tamanho do kernel, ficam no módulo, não no processador), portanto set_attn_processor os substitui todos por uma única instância compartilhada.

Alterar o backend (decoder.set_attention_backend(...)) para qualquer valor que não seja flex gera o seguinte erro: nenhum outro backend aceita o BlockMask. Use o processador NATTEN acima em vez disso.

Tiling

decoder.enable_tiling() decodifica em tiles sobrepostos que são mesclados novamente, limitando a memória de pico pelo tamanho do tile em vez do tamanho do vídeo. Os estágios iniciais de upsampling, de baixo custo, ainda veem o latente completo — apenas o último estágio de upsampling e o estágio de difusão, que dominam a memória de decodificação, são executados por tile —, portanto, o tiling altera a saída apenas perto das bordas dos tiles. Como o estágio de difusão remove o ruído de cada tile separadamente, uma decodificação com tiles não reproduz exatamente o resultado sem tiles; os tamanhos padrão de tile e sobreposição correspondem aos da implementação de referência. A atenção de vizinhança rejeita qualquer grade menor que seu kernel, de modo que um tile remanescente final é mesclado com seu vizinho em vez de ser decodificado isoladamente.

LTX2VideoDiffusionDecoderModel