# MiniMaxH3Transformer3DModel

Un modelo Diffusion Transformer para la generación conjunta de video y audio, introducido en [MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3) por MiniMax.

MiniMax-H3 ejecuta una única pila de bloques sobre **una secuencia 1-D empaquetada** que contiene a la vez la condición de texto, las filas de imagen de condición y de video, las filas de audio y las filas de video objetivo. La atención es autoatención completa sobre esa secuencia, por lo que no hay atención cruzada ni pesos de bloques por modalidad. El comportamiento específico de cada modalidad proviene únicamente de las dos proyecciones de parches de entrada, la etiqueta de modalidad por fila que selecciona los parámetros de modulación AdaLN y las dos cabezas de salida.

La construcción del empaquetado es responsabilidad del llamador, por lo que la firma de forward recibe el layout por separado de los latentes: la cuadrícula de posiciones `(t, h, w)`, las etiquetas de modalidad por fila, los índices de paso temporal por fila y los tres tensores de índice que dirigen a las filas de video, audio y texto. [MiniMaxH3Blocks](/docs/diffusers/v0.43.0/es/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks) y `MiniMaxH3Ref2VABlocks` construyen todo esto.

Un layout que incluye filas de relleno (etiqueta `-1`) requiere un backend de atención enmascarada, ya que dichas filas se mantienen en su propio documento de atención mediante una máscara booleana; una secuencia sin relleno no necesita máscara y mantiene todos los backends disponibles.

Un repositorio contiene las particiones de puntos de control publicadas, por lo que la subcarpeta es lo que selecciona la tarea: `transformer/` para las tareas de texto y fotogramas clave, y `transformer_ref/` para la tarea de referencia omni.

```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"
```

El checkpoint es de precisión mixta: las dos proyecciones de entrada de parches, el MLP de paso de tiempo y las dos cabezas de salida son float32, mientras que la pila de bloques es bfloat16. `from_pretrained` mantiene ese diseño a través de `_keep_in_fp32_modules`, por lo que debe pasar `dtype=torch.bfloat16` y dejar que coloque los módulos float32, en lugar de convertir el modelo con `.to(torch.bfloat16)` después.

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

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

**Parámetros:**

num_attention_heads (`int`, por defecto `56`) : El número de cabezas a utilizar para la atención multi-cabeza.

attention_head_dim (`int`, por defecto `128`) : El número de canales en cada cabeza de atención. Tenga en cuenta que `num_attention_heads * attention_head_dim` es *mayor* que `hidden_size` en MiniMax-H3.

hidden_size (`int`, por defecto `5376`) : El número de canales de la secuencia empaquetada (el flujo residual).

num_layers (`int`, por defecto `50`) : El número de bloques de transformer.

num_refiner_layers (`int`, por defecto `2`) : El número de bloques de refinamiento de tokens aplicados al flujo de texto proyectado.

ffn_dim (`int`, por defecto `14336`) : La dimensión interna de las capas de retroalimentación SwiGLU.

in_channels (`int`, por defecto `24`) : El número de canales de los latentes del video.

audio_in_channels (`int`, por defecto `32`) : El número de canales de los latentes de audio.

patch_size (`tuple[int, int, int]`, por defecto `(1, 2, 2)`) : El parche `(t, h, w)` utilizado para empaquetar los latentes del video en filas.

text_dim (`int`, por defecto `5120`) : El número de canales de la condición de texto producida por el codificador de texto.

freq_dim (`int`, por defecto `256`) : La dimensión de la incrustación sinusoidal del paso de tiempo. Los pasos de tiempo se consumen sin escalar en `[0, 1]`.

time_embed_hidden_dim (`int`, por defecto `5376`) : La dimensión interna del MLP de paso temporal.

time_embed_dim (`int`, por defecto `2688`) : La dimensión de salida del MLP de timestep, es decir, la entrada de cada proyección AdaLN.

rope_freq_dim (`int`, por defecto `16`) : El número de frecuencias rotatorias por eje. Los ejes `(t, h, w)` comparten un búfer `inv_freq` de esta longitud y `2 * 3 * rope_freq_dim` de los canales de `attention_head_dim` se rotan.

rope_theta (`float`, por defecto `10000.0`) : La base del programa de frecuiones rotatorias desde el que se calcula el búfer `rope.inv_freq`.

norm_eps (`float`, por defecto `1e-5`) : Epsilon de las normas pre-atención y pre-feed-forward.

qk_norm_eps (`float`, por defecto `1e-5`) : Epsilon de las normas de consulta/clave por cabeza.

final_norm_eps (`float`, por defecto `1e-5`) : Epsilon de la normalización de la salida del refinador de tokens y de `norm_out`.

