# LTX2VideoDiffusionDecoderModel

Le décodeur vidéo par diffusion introduit dans LTX-2.5 par Lightricks. Les étapes d'attention de voisinage effectuent un suréchantillonnage du latent en un volume de contexte, et une étape finale débruite les pixels en condition sur ce contexte.

C'est un décodeur, et non un auto-encodeur : l'encodage reste du ressort de [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/fr/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video), dont l'espace latent est consommé ici sans modification, si bien que les latents sont interchangeables entre le décodeur convolutif et celui-ci. Étant lui-même un modèle de diffusion, il est piloté par [LTX2VideoDiffusionDecodePipeline](/docs/diffusers/v0.43.0/fr/api/pipelines/ltx2#diffusers.LTX2VideoDiffusionDecodePipeline) plutôt que d'être transmis comme le `vae` d'un pipeline : exécutez n'importe quel pipeline LTX-2 avec `output_type="latent"`, puis décodez.

```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` est un composant facultatif du pipeline de décodage : il n’est consulté que pour les statistiques latentes lorsque `denormalize=True`, et le décodeur en possède ses propres, de sorte qu’un flux de travail de décodage uniquement n’a pas à charger un second autoencodeur.

## Backends d'attention

La fenêtre d'attention de voisinage est exprimée sous forme de `BlockMask`, le décodeur s'exécute donc par défaut sur le backend d'attention `flex` et n'exige aucune dépendance supplémentaire. PyTorch ne compile pas `flex_attention` à moins qu'on ne le lui demande, et non compilé, il matérialise la matrice de scores complète — ce qui est irréalisable pour des longueurs de séquence à résolution complète. Pour ces cas, il faut soit compiler le décodeur, soit passer aux noyaux de [NATTEN](https://github.com/SHI-Labs/NATTEN), qui sont également ceux utilisés par l'implémentation d'origine. Le processeur récupère NATTEN depuis le Hub ([`shi-labs/natten`](https://huggingface.co/shi-labs/natten)) via le package [`kernels`](https://github.com/huggingface/kernels), il faut donc `pip install kernels` plutôt qu'une compilation locale de NATTEN :

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

