# MiniMaxH3Transformer3DModel

Một mô hình Diffusion Transformer cho việc tạo video và âm thanh đồng thời, được giới thiệu trong [MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3) bởi MiniMax.

MiniMax-H3 chạy một chồng khối duy nhất trên **một chuỗi 1-D đóng gói** chứa đồng thời điều kiện văn bản, hàng ảnh và hàng video điều kiện, hàng âm thanh và hàng video đích. Attention là self-attention đầy đủ trên chuỗi đó, do đó không có cross-attention và không có trọng số khối riêng cho từng phương thức. Hành vi đặc thù theo phương thức chỉ đến từ hai phép chiếu patch đầu vào, thẻ phương thức theo hàng chọn các tham số điều biến AdaLN, và hai đầu ra.

Việc xây dựng bố cục đóng gói là trách nhiệm của bên gọi, đó là lý do tại sao chữ ký forward tách riêng bố cục khỏi các biến tiềm ẩn: lưới vị trí `(t, h, w)`, các thẻ phương thức cho từng hàng, các chỉ số bước thời gian cho từng hàng và ba tensor chỉ số để truy cập các hàng video, âm thanh và văn bản. [MiniMaxH3Blocks](/docs/diffusers/main/vi/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks) và `MiniMaxH3Ref2VABlocks` xây dựng tất cả những điều này.

Một layout chứa các hàng padding (tag `-1`) cần một backend attention có mask, vì các hàng đó được giữ trong tài liệu attention riêng của chúng bằng một mask boolean; một chuỗi không có padding thì không cần mask và giữ mọi backend khả dụng.

Một kho chứa cả các phân vùng checkpoint đã phát hành, do đó thư mục con là thứ xác định tác vụ: `transformer/` cho các tác vụ văn bản và keyframe, `transformer_ref/` cho tác vụ 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 có độ chính xác hỗn hợp: hai phép chiếu patch đầu vào, MLP bước thời gian và hai đầu ra là float32 trong khi chồng khối là bfloat16. `from_pretrained` giữ nguyên bố cục đó thông qua `_keep_in_fp32_modules`, vì vậy hãy truyền `dtype=torch.bfloat16` và để nó đặt các module float32 thay vì ép kiểu mô hình bằng `.to(torch.bfloat16)` sau đó.

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

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

**Tham số:**

num_attention_heads (`int`, mặc định là `56`) : Số lượng đầu (heads) được sử dụng cho chú ý đa đầu (multi-head attention).

attention_head_dim (`int`, mặc định là `128`) : Số lượng kênh trong mỗi đầu chú ý. Lưu ý rằng `num_attention_heads * attention_head_dim` *lớn hơn* `hidden_size` trong MiniMax-H3.

hidden_size (`int`, mặc định là `5376`) : Số kênh của chuỗi được đóng gói (dòng dư).

num_layers (`int`, mặc định là `50`) : Số lượng khối transformer.

num_refiner_layers (`int`, mặc định là `2`) : Số lượng khối token refiner được áp dụng cho luồng văn bản đã được chiếu (projected).

ffn_dim (`int`, mặc định là `14336`) : Kích thước chiều trong của các lớp feed-forward SwiGLU.

in_channels (`int`, mặc định là `24`) : Số kênh của các latents video.

audio_in_channels (`int`, mặc định là `32`) : Số kênh của các audio latents.

patch_size (`tuple[int, int, int]`, mặc định là `(1, 2, 2)`) : Patch `(t, h, w)` được dùng để đóng gói các video latents thành các hàng.

text_dim (`int`, mặc định là `5120`) : Số lượng kênh của điều kiện văn bản do text encoder tạo ra.

freq_dim (`int`, mặc định là `256`) : Kích thước của embedding bước thời gian hình sin. Các bước thời gian được sử dụng không có hệ số trong `[0, 1]`.

time_embed_hidden_dim (`int`, mặc định là `5376`) : Kích thước chiều trong của MLP bước thời gian.

time_embed_dim (`int`, mặc định là `2688`) : Kích thước chiều đầu ra của MLP thời gian, tức là đầu vào của mọi phép chiếu AdaLN.

rope_freq_dim (`int`, mặc định là `16`) : Số lượng tần số quay trên mỗi trục. Các trục `(t, h, w)` dùng chung một bộ đệm `inv_freq` có độ dài này và `2 * 3 * rope_freq_dim` trong số các kênh `attention_head_dim` sẽ được xoay.

rope_theta (`float`, mặc định là `10000.0`) : Cơ số của lịch tần số quay mà buffer `rope.inv_freq` được tính từ đó.

norm_eps (`float`, mặc định là `1e-5`) : Epsilon của các chuẩn (norms) trước chú ý (pre-attention) và trước mạng tiền tiến (pre-feed-forward).

qk_norm_eps (`float`, mặc định là `1e-5`) : Epsilon của các chuẩn query/key cho từng head.

final_norm_eps (`float`, mặc định là `1e-5`) : Epsilon của output norm của token refiner và của `norm_out`.

Một mô hình Transformer cho việc tạo video + âm thanh đồng thời, được giới thiệu trong MiniMax-H3.

