# MiniMaxH3Transformer3DModel

Um modelo Diffusion Transformer para geração conjunta de vídeo e áudio, introduzido em [MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3) pela MiniMax.

MiniMax-H3 executa uma única pilha de blocos sobre **uma sequência 1-D empacotada** que contém, de uma só vez, o condicionamento de texto, as linhas da imagem de condicionamento e do vídeo, as linhas de áudio e as linhas do vídeo de destino. A atenção é autoatenção completa sobre essa sequência, portanto não há atenção cruzada nem pesos de bloco por modalidade. O comportamento específico de cada modalidade vem apenas das duas projeções de patch de entrada, da tag de modalidade por linha que seleciona os parâmetros de modulação AdaLN e das duas cabeças de saída.

A construção do layout empacotado é responsabilidade do chamador, motivo pelo qual a assinatura do forward recebe o layout separado dos latentes: a grade de posições `(t, h, w)`, as tags de modalidade por linha, os índices de timestep por linha e os três tensores de índice que endereçam as linhas de vídeo, áudio e texto. [MiniMaxH3Blocks](/docs/diffusers/v0.43.0/pt/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks) e `MiniMaxH3Ref2VABlocks` constroem tudo isso.

Um layout que carrega linhas de padding (tag `-1`) precisa de um backend de atenção mascarada, pois essas linhas são mantidas em seu próprio documento de atenção por uma máscara booleana; uma sequência sem padding não precisa de máscara e mantém todos os backends disponíveis.

