# MiniMaxH3Transformer3DModel

Un modèle Diffusion Transformer pour la génération conjointe de vidéo et d'audio, introduit dans [MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3) par MiniMax.

MiniMax-H3 exécute une pile unique de blocs sur **une séquence 1-D compacte** qui contient simultanément le conditionnement texte, les lignes d’image de conditionnement et de vidéo, les lignes audio et les lignes de vidéo cible. L’attention est une auto-attention complète sur cette séquence, il n’y a donc ni attention croisée ni poids de bloc par modalité. Le comportement spécifique à chaque modalité provient uniquement des deux projections de patch d’entrée, de l’étiquette de modalité par ligne qui sélectionne les paramètres de modulation AdaLN, et des deux têtes de sortie.

La construction de la mise en page compacte est à la charge de l'appelant, c'est pourquoi la signature de la méthode forward reçoit la mise en page séparément des latents : la grille de positions `(t, h, w)`, les étiquettes de modalité par ligne, les indices de pas de temps par ligne et les trois tenseurs d'index qui adressent les lignes vidéo, audio et texte. [MiniMaxH3Blocks](/docs/diffusers/v0.43.0/fr/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks) et `MiniMaxH3Ref2VABlocks` construisent l'ensemble.

Un layout qui comporte des lignes de bourrage (tag `-1`) nécessite un backend d'attention masquée, car ces lignes sont conservées dans leur propre document d'attention par un masque booléen ; une séquence sans bourrage n'a besoin d'aucun masque et conserve tous les backends disponibles.

Un seul dépôt contient les partitions de points de contrôle publiés, c'est donc le sous-dossier qui sélectionne la tâche : `transformer/` pour les tâches de texte et de keyframe, `transformer_ref/` pour la tâche omni-reference.

```python
import torch
from diffusers import MiniMaxH3Transformer3DModel

transformer = MiniMaxH3Transformer3DModel.from_pretrained(
    "MiniMaxAI/MiniMax-H3", subfolder="transformer", dtype=torch.bfloat16
).to("cuda")  # or "mps", "xpu", "cpu"
```

Le point de contrôle est en précision mixte : les deux projections d’entrée de patch, le MLP de pas de temps et les deux têtes de sortie sont en float32, tandis que la pile de blocs est en bfloat16. `from_pretrained` conserve cette organisation grâce à `_keep_in_fp32_modules` ; passez donc `dtype=torch.bfloat16` et laissez-le placer les modules en float32, plutôt que de convertir le modèle avec `.to(torch.bfloat16)` par la suite.

## MiniMaxH3Transformer3DModel[[diffusers.MiniMaxH3Transformer3DModel]]

#### diffusers.MiniMaxH3Transformer3DModel[[diffusers.MiniMaxH3Transformer3DModel]]

```python
diffusers.MiniMaxH3Transformer3DModel(num_attention_heads: int = 56, attention_head_dim: int = 128, hidden_size: int = 5376, num_layers: int = 50, num_refiner_layers: int = 2, ffn_dim: int = 14336, in_channels: int = 24, audio_in_channels: int = 32, patch_size: tuple[int, int, int] = (1, 2, 2), text_dim: int = 5120, freq_dim: int = 256, time_embed_hidden_dim: int = 5376, time_embed_dim: int = 2688, rope_freq_dim: int = 16, rope_theta: float = 10000.0, norm_eps: float = 1e-05, qk_norm_eps: float = 1e-05, final_norm_eps: float = 1e-05)
```

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

**Paramètres :**

num_attention_heads (`int`, par défaut `56`) : Le nombre de têtes à utiliser pour l'attention multi-têtes.

attention_head_dim (`int`, par défaut `128`) : Le nombre de canaux dans chaque tête d'attention. Notez que `num_attention_heads * attention_head_dim` est *supérieur* à `hidden_size` dans MiniMax-H3.

hidden_size (`int`, par défaut `5376`) : Le nombre de canaux de la séquence compactée (le flux résiduel).

num_layers (`int`, par défaut `50`) : Le nombre de blocs transformer.