MiniMax-H3 chạy một chồng khối duy nhất trên **một chuỗi 1-D đóng gói** chứa điều kiện văn bản, các hàng ảnh / video điều kiện, các hàng âm thanh và các hàng video đích. Attention là self-attention đầy đủ trên chuỗi đó; không có cross-attention và không có trọng số khối riêng cho từng phương thức. Hành vi đặc thù theo phương thức chỉ đến từ hai phép chiếu patch đầu vào, thẻ phương thức AdaLN cho từng hàng và hai đầu ra.

Người gọi chịu trách nhiệm xây dựng bố cục đã đóng gói: patchify các latent của video, sắp xếp các hàng và tạo lưới vị trí `(t, h, w)`, các thẻ modality cho từng hàng và các chỉ số timestep cho từng hàng. Chuỗi không chứa padding — bản tham chiếu sẽ pad nó thành bội số của 64 cho FlashAttention và tách phần đuôi bằng `cu_seqlens = [0, used, S]`, điều mà bản port này không cần — do đó attention chạy không có mask trên một tài liệu duy nhất và mọi backend attention đều khả dụng.

Trục batch là một trục nhân bản thuần túy: các đối số cấu trúc (`timestep`, `timestep_indices`, `token_tags`, `position_ids` và ba tensor chỉ số) mô tả một bố cục đóng gói duy nhất mà mọi phần tử trong batch cùng chia sẻ, và mỗi phần tử là một tài liệu chú ý đơn lẻ.

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

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

**Tham số:**

hidden_states (`torch.Tensor` có shape `(batch_size, num_video_tokens, in_channels * prod(patch_size))`) : Các hàng latent của video đã được patchify — gồm các hàng điều kiện và các hàng đích — được sắp xếp theo thứ tự xuất hiện trong chuỗi đã đóng gói, tức là khớp với `video_indices`.

audio_hidden_states (`torch.Tensor` có hình dạng `(batch_size, num_audio_tokens, audio_in_channels)`) : Các hàng latent của âm thanh, được sắp xếp để khớp với `audio_indices`.

encoder_hidden_states (`torch.Tensor` có hình dạng `(batch_size, num_text_tokens, text_dim)`) : Điều kiện văn bản, được sắp xếp để khớp với `text_indices`.

timestep (`torch.Tensor` có shape `(num_timesteps,)`) : Các giá trị *khác nhau* của timestep có mặt trong chuỗi đã đóng gói, nằm trong khoảng `[0, 1]` và chưa được nhân hệ số. Một bước forward phục vụ các hàng ở các mức nhiễu khác nhau (video đích, audio đích, các hàng điều kiện).

timestep_indices (`torch.Tensor` có hình dạng `(seq_len,)`) : Với mỗi hàng của chuỗi đã đóng gói, chỉ số của bước thời gian của nó trong `timestep`.

token_tags (`torch.Tensor` có hình dạng `(seq_len,)`) : Với mỗi hàng của chuỗi được đóng gói, chế độ của nó: `0` video, `1` văn bản, `2` âm thanh.

position_ids (`torch.Tensor` có shape `(seq_len, 3)`) : Các tọa độ rotary `(t, h, w)` của mọi hàng trong chuỗi đã đóng gói.

video_indices (`torch.Tensor` có hình dạng `(num_video_tokens,)`) : Vị trí của các hàng video trong chuỗi đã đóng gói.

audio_indices (`torch.Tensor` có hình dạng `(num_audio_tokens,)`) : Vị trí của các hàng âm thanh trong chuỗi đã đóng gói.

text_indices (`torch.Tensor` có hình dạng `(num_text_tokens,)`) : Vị trí của các dòng văn bản trong chuỗi đã đóng gói.

attention_kwargs (`dict`, *tùy chọn*) : Một từ điển kwargs mà, nếu được chỉ định, có thể chứa mục `scale` được áp dụng cho các lớp LoRA.

return_dict (`bool`, mặc định là `True`) : Xác định có trả về một `MiniMaxH3TransformerOutput` thay vì một tuple thông thường hay không.

**Trả về:** `MiniMaxH3TransformerOutput` hoặc `tuple`

Tốc độ video có hình dạng `(batch_size, num_video_tokens, in_channels * prod(patch_size))` và tốc độ âm thanh có hình dạng `(batch_size, num_audio_tokens, audio_in_channels)`, theo thứ tự hàng của `video_indices` và `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)
```

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

**Tham số:**

sample (`torch.Tensor` có shape `(batch_size, num_video_tokens, in_channels * prod(patch_size))`) : Dự đoán vận tốc video cho các hàng được chỉ định bởi `video_indices`, theo cùng thứ tự. Các hàng điều kiện được trả về ở trạng thái chưa bị che — việc che chúng trước bước scheduler là trách nhiệm của người gọi.

audio_sample (`torch.Tensor` có shape `(batch_size, num_audio_tokens, audio_in_channels)`, mặc định là `None`) : Dự đoán vận tốc âm thanh cho các hàng được chỉ định bởi `audio_indices`, theo cùng thứ tự. `forward` luôn gán giá trị cho trường này; nó chỉ mặc định là `None` để đầu ra có thể được xây dựng lại từ một dict thông thường chứa các trường của nó, đây là cách các accelerate offload hooks đưa một `BaseOutput` trở lại thiết bị đầu vào.

Đầu ra của [MiniMaxH3Transformer3DModel](/docs/diffusers/main/vi/api/models/minimax_h3_transformer3d#diffusers.MiniMaxH3Transformer3DModel).