diffusers/main/pt/api/models/ltx2_diffusion_decoder.md

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[[diffusers.LTX2VideoDiffusionDecoderModel]]

diffusers.LTX2VideoDiffusionDecoderModel[[diffusers.LTX2VideoDiffusionDecoderModel]]

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)

Fonte

O decodificador de vídeo por difusão LTX-2, introduzido no LTX-2.5.

Este é um decodificador, não um autoencoder: ele não possui um codificador e não pode produzir latentes. A codificação permanece com o AutoencoderKLLTX2Video, cujo espaço latente este consome sem alterações, de modo que os latentes são intercambiáveis entre o decodificador convolucional e este.

Ele também é um modelo de difusão, e não um decodificador determinístico — ele remove o ruído dos pixels condicionado a um volume de contexto construído a partir dos latentes —, motivo pelo qual é acionado por LTX2VideoDiffusionDecodePipeline em vez de ser passado como vae de um pipeline.

As estatísticas latentes são mantidas aqui como buffers para que o pipeline de decodificação possa desnormalizar sem carregar um segundo autoencoder apenas para dois vetores.

Este modelo herda de ModelMixin. Consulte a documentação da superclasse para seus métodos genéricos implementados para todos os modelos (como download ou salvamento).

decode[[diffusers.LTX2VideoDiffusionDecoderModel.decode]]

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

Fonte

Decodifica um lote de latentes.

z é esperado que já esteja desnornormalizado (o pipeline aplica latents_mean / latents_std), correspondendo a AutoencoderKLLTX2Video. Este decodificador remove o ruído, portanto, passe generator para reprodutibilidade.

enable_tiling[[diffusers.LTX2VideoDiffusionDecoderModel.enable_tiling]]

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)

Fonte

Parâmetros:

tile_sample_min_height (int, opcional) : A altura de um tile decodificado, em pixels.

tile_sample_min_width (int, opcional) : A largura de um tile decodificado, em pixels.

tile_sample_min_num_frames (int, opcional) : O número de quadros de um tile decodificado.

tile_sample_stride_height (int, opcional) : A distância em pixels entre as partes superiores de duas tiles verticais consecutivas; a diferença em relação a tile_sample_min_height é a sobreposição mesclada.

tile_sample_stride_width (int, opcional) : A distância em pixels entre as bordas esquerda de duas tiles horizontais consecutivas.

tile_sample_stride_num_frames (int, opcional) : A distância em quadros entre os inícios de duas tiles temporais consecutivas.

Ative a decodificação em blocos (tiled decoding). Os estágios determinísticos de superamostragem (upsampling) antes do último sempre processam o latente completo (eles são executados em baixa resolução e têm baixo custo); o último estágio e os blocos de difusão do estágio 5 — que dominam a memória de decodificação — são executados em blocos sobrepostos cujas emendas são mescladas linearmente.

disable_tiling[[diffusers.LTX2VideoDiffusionDecoderModel.disable_tiling]]

disable_tiling()

Fonte

Desative a decodificação em blocos, retornando à decodificação do vídeo inteiro em uma única passagem.

forward[[diffusers.LTX2VideoDiffusionDecoderModel.forward]]

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

Fonte

Parâmetros:

z (torch.Tensor) : Latentes de forma (B, C, F, H, W), esperados para já estarem desnornalizados (o pipeline aplica latents_mean / latents_std), correspondendo a AutoencoderKLLTX2Video.

generator (torch.Generator, opcional) : Este decodificador remove o ruído, portanto, passe um gerador para tornar a decodificação reproduzível.

num_inference_steps (int, opcional) : Número de etapas de desruidamento. O padrão é o valor de configuração decoder_num_inference_steps do decodificador.

return_dict (bool, opcional, padrão True) : Se deve retornar um DecoderOutput em vez de uma tupla simples.

Retorna: DecoderOutput ou tuple

tiled_decode[[diffusers.LTX2VideoDiffusionDecoderModel.tiled_decode]]

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

Fonte

Decodifique um lote de latentes com o último estágio determinístico e o estágio de difusão executado por tile.

Os tiles ficam na grade que entra na última etapa determinística, na qual uma célula mapeia para um bloco fixo de pixels de saída; os tamanhos de tile_sample_* são convertidos para essa grade, portanto devem ser múltiplos do tamanho da célula (8 px espacialmente e 2 frames temporalmente para a configuração de produção). Os tiles temporais seguem o mapeamento de frames causal: o tile contendo t=0 descarta o frame inicial duplicado do upsample temporal e apenas o tile contendo o fim do vídeo carrega o padding de borda do NATTEN.