num_refiner_layers (`int`, par défaut `2`) : Le nombre de blocs de raffinement de jetons appliqués au flux de texte projeté.

ffn_dim (`int`, par défaut `14336`) : La dimension interne des couches feed-forward SwiGLU.

in_channels (`int`, par défaut `24`) : Le nombre de canaux des latents vidéo.

audio_in_channels (`int`, par défaut `32`) : Le nombre de canaux des latents audio.

patch_size (`tuple[int, int, int]`, par défaut `(1, 2, 2)`) : le patch `(t, h, w)` utilisé pour empiler les latents vidéo en lignes.

text_dim (`int`, par défaut `5120`) : Le nombre de canaux de la condition de texte produite par l'encodeur de texte.

freq_dim (`int`, par défaut `256`) : La dimension de l'encodage sinusoïdal des pas de temps. Les pas de temps sont consommés non mis à l'échelle dans `[0, 1]`.

time_embed_hidden_dim (`int`, par défaut `5376`) : La dimension interne du MLP de pas de temps.

time_embed_dim (`int`, par défaut `2688`) : La dimension de sortie du MLP de pas de temps, c'est-à-dire l'entrée de chaque projection AdaLN.

rope_freq_dim (`int`, par défaut `16`) : Le nombre de fréquences rotatives par axe. Les axes `(t, h, w)` partagent un tampon `inv_freq` de cette longueur et `2 * 3 * rope_freq_dim` des canaux `attention_head_dim` sont rotés.

rope_theta (`float`, par défaut `10000.0`) : La base du calendrier de fréquences rotatives à partir duquel le tampon `rope.inv_freq` est calculé.

norm_eps (`float`, par défaut `1e-5`) : Epsilon des normalisations pré-attention et pré-feed-forward.

qk_norm_eps (`float`, par défaut `1e-5`) : Epsilon des normes de requête/clé par tête.

final_norm_eps (`float`, par défaut `1e-5`) : Epsilon de la norme de sortie du raffineur de jetons et de `norm_out`.

Un modèle Transformer pour la génération conjointe de vidéo + audio, introduit dans MiniMax-H3.

MiniMax-H3 exécute une pile unique de blocs sur **une séquence 1-D compacte** qui contient la condition texte, les lignes d'image/vidéo de conditionnement, les lignes audio et les lignes de vidéo cible. L'attention est une auto-attention complète sur cette séquence ; il n'y a ni attention croisée ni poids de bloc par modalité. Le comportement spécifique à chaque modalité provient uniquement des deux projections de patch d'entrée, de l'étiquette de modalité AdaLN par ligne et des deux têtes de sortie.

L'appelant est responsable de la construction de la mise en page compacte : patchification des latents vidéo, ordonnancement des lignes et production de la grille de positions `(t, h, w)`, des étiquettes de modalité par ligne et des indices de pas de temps par ligne. La séquence ne contient aucun bourrage — l'implémentation de référence la bourre jusqu'à un multiple de 64 pour FlashAttention et isole la fin avec `cu_seqlens = [0, used, S]`, ce dont ce port n'a pas besoin — de sorte que l'attention s'exécute sans masque sur un seul document et que tous les backends d'attention restent disponibles.

L'axe de lot est un axe de pure réplication : les arguments structurels (`timestep`, `timestep_indices`, `token_tags`, `position_ids` et les trois tenseurs d'indices) décrivent une mise en page compacte unique partagée par tous les éléments du lot, et chaque élément est un document d'attention unique.

#### forward[[diffusers.MiniMaxH3Transformer3DModel.forward]]

```python
forward(hidden_states: Tensor, audio_hidden_states: Tensor, encoder_hidden_states: Tensor, timestep: Tensor, timestep_indices: Tensor, token_tags: Tensor, position_ids: Tensor, video_indices: Tensor, audio_indices: Tensor, text_indices: Tensor, attention_kwargs: dict[str, typing.Any] | None = None, return_dict: bool = True)
```

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

**Paramètres :**

