# LTX2VideoDiffusionDecoderModel

El decodificador de video por difusión introducido en LTX-2.5 por Lightricks. Las etapas de atención de vecindad submuestrean el latente en un volumen de contexto, y una etapa final desruidifica los píxeles condicionados en ese contexto.

Es un decodificador, no un autoencoder: la codificación sigue en [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/es/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video), cuyo espacio latente se consume sin cambios, por lo que los latentes son intercambiables entre el decodificador convolucional y este. Dado que es en sí mismo un modelo de difusión, se controla mediante [LTX2VideoDiffusionDecodePipeline](/docs/diffusers/v0.43.0/es/api/pipelines/ltx2#diffusers.LTX2VideoDiffusionDecodePipeline) en lugar de pasarse como `vae` de un pipeline: ejecute cualquier pipeline de LTX-2 con `output_type="latent"` y luego decodifique.

```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` es un componente opcional en el pipeline de decodificación: solo se consulta para las estadísticas latentes cuando `denormalize=True`, y el decodificador lleva las suyas, por lo que un flujo de trabajo solo de decodificación no tiene que cargar un segundo autoencoder.

## Backends de atención

La ventana de atención de vecindad se expresa como una `BlockMask`, por lo que el decodificador se ejecuta de forma predeterminada en el backend de atención `flex` y no requiere ninguna dependencia adicional. PyTorch no compila `flex_attention` a menos que se le solicite, y sin compilar materializa la matriz de puntuación completa, lo cual es impráctico con longitudes de secuencia a resolución completa. Para esos casos, o bien compile el decodificador o bien cambie a los kernels de [NATTEN](https://github.com/SHI-Labs/NATTEN), que también son los que utiliza la implementación original. El procesador obtiene NATTEN desde el Hub ([`shi-labs/natten`](https://huggingface.co/shi-labs/natten)) a través del paquete [`kernels`](https://github.com/huggingface/kernels), por lo que necesita `pip install kernels` en lugar de una compilación local de NATTEN:

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

decoder.set_attn_processor(LTX2VideoVaeNeighborhoodNattenProcessor())
```

Obtención del código de descargas del kernel desde el Hub, por lo que el procesador genera un error cuando el código remoto está deshabilitado globalmente con `DIFFUSERS_DISABLE_REMOTE_CODE=true`.

Todos los módulos de atención en el decodificador son la misma atención de vecindad (las diferencias por etapa, como el tamaño del kernel, residen en el módulo, no en el procesador), por lo que `set_attn_processor` los reemplaza todos con una instancia compartida.

Cambiar el *backend* (`decoder.set_attention_backend(...)`) a cualquier valor distinto de `flex` genera un error: ningún otro backend acepta `BlockMask`. Utilice en su lugar el procesador NATTEN anterior.

## Tiling

`decoder.enable_tiling()` decodifica en mosaicos superpuestos que se combinan nuevamente, limitando la memoria pico por el tamaño del mosaico en lugar del tamaño del video. Las etapas iniciales de interpolación ascendente de bajo costo aún ven el latente completo; solo la última etapa de interpolación ascendente y la etapa de difusión, que dominan la memoria de decodificación, se ejecutan por mosaico, por lo que el mosaico cambia la salida solo cerca de los bordes de los mosaicos. Dado que la etapa de difusión desruidifica cada mosaico por separado, una decodificación con mosaicos no reproduce exactamente el resultado sin mosaicos; los tamaños predeterminados de mosaico y superposición coinciden con los de la implementación de referencia. La atención de vecindad rechaza cualquier cuadrícula más pequeña que su núcleo, por lo que un mosaico residual final se fusiona con su vecino en lugar de decodificarse por separado.

## 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)
```

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

El decodificador de video por difusión LTX-2, introducido en LTX-2.5.

Este es un decodificador, no un autoencoder: no tiene un codificador y no puede generar latentes. La codificación sigue a cargo de [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/es/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video), cuyo espacio latente se consume sin cambios, por lo que los latentes son intercambiables entre el decodificador convolucional y este.

También es un modelo de difusión y no un decodificador determinista: desruidifica los píxeles condicionados en un volumen de contexto construido a partir de los latentes, por lo que está impulsado por [LTX2VideoDiffusionDecodePipeline](/docs/diffusers/v0.43.0/es/api/pipelines/ltx2#diffusers.LTX2VideoDiffusionDecodePipeline) en lugar de ser pasado como el `vae` de un pipeline.

Las estadísticas latentes se transportan aquí como buffers para que la pipeline de decodificación pueda desnormalizar sin cargar un segundo autoencoder solo por dos vectores.

Este modelo hereda de [ModelMixin](/docs/diffusers/v0.43.0/es/api/models/overview#diffusers.ModelMixin). Consulta la documentación de la superclase para sus métodos genéricos implementados para todos los modelos (como la descarga o el guardado).

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

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

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

Decodificar un lote de latentes.

Se espera que `z` ya esté denormalizado (el pipeline aplica `latents_mean` / `latents_std`), en concordancia con [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/es/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video). Este decodificador elimina el ruido, por lo que se debe pasar `generator` para garantizar la reproducibilidad.

#### 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)
```

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

**Parámetros:**

tile_sample_min_height (`int`, *opcional*) : La altura de una tesela decodificada, en píxeles.

tile_sample_min_width (`int`, *opcional*) : El ancho de una sola tesela decodificada, en píxeles.

tile_sample_min_num_frames (`int`, *opcional*) : El número de fotogramas de una tesela decodificada.

tile_sample_stride_height (`int`, *opcional*) : La distancia en píxeles entre las partes superiores de dos mosaicos verticales consecutivos; la diferencia con `tile_sample_min_height` es la superposición combinada.

tile_sample_stride_width (`int`, *opcional*) : La distancia en píxeles entre los bordes izquierdos de dos mosaicos horizontales consecutivos.

tile_sample_stride_num_frames (`int`, *opcional*) : La distancia en fotogramas entre los inicios de dos mosaicos temporales consecutivos.

Habilita la decodificación por mosaicos. Las etapas de remuestreo determinista anteriores a la última siempre procesan el latente completo (se ejecutan a baja resolución y son económicas); la última etapa y los bloques de difusión de la etapa 5, que dominan la memoria de decodificación, se ejecutan en mosaicos superpuestos cuyas costuras se combinan linealmente.

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

```python
disable_tiling()
```

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

Desactivar la decodificación por mosaicos, volviendo a decodificar el video completo en una sola pasada.

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

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

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

**Parámetros:**

z (`torch.Tensor`) : Latentes de forma `(B, C, F, H, W)`, que se espera que ya estén denormalizados (el pipeline aplica `latents_mean` / `latents_std`), coincidentes con [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/es/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video).

generator (`torch.Generator`, *opcional*) : Este decodificador elimina el ruido, por lo que debe pasar un generador para que la decodificación sea reproducible.

num_inference_steps (`int`, *opcional*) : Número de pasos de desruido. Por defecto, utiliza el valor de configuración `decoder_num_inference_steps` del decodificador.

return_dict (`bool`, *opcional*, valor predeterminado `True`) : Si se debe devolver un [DecoderOutput](/docs/diffusers/v0.43.0/es/api/models/autoencoderkl_qwenimage#diffusers.models.autoencoders.vae.DecoderOutput) en lugar de una tupla simple.

**Devuelve:** [DecoderOutput](/docs/diffusers/v0.43.0/es/api/models/autoencoderkl_qwenimage#diffusers.models.autoencoders.vae.DecoderOutput) o `tuple`

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

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

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

Decodifica un lote de latentes con la última etapa determinista y la etapa de difusión ejecutándose por mosaico.

Los tiles se ubican en la cuadrícula que ingresa a la última etapa determinista, donde una celda se mapea a un bloque fijo de píxeles de salida; los tamaños de `tile_sample_*` se convierten a esa cuadrícula, por lo que deben ser múltiplos del tamaño de la celda (8 px espacialmente y 2 fotogramas temporalmente para la configuración de producción). Los tiles temporales siguen el mapeo de fotogramas causal: el tile que contiene t=0 descarta el fotograma inicial duplicado del submuestreo temporal y solo el tile que contiene el final del video lleva el relleno de borde de NATTEN.