Un modelo Transformer para la generación conjunta de video + audio, introducido en MiniMax-H3.

MiniMax-H3 ejecuta una única pila de bloques sobre **una secuencia 1-D empaquetada** que contiene la condición de texto, las filas de imagen/video de condicionamiento, las filas de audio y las filas de video objetivo. La atención es autoatención completa sobre esa secuencia; no hay atención cruzada ni pesos de bloques por modalidad. El comportamiento específico de cada modalidad proviene únicamente de las dos proyecciones de parches de entrada, la etiqueta de modalidad AdaLN por fila y las dos cabezas de salida.

El llamador es responsable de construir el empaquetado: aplicar patchify a los latentes del video, ordenar las filas y generar la cuadrícula de posiciones `(t, h, w)`, las etiquetas de modalidad por fila y los índices de timestep por fila. La secuencia no lleva relleno: la implementación de referencia la rellena hasta un múltiplo de 64 para FlashAttention y separa la cola con `cu_seqlens = [0, used, S]`, algo que esta portada no necesita, por lo que la atención se ejecuta sin máscara sobre un solo documento y todos los backends de atención permanecen disponibles.

El eje de lote es un eje de replicación pura: los argumentos estructurales (`timestep`, `timestep_indices`, `token_tags`, `position_ids` y los tres tensores de índice) describen una única disposición empaquetada que comparten todos los elementos del lote, y cada elemento es un único documento de atención.

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

[Fuente](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))`) : Filas de latentes de video parcheadas — filas de condicionamiento y filas objetivo — ordenadas según aparecen en la secuencia empaquetada, es decir, coincidiendo con `video_indices`.

audio_hidden_states (`torch.Tensor` de forma `(batch_size, num_audio_tokens, audio_in_channels)`) : Filas latentes de audio, ordenadas para coincidir con `audio_indices`.

encoder_hidden_states (`torch.Tensor` de forma `(batch_size, num_text_tokens, text_dim)`) : Condicionamiento de texto, ordenado para que coincida con `text_indices`.

timestep (`torch.Tensor` de forma `(num_timesteps,)`) : Los valores de *pasos de tiempo* distintos presentes en la secuencia empaquetada, en `[0, 1]` y sin escalar. Una sola pasada hacia adelante sirve filas en diferentes niveles de ruido (video objetivo, audio objetivo, filas de condicionamiento).

timestep_indices (`torch.Tensor` de forma `(seq_len,)`) : Para cada fila de la secuencia empaquetada, el índice de su paso de tiempo en `timestep`.

token_tags (`torch.Tensor` de forma `(seq_len,)`) : Para cada fila de la secuencia empaquetada, su modalidad: `0` video, `1` texto, `2` audio.

position_ids (`torch.Tensor` de forma `(seq_len, 3)`) : Las coordenadas rotatorias `(t, h, w)` de cada fila de la secuencia empaquetada.

video_indices (`torch.Tensor` de forma `(num_video_tokens,)`) : Posiciones de las filas de video en la secuencia empaquetada.

audio_indices (`torch.Tensor` de forma `(num_audio_tokens,)`) : Posiciones de las filas de audio en la secuencia empaquetada.

text_indices (`torch.Tensor` de forma `(num_text_tokens,)`) : Posiciones de las filas de texto en la secuencia empaquetada.

attention_kwargs (`dict`, *opcional*) : Un diccionario de kwargs que, si se especifica, puede contener una entrada `scale` que se aplica a las capas LoRA.

return_dict (`bool`, por defecto `True`) : Si se debe devolver un `MiniMaxH3TransformerOutput` en lugar de una tupla simple.

**Devuelve:** `MiniMaxH3TransformerOutput` o `tuple`

La velocidad del video de forma `(batch_size, num_video_tokens, in_channels * prod(patch_size))` y la velocidad del audio de forma `(batch_size, num_audio_tokens, audio_in_channels)`, en el orden de filas de `video_indices` y `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)
```

[Fuente](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))`) : La predicción de velocidad del video para las filas indicadas por `video_indices`, en el mismo orden. Las filas de condicionamiento se devuelven sin enmascarar; enmascararlas antes del paso del planificador es responsabilidad del llamador.

audio_sample (`torch.Tensor` de forma `(batch_size, num_audio_tokens, audio_in_channels)`, por defecto `None`) : La predicción de velocidad de audio para las filas indicadas por `audio_indices`, en el mismo orden. `forward` siempre lo rellena; solo toma el valor por defecto `None` para que la salida pueda reconstruirse a partir de un diccionario simple de sus campos, que es la forma en que los hooks de offload de accelerate devuelven un `BaseOutput` al dispositivo de entrada.

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