# MiniMaxH3Transformer3DModel

一种用于联合生成视频和音频的 Diffusion Transformer 模型，由 MiniMax 在 [MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3) 中提出。

MiniMax-H3 在一个单一的块堆栈上运行，该堆栈处理**一个打包的一维序列**，该序列同时包含文本条件、条件图像和视频行、音频行以及目标视频行。注意力机制是对该序列的完整自注意力，因此不存在交叉注意力，也不存在按模态划分的块权重。模态特定的行为仅来自两个输入补丁投影、用于选择 AdaLN 调制参数的逐行模态标签，以及两个输出头。

构建打包布局是调用方的职责，因此 forward 的签名将布局与潜变量分开：即 `(t, h, w)` 位置网格、每行的模态标签、每行的时间步索引，以及用于寻址视频、音频和文本行的三个索引张量。[MiniMaxH3Blocks](/docs/diffusers/main/zh/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks) 和 `MiniMaxH3Ref2VABlocks` 会构建所有这些内容。

带有填充行（标签为 `-1`）的布局需要支持掩码的注意力后端，因为这些行通过布尔掩码保留在各自的注意力文档中；无填充的序列不需要掩码，因此所有后端均可用。

同一个仓库同时存放了已发布的检查点分区，因此子文件夹用于选择任务：`transformer/` 用于文本和关键帧任务，`transformer_ref/` 用于全参考任务。

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

该检查点采用混合精度：两个输入 patch 投影、时间步 MLP 以及两个输出头为 float32，而 block 堆栈为 bfloat16。`from_pretrained` 通过 `_keep_in_fp32_modules` 保持该布局，因此请传入 `dtype=torch.bfloat16`，并让该函数自行放置 float32 模块，而不是在之后使用 `.to(torch.bfloat16)` 对整个模型进行转换。

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

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

**参数：**

num_attention_heads (`int`，默认为 `56`)：用于多头注意力的注意力头数量。

attention_head_dim (`int`，默认为 `128`)：每个注意力头中的通道数。请注意，在 MiniMax-H3 中，`num_attention_heads * attention_head_dim` 的值*大于*`hidden_size`。

hidden_size (`int`，默认为 `5376`)：打包序列（残差流）的通道数。

num_layers (`int`，默认为 `50`)：Transformer 块的数量。

num_refiner_layers (`int`，默认为 `2`)：应用于投影文本流的 token 细化块数量。

ffn_dim (`int`，默认为 `14336`)：SwiGLU 前馈层的内部维度。

in_channels (`int`，默认为 `24`)：视频潜变量的通道数。

audio_in_channels (`int`，默认为 `32`)：音频潜变量的通道数。

patch_size (`tuple[int, int, int]`，默认为 `(1, 2, 2)`)：用于将视频潜变量打包成行的 `(t, h, w)` 补丁。

text_dim (`int`，默认为 `5120`)：文本编码器生成的文本条件信号的通道数。

freq_dim (`int`，默认为 `256`)：正弦时间步嵌入的维度。时间步在 `[0, 1]` 范围内未经缩放使用。

time_embed_hidden_dim (`int`，默认为 `5376`)：时间步 MLP 的内部维度。

time_embed_dim (`int`，默认为 `2688`)：时间步 MLP 的输出维度，即每个 AdaLN 投影的输入。

rope_freq_dim (`int`，默认为 `16`)：每个轴上的旋转频率数量。`(t, h, w)` 轴共享一个长度为该值的 `inv_freq` 缓冲区，并且 `attention_head_dim` 通道中的 `2 * 3 * rope_freq_dim` 个通道会被旋转。

rope_theta (`float`，默认为 `10000.0`) : 用于计算 `rope.inv_freq` 缓冲区的旋转频率调度的底数。

norm_eps (`float`，默认为 `1e-5`)：注意力前和前馈前归一化的 Epsilon。

qk_norm_eps (`float`，默认为 `1e-5`)：每个头查询/键范数的 Epsilon。

final_norm_eps (`float`，默认为 `1e-5`)：token refiner 输出归一化以及 `norm_out` 的 epsilon。

一种用于联合视频 + 音频生成的 Transformer 模型，在 MiniMax-H3 中引入。

