# MiniMaxH3Transformer3DModel

Model Diffusion Transformer untuk generasi video dan audio secara bersama-sama, diperkenalkan dalam [MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3) oleh MiniMax.

MiniMax-H3 menjalankan satu tumpukan blok di atas **satu urutan 1-D yang dikemas** yang sekaligus menyimpan kondisi teks, baris gambar dan video kondisi, baris audio, serta baris video target. Atensinya adalah self-attention penuh di atas urutan tersebut, sehingga tidak ada cross-attention dan tidak ada bobot blok per-modalitas. Perilaku spesifik modalitas hanya berasal dari dua proyeksi patch input, tag modalitas per-baris yang memilih parameter modulasi AdaLN, dan dua kepala output.

Membangun layout yang dikemas adalah tugas pemanggil, itulah mengapa tanda tangan forward mengambil layout terpisah dari latents: grid posisi `(t, h, w)`, tag modalitas per baris, indeks timestep per baris, dan tiga tensor indeks yang mengalamatkan baris video, audio, dan teks. [MiniMaxH3Blocks](/docs/diffusers/main/id/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks) dan `MiniMaxH3Ref2VABlocks` membangun semuanya.

Layout yang membawa baris padding (tag `-1`) memerlukan backend perhatian yang dimasker, karena baris-baris tersebut dipertahankan dalam dokumen perhatian mereka sendiri oleh mask boolean; urutan tanpa padding tidak memerlukan mask dan tetap mempertahankan semua backend yang tersedia.

