Diffusers documentation
MiniMaxH3Transformer3DModel
MiniMaxH3Transformer3DModel
一种用于联合生成视频和音频的 Diffusion Transformer 模型，由 MiniMax 在 MiniMax-H3 中提出。
MiniMax-H3 在一个单一的块堆栈上运行，该堆栈处理一个打包的一维序列，该序列同时包含文本条件、条件图像和视频行、音频行以及目标视频行。注意力机制是对该序列的完整自注意力，因此不存在交叉注意力，也不存在按模态划分的块权重。模态特定的行为仅来自两个输入补丁投影、用于选择 AdaLN 调制参数的逐行模态标签，以及两个输出头。
构建打包布局是调用方的职责，因此 forward 签名将布局与潜变量分开接收：即 (t, h, w) 位置网格、每行的模态标签、每行的时间步索引，以及用于寻址视频、音频和文本行的三个索引张量。MiniMaxH3Blocks 和 MiniMaxH3Ref2VABlocks 会构建所有这些内容。
带有填充行（标签为 -1）的布局需要支持掩码的注意力后端，因为这些行通过布尔掩码保留在各自的注意力文档中；无填充的序列不需要掩码，因此所有后端均可用。
同一个仓库同时存放了已发布的检查点分区，因此子文件夹用于选择任务：transformer/ 用于文本和关键帧任务，transformer_ref/ 用于全参考任务。
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
class diffusers.MiniMaxH3Transformer3DModel
< source >( num_attention_heads: int = 56attention_head_dim: int = 128hidden_size: int = 5376num_layers: int = 50num_refiner_layers: int = 2ffn_dim: int = 14336in_channels: int = 24audio_in_channels: int = 32patch_size: tuple = (1, 2, 2)text_dim: int = 5120freq_dim: int = 256time_embed_hidden_dim: int = 5376time_embed_dim: int = 2688rope_freq_dim: int = 16rope_theta: float = 10000.0norm_eps: float = 1e-05qk_norm_eps: float = 1e-05final_norm_eps: float = 1e-05 )
参数
- 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 refiner 块的数量。 - 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) — 每个头 query/key 范数的 epsilon。 - final_norm_eps (
float，默认为1e-5) — token refiner 输出归一化以及norm_out的 epsilon。
一种用于联合视频 + 音频生成的 Transformer 模型，在 MiniMax-H3 中引入。
MiniMax-H3 runs a single stack of blocks over one packed 1-D sequence that holds the text condition, the conditioning image / video rows, the audio rows and the target video rows. Attention is full self-attention over that sequence; there is no cross-attention and no per-modality block weights. Modality-specific behaviour comes only from the two input patch projections, the per-row AdaLN modality tag, and the two output heads.
调用方负责构建打包布局：对视频潜变量进行分块（patchify）、对行进行排序，并生成 (t, h, w) 位置网格、每行的模态标签以及每行的时间步索引。序列不包含填充——参考实现会将其填充为 64 的倍数以适配 FlashAttention，并通过 cu_seqlens = [0, used, S] 切分出尾部，而此移植版本无需此操作——因此注意力在单个文档上无掩码运行，所有注意力后端均可用。
批次维度是一个纯粹的复制维度：结构参数（timestep、timestep_indices、token_tags、position_ids 以及三个索引张量）描述了一种所有批次项共享的打包布局，且每个项都是单个注意力文档。
forward
< source >( hidden_states: Tensoraudio_hidden_states: Tensorencoder_hidden_states: Tensortimestep: Tensortimestep_indices: Tensortoken_tags: Tensorposition_ids: Tensorvideo_indices: Tensoraudio_indices: Tensortext_indices: Tensorattention_kwargs: dict[str, typing.Any] | None = Nonereturn_dict: bool = True ) → MiniMaxH3TransformerOutput or tuple
参数
- hidden_states（形状为
(batch_size, num_video_tokens, in_channels * prod(patch_size))的torch.Tensor）— 经过分块处理的视频潜在行——包括条件行和目标行——按照其在打包序列中出现的顺序排列，即与video_indices相匹配。 - audio_hidden_states（形状为
(batch_size, num_audio_tokens, audio_in_channels)的torch.Tensor）— 音频潜在行，其顺序与audio_indices相匹配。 - encoder_hidden_states（形状为
(batch_size, num_text_tokens, text_dim)的torch.Tensor）— 文本条件，其顺序与text_indices相匹配。 - timestep（形状为
(num_timesteps,)的torch.Tensor）— 打包序列中存在的不同时间步值，取值范围为[0, 1]且未进行缩放。一次前向传播处理处于不同噪声水平的行（目标视频、目标音频、条件行）。 - timestep_indices（形状为
(seq_len,)的torch.Tensor）— 对于打包序列的每一行，其在timestep中对应的时间步索引。 - token_tags（形状为
(seq_len,)的torch.Tensor）— 对于打包序列的每一行，其模态：0视频，1文本，2音频。 - position_ids（形状为
(seq_len, 3)的torch.Tensor）— 打包序列中每一行的(t, h, w)旋转坐标。 - video_indices（形状为
(num_video_tokens,)的torch.Tensor）— 视频行在打包序列中的位置。 - audio_indices（形状为
(num_audio_tokens,)的torch.Tensor）— 音频行在打包序列中的位置。 - text_indices（形状为
(num_text_tokens,)的torch.Tensor）— 文本行在打包序列中的位置。 - 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
class diffusers.models.transformers.transformer_minimax_h3.MiniMaxH3TransformerOutput
< source >( sample: Tensoraudio_sample: typing.Optional[torch.Tensor] = None )
参数
- 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移回输入设备的方式。