# WanAnimate2Transformer3DModel

Un modèle Diffusion Transformer pour des données vidéo 3D, utilisé dans [Wan-Animate-2](https://github.com/Wan-Video/Wan2.2) par l'équipe Alibaba Wan. Il anime une image de personnage avec le mouvement d'une vidéo de pilotage grâce à un mécanisme de référence en contexte : chaque segment exécute d'abord un passage de référence (`kv_cache_mode="extract"`) qui met en cache les K/V de référence de chaque couche, puis les passages de débruitage (`kv_cache_mode="cached"`) effectuent une attention conjointe sur les jetons de génération et les jetons de référence mis en cache via un `BlockMask` flexible.

Le modèle peut être chargé à l'aide du fragment de code suivant.

```python
from diffusers import WanAnimate2Transformer3DModel

transformer = WanAnimate2Transformer3DModel.from_pretrained("Wan-AI/Wan2.2-Animate-2-14B-Diffusers", subfolder="transformer", dtype=torch.bfloat16)
```

## WanAnimate2Transformer3DModel[[diffusers.WanAnimate2Transformer3DModel]]

#### diffusers.WanAnimate2Transformer3DModel[[diffusers.WanAnimate2Transformer3DModel]]

```python
diffusers.WanAnimate2Transformer3DModel(patch_size: tuple = (1, 2, 2), text_len: int = 512, in_dim: int = 36, dim: int = 5120, ffn_dim: int = 13824, freq_dim: int = 256, text_dim: int = 4096, out_dim: int = 16, num_heads: int = 40, num_layers: int = 40, cross_attn_norm: bool = True, eps: float = 1e-06, use_img_emb: bool = True, refer_offset_t: int = 1, refer_offset_h: int = 0, refer_offset_w: int = -1, refer_stride: int = 1)
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_wan_animate_2.py#L570)

**Paramètres :**

patch_size (*tuple[int]*, par défaut *(1, 2, 2)*) : dimensions des patches 3D pour l'intégration vidéo (t_patch, h_patch, w_patch).

text_len (*int*, par défaut *512*) : Longueur fixe pour les embeddings de texte.

in_dim (*int*, par défaut *36*) : Le nombre de canaux dans l'entrée (2 * latent_channels + 4 pour le canal de masque).

dim (*int*, par défaut *5120*) : Le nombre de canaux du transformer.

ffn_dim (*int*, par défaut *13824*) : Dimension intermédiaire du réseau feed-forward.

freq_dim (*int*, par défaut *256*) : Dimension pour les embeddings temporels sinusoïdaux.

text_dim (*int*, par défaut *4096*) : Dimension d'entrée pour les embeddings de texte.

out_dim (*int*, par défaut *16*) : Le nombre de canaux dans la sortie.

num_heads (*int*, par défaut *40*) : Le nombre de têtes d'attention.

num_layers (*int*, par défaut *40*) : Le nombre de blocs de transformeurs à utiliser.

cross_attn_norm (*bool*, par défaut *True*) : Active la normalisation de l'attention croisée.

eps (*float*, par défaut *1e-6*) : Valeur d'épsilon pour les couches de normalisation.

use_img_emb (*bool*, par défaut *True*) : Indique s'il faut utiliser l'embedding d'image CLIP.

refer_offset_t (*int*, par défaut *1*) : décalage RoPE pour la dimension temporelle de la référence.

refer_offset_h (*int*, par défaut *0*) : décalage RoPE pour la dimension de hauteur de la référence.

refer_offset_w (*int*, par défaut *-1*) : décalage RoPE pour la dimension de largeur de la référence. -1 signifie d'utiliser la taille de la grille de génération.

refer_stride (*int*, par défaut *1*) : Pas pour l'application de RoPE sur la référence.

Un modèle Transformer pour des données de type vidéo utilisé dans le modèle Wan-Animate-2.

Wan-Animate-2 utilise un mécanisme d’attention in-context avec un cache KV : une vidéo de référence est d’abord encodée (`kv_cache_mode="extract"`) pour alimenter un [*WanAnimate2KVCache*], puis chaque étape de débruitage (`kv_cache_mode="cached"`) porte conjointement sur les jetons de génération et sur les K/V de référence mis en cache via un `BlockMask` flexible. L’auto-attention de génération s’exécute donc uniquement sur le backend d’attention `flex` ; toutes les autres attentions du modèle fonctionnent sur n’importe quel backend.

#### forward[[diffusers.WanAnimate2Transformer3DModel.forward]]

```python
forward(hidden_states: list[torch.Tensor], timestep: Tensor, encoder_hidden_states: list[torch.Tensor], condition_latents: list[torch.Tensor], kv_cache: WanAnimate2KVCache, kv_cache_mode: str, seq_len: int, encoder_hidden_states_image: typing.Optional[torch.Tensor] = None, offset_grid_sizes: typing.Optional[torch.Tensor] = None, reference_grid_sizes: typing.Optional[torch.Tensor] = None, origin_len: int | None = None, origin_area: list[int] | None = None, is_uncondtion: bool = False, return_dict: bool = True)
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_wan_animate_2.py#L766)

**Paramètres :**

hidden_states (`list[torch.Tensor]`) : Latents pour ce passage — les latents de référence lorsque `kv_cache_mode="extract"`, les latents de génération bruités lorsque `kv_cache_mode="cached"`.

timestep (`torch.Tensor`) : Pas de débruitage. Ignoré lorsque `kv_cache_mode="extract"`, qui utilise un pas fixe de 1.

encoder_hidden_states (`list[torch.Tensor]`) : Embeddings de texte pour ce passage.

condition_latents (`list[torch.Tensor]`) : Latents de conditionnement concaténés à `hidden_states` avant l'encodage par patch.

kv_cache (`WanAnimate2KVCache`) : écrit avec `kv_cache_mode="extract"`, lu avec `"cached"`.

kv_cache_mode (`str`) : `"extract"` exécute le passage de référence et remplit `kv_cache` ; `"cached"` exécute une étape de débruitage sur les jetons de référence mis en cache.

seq_len (`int`) : Nombre de jetons que chaque exemple doit contenir après l'encodage de patch.

encoder_hidden_states_image (`torch.Tensor`, *facultatif*) : embeddings d'images CLIP, utilisés lorsque le modèle est configuré avec `use_img_emb`.

offset_grid_sizes (`torch.Tensor`, *facultatif*) : Grille de patches des latents de référence, utilisée pour résoudre tout `refer_offset_*` défini à -1. Obligatoire avec `kv_cache_mode="extract"` ; avec `"cached"`, `reference_grid_sizes` décrit la même grille et est utilisé à la place.

reference_grid_sizes (`torch.Tensor`, *facultatif*) : Grille de patches des latents de référence, utilisée pour les embeddings rotationnels de référence. Obligatoire avec `kv_cache_mode="cached"`.

origin_len (`int`, *facultatif*) : Nombre de frames de la vidéo complète, sur lequel le masque de blocs in-context est construit. Requis lorsque `kv_cache_mode="cached"`.

origin_area (`list[int]`, *facultatif*) : Taille spatiale `[height, width]` de la vidéo complète, sur laquelle le masque de blocs in-context est construit. Obligatoire avec `kv_cache_mode="cached"`.

is_uncondtion (`bool`, *facultatif*) : Indique s'il s'agit de la branche inconditionnelle du guidage sans classifieur.

return_dict (`bool`, *facultatif*, par défaut `True`) : Indique s'il faut retourner un `~models.transformer_2d.Transformer2DModelOutput` plutôt qu'un simple tuple.

**Retourne :** [Transformer2DModelOutput](/docs/diffusers/v0.43.0/fr/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) ou `tuple(list[torch.Tensor])`

L'échantillon prédit par latent d'entrée, non patchifié ; un simple tuple si `return_dict` est `False`.

## Transformer2DModelOutput[[diffusers.models.modeling_outputs.Transformer2DModelOutput]]

#### diffusers.models.modeling_outputs.Transformer2DModelOutput[[diffusers.models.modeling_outputs.Transformer2DModelOutput]]

```python
diffusers.models.modeling_outputs.Transformer2DModelOutput(sample: torch.Tensor)
```

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

**Paramètres :**

sample (`torch.Tensor` de forme `(batch_size, num_channels, height, width)` ou `(batch size, num_vector_embeds - 1, num_latent_pixels)` si [Transformer2DModel](/docs/diffusers/v0.43.0/fr/api/models/transformer2d#diffusers.Transformer2DModel) est discret) : Les états cachés en sortie, conditionnés par l'entrée `encoder_hidden_states`. Si discret, renvoie les distributions de probabilité pour les pixels latents non bruités.

La sortie de [Transformer2DModel](/docs/diffusers/v0.43.0/fr/api/models/transformer2d#diffusers.Transformer2DModel).