Um repositório contém as partições de checkpoint liberadas, portanto, a subpasta é o que seleciona a tarefa: `transformer/` para as tarefas de texto e keyframe, `transformer_ref/` para a tarefa 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"
```

O checkpoint é de precisão mista: as duas projeções de entrada de patch, o MLP de timestep e as duas saídas são float32, enquanto a pilha de blocos é bfloat16. `from_pretrained` mantém esse layout por meio de `_keep_in_fp32_modules`, então passe `dtype=torch.bfloat16` e deixe que ele posicione os módulos float32, em vez de converter o modelo com `.to(torch.bfloat16)` depois.

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

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

**Parâmetros:**

num_attention_heads (`int`, padrão `56`) : O número de cabeças a serem usadas para a atenção multi-cabeça.

attention_head_dim (`int`, padrão `128`) : O número de canais em cada cabeça de atenção. Observe que `num_attention_heads * attention_head_dim` é *maior* que `hidden_size` no MiniMax-H3.

hidden_size (`int`, padrão `5376`) : O número de canais da sequência empacotada (o fluxo residual).

num_layers (`int`, padrão `50`) : O número de blocos do transformer.

num_refiner_layers (`int`, padrão `2`) : O número de blocos de refinamento de tokens aplicados ao fluxo de texto projetado.

ffn_dim (`int`, padrão `14336`) : A dimensão interna das camadas feed-forward SwiGLU.

in_channels (`int`, padrão `24`) : O número de canais dos latentes do vídeo.

audio_in_channels (`int`, padrão `32`) : O número de canais dos latentes de áudio.

patch_size (`tuple[int, int, int]`, padrão `(1, 2, 2)`) : O patch `(t, h, w)` usado para empacotar os latentes do vídeo em linhas.

text_dim (`int`, padrão `5120`) : O número de canais da condição de texto produzida pelo codificador de texto.

freq_dim (`int`, padrão `256`) : A dimensão do embedding sinusoidal de timestep. Os timesteps são consumidos sem escala em `[0, 1]`.

time_embed_hidden_dim (`int`, padrão `5376`) : A dimensão interna do MLP de timestep.

time_embed_dim (`int`, padrão `2688`) : A dimensão de saída do MLP de timestep, ou seja, a entrada de cada projeção AdaLN.

rope_freq_dim (`int`, padrão `16`) : O número de frequências rotativas por eixo. Os eixos `(t, h, w)` compartilham um buffer `inv_freq` deste comprimento e `2 * 3 * rope_freq_dim` dos canais de `attention_head_dim` são rotacionados.

rope_theta (`float`, padrão `10000.0`) : A base da agenda de frequência rotativa a partir da qual o buffer `rope.inv_freq` é calculado.

norm_eps (`float`, padrão `1e-5`) : Epsilon das normalizações pré-atenção e pré-feed-forward.

qk_norm_eps (`float`, padrão `1e-5`) : Epsilon das normas de query/key por cabeça.

final_norm_eps (`float`, padrão `1e-5`) : Epsilon da normalização da saída do refinador de tokens e de `norm_out`.

Um modelo Transformer para geração conjunta de vídeo + áudio, introduzido no MiniMax-H3.

MiniMax-H3 executa uma única pilha de blocos sobre **uma sequência 1-D empacotada** que contém a condição de texto, as linhas da imagem/vídeo de condicionamento, as linhas de áudio e as linhas do vídeo alvo. A atenção é autoatenção completa sobre essa sequência; não há atenção cruzada nem pesos de bloco por modalidade. O comportamento específico de cada modalidade vem apenas das duas projeções de patch de entrada, da tag de modalidade AdaLN por linha e dos dois cabeçalhos de saída.

O chamador é responsável por construir o layout empacotado: aplicar patchify aos latentes do vídeo, ordenar as linhas e produzir a grade de posições `(t, h, w)`, as tags de modalidade por linha e os índices de timestep por linha. A sequência não possui padding — a implementação de referência faz padding até um múltiplo de 64 para FlashAttention e separa o final com `cu_seqlens = [0, used, S]`, o que esta portabilidade não utiliza —, portanto a atenção é executada sem máscara sobre um único documento e todos os backends de atenção permanecem disponíveis.

O eixo de lote é um eixo de replicação pura: os argumentos estruturais (`timestep`, `timestep_indices`, `token_tags`, `position_ids` e os três tensores de índice) descrevem um único layout empacotado compartilhado por todos os itens do lote, e cada item é um único documento de atenção.

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

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

**Parâmetros:**

hidden_states (`torch.Tensor` de forma `(batch_size, num_video_tokens, in_channels * prod(patch_size))`) : Linhas de latentes de vídeo em patches — linhas de condicionamento e linhas de alvo — ordenadas conforme aparecem na sequência empacotada, ou seja, correspondendo a `video_indices`.

audio_hidden_states (`torch.Tensor` de forma `(batch_size, num_audio_tokens, audio_in_channels)`) : Linhas latentes de áudio, ordenadas para corresponder a `audio_indices`.

encoder_hidden_states (`torch.Tensor` de forma `(batch_size, num_text_tokens, text_dim)`) : Condição de texto, ordenada para corresponder a `text_indices`.

timestep (`torch.Tensor` de forma `(num_timesteps,)`) : Os valores de timestep *distintos* presentes na sequência empacotada, em `[0, 1]` e sem escala. Uma única forward atende linhas em diferentes níveis de ruído (vídeo alvo, áudio alvo, linhas de condicionamento).

timestep_indices (`torch.Tensor` de forma `(seq_len,)`) : Para cada linha da sequência empacotada, o índice de seu timestep em `timestep`.

token_tags (`torch.Tensor` de forma `(seq_len,)`) : Para cada linha da sequência empacotada, sua modalidade: `0` vídeo, `1` texto, `2` áudio.

position_ids (`torch.Tensor` de forma `(seq_len, 3)`) : As coordenadas rotacionais `(t, h, w)` de cada linha da sequência empacotada.

video_indices (`torch.Tensor` de forma `(num_video_tokens,)`) : Posições das linhas de vídeo na sequência empacotada.

audio_indices (`torch.Tensor` de forma `(num_audio_tokens,)`) : Posições das linhas de áudio na sequência empacotada.

text_indices (`torch.Tensor` de forma `(num_text_tokens,)`) : Posições das linhas de texto na sequência empacotada.

attention_kwargs (`dict`, *opcional*) : Um dicionário de kwargs que, se especificado, pode conter uma entrada `scale` que é aplicada às camadas LoRA.

return_dict (`bool`, padrão `True`) : Se deve retornar um `MiniMaxH3TransformerOutput` em vez de uma tupla simples.

**Retorna:** `MiniMaxH3TransformerOutput` ou `tuple`

A velocidade do vídeo de forma `(batch_size, num_video_tokens, in_channels * prod(patch_size))` e a velocidade do áudio de forma `(batch_size, num_audio_tokens, audio_in_channels)`, na ordem das linhas de `video_indices` e `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)
```

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

**Parâmetros:**

sample (`torch.Tensor` de forma `(batch_size, num_video_tokens, in_channels * prod(patch_size))`) : A previsão de velocidade do vídeo para as linhas endereçadas por `video_indices`, na mesma ordem. As linhas de condicionamento são retornadas sem máscara — mascará-las antes da etapa do agendador é responsabilidade do chamador.

audio_sample (`torch.Tensor` de forma `(batch_size, num_audio_tokens, audio_in_channels)`, padrão `None`) : A predição de velocidade do áudio para as linhas endereçadas por `audio_indices`, na mesma ordem. `forward` sempre preenche esse campo; ele só tem valor padrão `None` para que a saída possa ser reconstruída a partir de um dicionário simples de seus campos, que é a forma como os hooks de offload do accelerate movem um `BaseOutput` de volta para o dispositivo de entrada.

A saída de [MiniMaxH3Transformer3DModel](/docs/diffusers/v0.43.0/pt/api/models/minimax_h3_transformer3d#diffusers.MiniMaxH3Transformer3DModel).