# SanaWMTransformer3DModel

Un Diffusion Transformer 3D (1,6 Md de paramètres) pour la génération d'images en vidéo contrôlée par caméra, utilisé comme échantillonneur de l'étape 1 de [SanaWMPipeline](/docs/diffusers/v0.43.0/fr/api/pipelines/sana_wm#diffusers.SanaWMPipeline). Le transformer combine :

* une branche principale d'attention linéaire GDN-Triton bidirectionnelle (profondeur 20, 2240 cachés, 20 têtes),
* une branche de contrôle de caméra UCPE (Unified Camera Pose Embedding) qui consomme une représentation raymap + Plücker de la trajectoire demandée, et
* un embedding de position rotatif 3D de type Wan, ainsi que des blocs d'attention softmax périodiques injectés toutes les `softmax_every_n` couches.

Le modèle peut être chargé avec :

```python
import torch
from diffusers import SanaWMTransformer3DModel

transformer = SanaWMTransformer3DModel.from_pretrained(
    "Efficient-Large-Model/SANA-WM_bidirectional-diffusers",
    subfolder="transformer",
    torch_dtype=torch.bfloat16,
)
```

## SanaWMTransformer3DModel[[diffusers.SanaWMTransformer3DModel]]

#### diffusers.SanaWMTransformer3DModel[[diffusers.SanaWMTransformer3DModel]]

```python
diffusers.SanaWMTransformer3DModel(in_channels: int = 128, num_layers: int = 20, hidden_size: int = 2240, num_attention_heads: int = 20, patch_size: tuple[int, int, int] = (1, 1, 1), softmax_every_n: int = 4, linear_head_dim: int = 112, ffn_type: str = 'GLUMBConvTemp', t_kernel_size: int = 3, conv_kernel_size: int = 4, k_conv_only: bool = True, pos_embed_type: str = 'wan_rope', qk_norm: bool = True, cross_norm: bool = True, y_norm: bool = True, cam_attn_compress: int = 1, init_cam_from_base: bool = True, use_chunk_plucker_post_attn: bool = True, chunk_plucker_channels: int = 48, chunk_plucker_post_attn_blocks: int = 20, fp32_attention: bool = True, image_size: int = 720, caption_channels: int = 2304, mlp_ratio: float = 3.0, mlp_acts: tuple = ('silu', 'silu', None), use_pe: bool = True, learn_sigma: bool = False, pred_sigma: bool = False, mixed_precision: str = 'bf16')
```

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

**Paramètres :**

in_channels (*int*, par défaut 128) : canaux latents du VAE (LTX-2).

softmax_every_n (*int*, par défaut 4) : Utiliser un bloc d'attention softmax tous les N blocs.

linear_head_dim (*int*, par défaut 112) : dimension de la tête GDN.

ffn_type (*str*, par défaut `"GLUMBConvTemp"`) : FFN.

t_kernel_size (*int*, par défaut 3) : Noyau de convolution temporelle.

conv_kernel_size (*int*, par défaut 4) : noyau de convolution spatiale dans l'attention.

k_conv_only (*bool*, par défaut True) : Appliquer la convolution uniquement sur K.

pos_embed_type (*str*, par défaut `"wan_rope"`) : Intégration de position.

qk_norm (*bool*, par défaut True) : RMSNorm sur Q/K.

cross_norm (*bool*, par défaut True) : RMSNorm sur le K de l'attention croisée.

y_norm (*bool*, par défaut True) : Appliquer `attention_y_norm` aux embeddings de texte.

init_cam_from_base (*bool*, par défaut True) : Non utilisé ; la branche caméra est chargée depuis le point de contrôle. Conservé afin que les fichiers *config.json* publiés puissent être chargés.

use_chunk_plucker_post_attn (*bool*, par défaut True). --

chunk_plucker_channels (*int*, par défaut 48) : `6 dims * temporal_stride 8`.

chunk_plucker_post_attn_blocks (*int*, par défaut 20) : Tous les blocs.

fp32_attention (*bool*, par défaut True) : Non utilisé ; l'attention s'exécute toujours en fp32. Conservé afin que les fichiers *config.json* publiés puissent être chargés.

image_size (*int*, par défaut 720) : Taille nominale de l'image.

caption_channels (*int*, par défaut 2304) : taille cachée de Gemma-2.

SANA-WM 1600M DiT bidirectionnel contrôlé par caméra.

Un DiT à classe unique (depth=20, hidden_size=2240, patch_size=(1,1,1), num_heads=20 — c’est-à-dire la version publique `Efficient-Large-Model/SANA-WM_bidirectional`). `save_pretrained` / `from_pretrained` fonctionnent immédiatement via [ConfigMixin](/docs/diffusers/v0.43.0/fr/api/configuration#diffusers.ConfigMixin).

Chaque bloc exécute une attention conditionnée par la caméra (UCPE) : [*BidirectionalGDNUCPESinglePathLiteLA*], à l'exception de chaque `softmax_every_n`-ième bloc, qui exécute son équivalent softmax [*_SoftmaxUCPESinglePathLiteLA*].

Le state-dict est identique au checkpoint public sana, à l'exception du tampon `pos_embed` supprimé intentionnellement.

#### forward[[diffusers.SanaWMTransformer3DModel.forward]]

```python
forward(hidden_states: torch.Tensor, timestep: torch.Tensor, encoder_hidden_states: torch.Tensor, encoder_attention_mask: torch.Tensor | None = None, mask: torch.Tensor | None = None, return_dict: bool = True, data_info: Optional[dict] = None, camera_conditions: torch.Tensor | None = None, chunk_plucker: torch.Tensor | None = None, cam_pos_embeds: Optional[dict] = None, pos_embeds: torch.Tensor | None = None, raymats: torch.Tensor | None = None, frame_valid_mask: torch.Tensor | None = None, chunk_size: int | None = None)
```

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

**Paramètres :**

hidden_states : latents de forme `(B, C, T, H, W)`.

timestep : `(B, 1, T)` timesteps de diffusion par image (style LTX).

encoder_hidden_states : `(B, 1, L, D_caption)` embeddings de texte.

encoder_attention_mask : `(B, L)` masque d'attention du texte (convention de diffusers).

mask : Alias de `encoder_attention_mask` correspondant au nom du paramètre du DiT sana. Si les deux sont fournis, `mask` a la priorité.

return_dict : Si `True` (par défaut), renvoie un `Transformer2DModelOutput` ; sinon, renvoie un tuple unique `(sample,)`.

data_info : Conditionnement supplémentaire ; `data_info["image_vae_embeds"]` est concaténé aux latents le long de l'axe des canaux lorsqu'il est présent.

camera_conditions : `(B, T, 20)` conditions brutes de caméra pilotant la branche de contrôle de la caméra (UCPE).

chunk_plucker : Plucker ray embeddings `(B, C, T, H, W)`, consommés lorsque le modèle est configuré avec `use_chunk_plucker_input` / `use_chunk_plucker_post_attn`.

cam_pos_embeds : Incrustations de position de caméra précalculées optionnelles (entrées `"absmap"` / `"P"`) réutilisées à la place d'un recalcul.

pos_embeds : embeddings de position rotative précalculés facultatifs ; lorsque `None`, ils sont construits à partir de la forme latente.

raymats : Matrices de rayons UCPE précalculées (utilisées uniquement lorsque `cam_pos_embeds` ne contient pas `"P"`).

frame_valid_mask : masque de validité par image facultatif, de forme `(B, 1, T, 1, 1)`, `(B, 1, T)` ou `(B, T)`.

chunk_size : Longueur de bloc à appliquer, transmise aux blocs ; en cas d'absence, la valeur `chunk_size` configurée pour chaque bloc est utilisée.

**Retourne :**

`Transformer2DModelOutput` avec `sample` de forme `(B, C, T, H, W)`.

Exécuter le DiT de SANA-WM.

#### unpatchify[[diffusers.SanaWMTransformer3DModel.unpatchify]]

```python
unpatchify(x, post_patch_num_frames, post_patch_height, post_patch_width)
```

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

x: (N, T, patch_size**2 * C) imgs: (N, H, W, C)

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