hidden_states (`torch.Tensor` de forme `(batch_size, num_video_tokens, in_channels * prod(patch_size))`) : Lignes latentes vidéo patchifiées — lignes de conditionnement et lignes cibles — ordonnées comme elles apparaissent dans la séquence packée, c’est-à-dire correspondant à `video_indices`.

audio_hidden_states (`torch.Tensor` de forme `(batch_size, num_audio_tokens, audio_in_channels)`) : Lignes latentes audio, ordonnées pour correspondre à `audio_indices`.

encoder_hidden_states (`torch.Tensor` de forme `(batch_size, num_text_tokens, text_dim)`) : Conditionnement par le texte, ordonné pour correspondre à `text_indices`.

timestep (`torch.Tensor` de forme `(num_timesteps,)`) : Les valeurs de pas de temps *distinctes* présentes dans la séquence compacte, dans `[0, 1]` et non échelonnées. Un seul passage avant sert des lignes à différents niveaux de bruit (vidéo cible, audio cible, lignes de conditionnement).

timestep_indices (`torch.Tensor` de forme `(seq_len,)`) : Pour chaque ligne de la séquence compactée, l'index de son pas de temps dans `timestep`.

token_tags (`torch.Tensor` de forme `(seq_len,)`) : Pour chaque ligne de la séquence compactée, sa modalité : `0` vidéo, `1` texte, `2` audio.

position_ids (`torch.Tensor` de forme `(seq_len, 3)`) : Les coordonnées rotatives `(t, h, w)` de chaque ligne de la séquence compactée.

video_indices (`torch.Tensor` de forme `(num_video_tokens,)`) : Positions des lignes de la vidéo dans la séquence compactée.

audio_indices (`torch.Tensor` de forme `(num_audio_tokens,)`) : Positions des lignes audio dans la séquence compactée.

text_indices (`torch.Tensor` de forme `(num_text_tokens,)`) : Positions des lignes de texte dans la séquence compactée.

attention_kwargs (`dict`, *facultatif*) : Un dictionnaire de kwargs qui, s'il est spécifié, peut contenir une entrée `scale` appliquée aux couches LoRA.

return_dict (`bool`, par défaut `True`) : Indique s'il faut retourner un `MiniMaxH3TransformerOutput` plutôt qu'un simple tuple.

**Retourne :** `MiniMaxH3TransformerOutput` ou `tuple`

La vitesse vidéo de forme `(batch_size, num_video_tokens, in_channels * prod(patch_size))` et la vitesse audio de forme `(batch_size, num_audio_tokens, audio_in_channels)`, dans l'ordre des lignes de `video_indices` et `audio_indices`.

## MiniMaxH3TransformerOutput[[diffusers.models.transformers.transformer_minimax_h3.MiniMaxH3TransformerOutput]]

#### diffusers.models.transformers.transformer_minimax_h3.MiniMaxH3TransformerOutput[[diffusers.models.transformers.transformer_minimax_h3.MiniMaxH3TransformerOutput]]

```python
diffusers.models.transformers.transformer_minimax_h3.MiniMaxH3TransformerOutput(sample: Tensor, audio_sample: typing.Optional[torch.Tensor] = None)
```

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

**Paramètres :**

sample (`torch.Tensor` de forme `(batch_size, num_video_tokens, in_channels * prod(patch_size))`) : La prédiction de vélocité vidéo pour les lignes adressées par `video_indices`, dans le même ordre. Les lignes de conditionnement sont renvoyées non masquées — il incombe à l'appelant de les masquer avant l'étape du planificateur.

audio_sample (`torch.Tensor` de forme `(batch_size, num_audio_tokens, audio_in_channels)`, par défaut `None`) : La prédiction de la vélocité audio pour les lignes adressées par `audio_indices`, dans le même ordre. `forward` la remplit toujours ; elle ne prend la valeur `None` par défaut que pour permettre la reconstruction de la sortie à partir d'un simple dictionnaire de ses champs, ce qui est la méthode utilisée par les hooks de déchargement d'accelerate pour renvoyer un `BaseOutput` vers le périphérique d'entrée.

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