Satu repositori menyimpan partisi checkpoint yang telah dirilis, sehingga subfolder yang menentukan tugas: `transformer/` untuk tugas teks dan keyframe, `transformer_ref/` untuk tugas 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"
```

Checkpoint menggunakan presisi campuran: dua proyeksi patch input, MLP timestep, dan dua kepala output adalah float32, sedangkan tumpukan blok adalah bfloat16. `from_pretrained` mempertahankan tata letak tersebut melalui `_keep_in_fp32_modules`, jadi berikan `dtype=torch.bfloat16` dan biarkan modul float32 ditempatkan, alih-alih meng-cast model dengan `.to(torch.bfloat16)` setelahnya.

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

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

**Parameter:**

num_attention_heads (`int`, defaultnya `56`) : Jumlah kepala yang digunakan untuk multi-head attention.

attention_head_dim (`int`, defaultnya `128`) : Jumlah channel di setiap kepala perhatian. Perhatikan bahwa `num_attention_heads * attention_head_dim` *lebih besar* daripada `hidden_size` di MiniMax-H3.

hidden_size (`int`, defaultnya `5376`) : Jumlah saluran dari urutan yang dikemas (aliran residual).

num_layers (`int`, defaultnya `50`) : Jumlah blok transformer.

num_refiner_layers (`int`, defaultnya `2`) : Jumlah blok penyempurna token yang diterapkan pada aliran teks yang diproyeksikan.

ffn_dim (`int`, defaultnya `14336`) : Dimensi dalam dari lapisan feed-forward SwiGLU.

in_channels (`int`, defaultnya `24`) : Jumlah channel dari latens video.

audio_in_channels (`int`, defaultnya `32`) : Jumlah channel dari latens audio.

patch_size (`tuple[int, int, int]`, defaultnya `(1, 2, 2)`) : patch `(t, h, w)` yang digunakan untuk mengemas latens video ke dalam baris.

text_dim (`int`, defaultnya `5120`) : Jumlah channel dari kondisi teks yang dihasilkan oleh text encoder.

freq_dim (`int`, defaultnya `256`) : Dimensi dari sinusoidal timestep embedding. Timesteps dikonsumsi tanpa penskalaan dalam `[0, 1]`.

time_embed_hidden_dim (`int`, defaultnya `5376`) : Dimensi dalam dari MLP timestep.

time_embed_dim (`int`, defaultnya `2688`) : Dimensi output dari MLP timestep, yaitu input dari setiap proyeksi AdaLN.

rope_freq_dim (`int`, defaultnya `16`) : Jumlah frekuensi rotasi per sumbu. Sumbu `(t, h, w)` berbagi satu buffer `inv_freq` dengan panjang ini dan `2 * 3 * rope_freq_dim` dari kanal `attention_head_dim` dirotasikan.

rope_theta (`float`, defaultnya `10000.0`) : Basis dari jadwal frekuensi rotasi yang digunakan untuk menghitung buffer `rope.inv_freq`.

norm_eps (`float`, defaultnya `1e-5`) : Epsilon dari norm pra-attention dan pra-feed-forward.

qk_norm_eps (`float`, defaultnya `1e-5`) : Epsilon dari norma query/key per-head.

final_norm_eps (`float`, defaultnya `1e-5`) : Epsilon dari output norm token refiner dan dari `norm_out`.

Model Transformer untuk generasi video + audio secara bersama-sama, diperkenalkan dalam MiniMax-H3.

MiniMax-H3 menjalankan satu tumpukan blok di atas **satu urutan 1-D yang dikemas** yang berisi kondisi teks, baris gambar/video pengkondisian, baris audio, dan baris video target. Atensinya adalah self-attention penuh di atas urutan tersebut; tidak ada cross-attention dan tidak ada bobot blok per-modalitas. Perilaku spesifik modalitas hanya berasal dari dua proyeksi patch input, tag modalitas AdaLN per-baris, dan dua kepala output.

Pemanggil bertanggung jawab untuk membangun tata letak yang dikemas: melakukan patchifikasi pada latens video, mengurutkan baris, dan menghasilkan grid posisi `(t, h, w)`, tag modalitas per baris, dan indeks timestep per baris. Urutan tidak membawa padding — implementasi referensi melakukan padding hingga kelipatan 64 untuk FlashAttention dan memisahkan ekor dengan `cu_seqlens = [0, used, S]`, yang tidak diperlukan oleh port ini — sehingga perhatian berjalan tanpa masker di atas satu dokumen dan semua backend perhatian tetap tersedia.

Sumbu batch adalah sumbu replikasi murni: argumen struktural (`timestep`, `timestep_indices`, `token_tags`, `position_ids` dan tiga tensor indeks) menggambarkan satu tata letak terpadu yang dibagikan oleh setiap item batch, dan setiap item adalah satu dokumen perhatian.

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

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

**Parameter:**

hidden_states (`torch.Tensor` dengan bentuk `(batch_size, num_video_tokens, in_channels * prod(patch_size))`) : Baris latensi video yang telah di-patch — baris kondisioning dan baris target — yang diurutkan sesuai kemunculannya dalam urutan yang dikemas, yaitu sesuai dengan `video_indices`.

audio_hidden_states (`torch.Tensor` dengan bentuk `(batch_size, num_audio_tokens, audio_in_channels)`) : Baris laten audio, diurutkan agar sesuai dengan `audio_indices`.

encoder_hidden_states (`torch.Tensor` dengan bentuk `(batch_size, num_text_tokens, text_dim)`) : Kondisioning teks, diurutkan agar sesuai dengan `text_indices`.

timestep (`torch.Tensor` dengan bentuk `(num_timesteps,)`) : Nilai *distinct* timestep yang ada dalam urutan yang dikemas, dalam `[0, 1]` dan tidak diskalakan. Satu forward melayani baris pada tingkat noise yang berbeda (video target, audio target, baris kondisioning).

timestep_indices (`torch.Tensor` dengan bentuk `(seq_len,)`) : Untuk setiap baris dari urutan yang dikemas, indeks timestep-nya dalam `timestep`.

token_tags (`torch.Tensor` dengan bentuk `(seq_len,)`) : Untuk setiap baris dari urutan yang dikemas, modalitasnya: `0` video, `1` teks, `2` audio.

position_ids (`torch.Tensor` dengan bentuk `(seq_len, 3)`) : Koordinat rotasi `(t, h, w)` untuk setiap baris dari urutan yang dikemas.

video_indices (`torch.Tensor` dengan bentuk `(num_video_tokens,)`) : Posisi baris video dalam urutan yang dikemas.

audio_indices (`torch.Tensor` dengan bentuk `(num_audio_tokens,)`) : Posisi baris audio dalam urutan yang dikemas.

text_indices (`torch.Tensor` dengan bentuk `(num_text_tokens,)`) : Posisi baris teks dalam urutan yang dikemas.

attention_kwargs (`dict`, *opsional*) : Kamus kwargs yang, jika ditentukan, dapat membawa entri `scale` yang diterapkan ke lapisan LoRA.

return_dict (`bool`, defaultnya `True`) : Apakah akan mengembalikan `MiniMaxH3TransformerOutput` alih-alih tuple biasa.

**Mengembalikan:** `MiniMaxH3TransformerOutput` atau `tuple`

Kecepatan video dengan bentuk `(batch_size, num_video_tokens, in_channels * prod(patch_size))` dan kecepatan audio dengan bentuk `(batch_size, num_audio_tokens, audio_in_channels)`, sesuai urutan baris dari `video_indices` dan `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)
```

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

**Parameter:**

sample (`torch.Tensor` dengan bentuk `(batch_size, num_video_tokens, in_channels * prod(patch_size))`) : Prediksi kecepatan video untuk baris yang ditunjuk oleh `video_indices`, dalam urutan yang sama. Baris kondisioning dikembalikan tanpa masker — tugas pemanggil untuk memaskerinya sebelum langkah scheduler.

audio_sample (`torch.Tensor` dengan bentuk `(batch_size, num_audio_tokens, audio_in_channels)`, defaultnya `None`) : Prediksi kecepatan audio untuk baris yang ditunjuk oleh `audio_indices`, dalam urutan yang sama. `forward` selalu mengisinya; nilainya hanya default ke `None` agar output dapat dibangun kembali dari dict biasa dari field-fieldnya, yang merupakan cara hook offload accelerate memindahkan `BaseOutput` kembali ke perangkat input.

Output dari [MiniMaxH3Transformer3DModel](/docs/diffusers/main/id/api/models/minimax_h3_transformer3d#diffusers.MiniMaxH3Transformer3DModel).