MiniMax-H3 在一个包含文本条件、条件图像/视频行、音频行和目标视频行的**单个打包一维序列**上运行单一的块堆栈。注意力机制是该序列上的完整自注意力；没有交叉注意力，也没有按模态区分的块权重。模态特定的行为仅来自两个输入补丁投影、每行的 AdaLN 模态标签以及两个输出头。

调用方负责构建打包布局：对视频潜变量进行分块（patchify）、对行进行排序，并生成 `(t, h, w)` 位置网格、每行的模态标签以及每行的时间步索引。序列不包含填充——参考实现会将其填充至 64 的倍数以适配 FlashAttention，并通过 `cu_seqlens = [0, used, S]` 切分出尾部，而本移植版本无需此操作——因此注意力在单个文档上无掩码运行，所有注意力后端均可用。

批次维度是一个纯粹的复制维度：结构参数（`timestep`、`timestep_indices`、`token_tags`、`position_ids` 以及三个索引张量）描述了一种所有批次项共享的打包布局，且每个项都是单个注意力文档。

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

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

**参数：**

hidden_states (`torch.Tensor`，形状为 `(batch_size, num_video_tokens, in_channels * prod(patch_size))`)：经过分块处理的视频潜在行——包括条件行和目标行——按照其在打包序列中出现的顺序排列，即与 `video_indices` 相匹配。

audio_hidden_states (`torch.Tensor`，形状为 `(batch_size, num_audio_tokens, audio_in_channels)`)：音频潜在行，其顺序与 `audio_indices` 相匹配。

encoder_hidden_states (`torch.Tensor`，形状为 `(batch_size, num_text_tokens, text_dim)`)：文本条件，其顺序与 `text_indices` 相匹配。

timestep (`torch.Tensor`，形状为 `(num_timesteps,)`)：打包序列中存在的*不同*时间步值，取值范围为 `[0, 1]` 且未缩放。一次前向传播处理处于不同噪声水平的行（目标视频、目标音频、条件行）。

timestep_indices (`torch.Tensor`，形状为 `(seq_len,)`)：对于打包序列的每一行，其在 `timestep` 中对应的时间步索引。

token_tags (`torch.Tensor`，形状为 `(seq_len,)`)：对于打包序列的每一行，其模态：`0` 视频，`1` 文本，`2` 音频。

position_ids (`torch.Tensor`，形状为 `(seq_len, 3)`)：打包序列中每一行的 `(t, h, w)` 旋转坐标。

video_indices (`torch.Tensor`，形状为 `(num_video_tokens,)`)：视频行在打包序列中的位置。

audio_indices (`torch.Tensor`，形状为 `(num_audio_tokens,)`)：音频行在打包序列中的位置。

text_indices (`torch.Tensor`，形状为 `(num_text_tokens,)`)：打包序列中文本行的位置。

attention_kwargs (`dict`, *可选*) : 一个 kwargs 字典，如果指定，可能包含一个 `scale` 条目，该条目将应用于 LoRA 层。

return_dict (`bool`，默认为 `True`)：是否返回 `MiniMaxH3TransformerOutput` 而不是普通元组。

**返回：** `MiniMaxH3TransformerOutput` 或 `tuple`

形状为 `(batch_size, num_video_tokens, in_channels * prod(patch_size))` 的视频速度，以及形状为 `(batch_size, num_audio_tokens, audio_in_channels)` 的音频速度，其行顺序遵循 `video_indices` 和 `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)
```

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

**参数：**

sample (`torch.Tensor`，形状为 `(batch_size, num_video_tokens, in_channels * prod(patch_size))`)：由 `video_indices` 所指定行的视频速度预测，顺序相同。条件行以未掩码的形式返回——在调度器步骤之前将其掩码掉是调用方的职责。

audio_sample (`torch.Tensor`，形状为 `(batch_size, num_audio_tokens, audio_in_channels)`，默认值为 `None`)：由 `audio_indices` 所指定行的音频速度预测值，顺序相同。`forward` 始终会填充该值；其默认值仅为 `None`，以便能够根据其字段的普通字典重建输出，这正是 accelerate offload hooks 将 `BaseOutput` 移回输入设备的方式。

[MiniMaxH3Transformer3DModel](/docs/diffusers/main/zh/api/models/minimax_h3_transformer3d#diffusers.MiniMaxH3Transformer3DModel) 的输出。