decoder.set_attn_processor(LTX2VideoVaeNeighborhoodNattenProcessor())
```

Récupération du code de téléchargement du noyau depuis le Hub, de sorte que le processeur lève une exception lorsque le code distant est désactivé globalement avec `DIFFUSERS_DISABLE_REMOTE_CODE=true`.

Chaque module d'attention du décodeur est la même attention de voisinage (les différences par étape, comme la taille du noyau, sont définies sur le module et non sur le processeur), de sorte que `set_attn_processor` les remplace tous par une instance partagée.

Passer le *backend* (`decoder.set_attention_backend(...)`) à autre chose que `flex` provoque une erreur : aucun autre backend n’accepte le `BlockMask`. Utilisez à la place le processeur NATTEN ci-dessus.

## Tiling

`decoder.enable_tiling()` décode en tuiles superposées qui sont ensuite fusionnées, limitant ainsi la mémoire de pointe par la taille de la tuile plutôt que par la taille de la vidéo. Les étapes d’interpolation ascendante initiales, peu coûteuses, traitent toujours le latent complet — seules la dernière étape d’interpolation ascendante et l’étape de diffusion, qui dominent la mémoire de décodage, s’exécutent par tuile — de sorte que le tuilage ne modifie la sortie qu’aux abords des frontières de tuiles. Comme l’étape de diffusion débruite chaque tuile séparément, un décodage tuilé ne reproduit pas exactement le résultat non tuilé ; les tailles de tuile et de chevauchement par défaut correspondent à celles de l’implémentation de référence. L’attention de voisinage rejette tout grille plus petite que son noyau, de sorte qu’une tuile résiduelle finale est fusionnée avec sa voisine plutôt que décodée isolément.

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

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

Le décodeur vidéo par diffusion LTX-2, introduit dans LTX-2.5.

Il s’agit d’un décodeur, et non d’un auto-encodeur : il ne possède pas d’encodeur et ne peut pas produire de latents. L’encodage reste du ressort de [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/fr/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video), dont l’espace latent est consommé ici sans modification, si bien que les latents sont interchangeables entre le décodeur convolutif et celui-ci.

C'est également un modèle de diffusion plutôt qu'un décodeur déterministe — il débruite les pixels en fonction d'un volume de contexte construit à partir des latents — c'est pourquoi il est piloté par [LTX2VideoDiffusionDecodePipeline](/docs/diffusers/v0.43.0/fr/api/pipelines/ltx2#diffusers.LTX2VideoDiffusionDecodePipeline) au lieu d'être transmis comme `vae` d'un pipeline.

Les statistiques latentes sont conservées ici sous forme de tampons afin que le pipeline de décodage puisse dénormaliser sans charger un second autoencodeur uniquement pour deux vecteurs.

Ce modèle hérite de [ModelMixin](/docs/diffusers/v0.43.0/fr/api/models/overview#diffusers.ModelMixin). Consultez la documentation de la classe parente pour ses méthodes génériques implémentées pour tous les modèles (tels que le téléchargement ou l'enregistrement).

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

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

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

Décoder un lot de latents.

`z` est censé être déjà dénormalisé (le pipeline applique `latents_mean` / `latents_std`), conformément à [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/fr/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video). Ce décodeur effectue un débruitage, il faut donc passer `generator` pour assurer la reproductibilité.

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

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

**Paramètres :**

tile_sample_min_height (`int`, *facultatif*) : La hauteur d'une tuile décodée, en pixels.

tile_sample_min_width (`int`, *facultatif*) : La largeur d'une tuile décodée, en pixels.

tile_sample_min_num_frames (`int`, *facultatif*) : Le nombre d'images d'une tuile décodée.

tile_sample_stride_height (`int`, *facultatif*) : La distance en pixels entre les sommets de deux tuiles verticales consécutives ; la différence par rapport à `tile_sample_min_height` correspond au chevauchement fusionné.

tile_sample_stride_width (`int`, *facultatif*) : La distance en pixels entre les bords gauche de deux tuiles horizontales consécutives.

tile_sample_stride_num_frames (`int`, *facultatif*) : La distance en images entre les débuts de deux tuiles temporelles consécutives.

Activez le décodage par tuiles. Les étapes déterministes de suréchantillonnage avant la dernière traitent toujours le latent complet (elles s’exécutent à basse résolution et sont peu coûteuses) ; la dernière étape et les blocs de diffusion de l’étape 5 — qui dominent la mémoire de décodage — s’exécutent sur des tuiles chevauchantes dont les coutures sont fusionnées linéairement.

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

```python
disable_tiling()
```

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

Désactiver le décodage par tuiles, pour revenir au décodage de la vidéo entière en une seule passe.

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

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

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

**Paramètres :**

z (`torch.Tensor`) : Latents de forme `(B, C, F, H, W)`, censés être déjà dénormalisés (le pipeline applique `latents_mean` / `latents_std`), correspondant à [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/fr/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video).

generator (`torch.Generator`, *facultatif*) : Ce décodeur effectue un débruitage, passez donc un générateur pour rendre le décodage reproductible.

num_inference_steps (`int`, *facultatif*) : Nombre d'étapes de débruitage. Par défaut, la valeur de configuration `decoder_num_inference_steps` du décodeur est utilisée.

return_dict (`bool`, *facultatif*, par défaut `True`) : Indique s'il faut retourner un [DecoderOutput](/docs/diffusers/v0.43.0/fr/api/models/autoencoderkl_qwenimage#diffusers.models.autoencoders.vae.DecoderOutput) plutôt qu'un simple tuple.

**Retourne :** [DecoderOutput](/docs/diffusers/v0.43.0/fr/api/models/autoencoderkl_qwenimage#diffusers.models.autoencoders.vae.DecoderOutput) ou `tuple`

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

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

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

Décodez un lot de latents avec la dernière étape déterministe et l'étape de diffusion exécutée par tuile.

Les tuiles sont positionnées sur la grille entrant dans la dernière étape déterministe, où une cellule correspond à un bloc fixe de pixels de sortie ; les tailles `tile_sample_*` sont converties vers cette grille, elles doivent donc être des multiples de la taille de cellule (8 px spatialement et 2 images temporellement pour la configuration de production). Les tuiles temporelles suivent la causalité du mappage des images : la tuile contenant t=0 supprime l'image de tête dupliquée par le suréchantillonnage temporel, et seule la tuile contenant la fin de la vidéo porte le padding de bordure NATTEN.