Diffusers documentation
MiniMaxH3Transformer3DModel
MiniMaxH3Transformer3DModel
MiniMax による MiniMax-H3 で紹介された、動画と音声の同時生成を行う Diffusion Transformer モデルです。
MiniMax-H3は、テキストの条件付け、条件付け画像と動画の行、音声の行、およびターゲット動画の行を同時に保持する1つのパックされた1次元シーケンスに対して、単一のブロックスタックを実行します。アテンションはこのシーケンス全体に対するフルセルフアテンションであるため、クロスアテンションやモダリティごとのブロック重みは存在しません。モダリティ固有の挙動は、2つの入力パッチ投影、AdaLNのモジュレーションパラメータを選択する行ごとのモダリティタグ、および2つの出力ヘッドからのみ生じます。
パック済みレイアウトの構築は呼び出し側の責務です。そのため、forward のシグネチャでは、潜在変数とは別にレイアウトを受け取ります。具体的には、(t, h, w) の位置グリッド、行ごとのモダリティタグ、行ごとのタイムステップインデックス、そして動画・音声・テキストの行を参照するための3つのインデックステンソルです。MiniMaxH3Blocks と MiniMaxH3Ref2VABlocks がこれらすべてを構築します。
-1 のタグを持つパディング行を含むレイアウトでは、これらの行がブールマスクによって独自のアテンションドキュメントに保持されるため、マスク付きアテンションバックエンドが必要です。一方、パディングのないシーケンスではマスクが不要であり、すべてのバックエンドが利用可能です。
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"チェックポイントは混合精度です。2 つの入力パッチ投影、タイムステップ MLP、および 2 つの出力ヘッドは float32 であり、ブロックスタックは 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) — 投影されたテキストストリームに適用されるトークンリファイナーブロックの数。 - 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バッファを 1 つ共有し、attention_head_dimチャネルのうち2 * 3 * rope_freq_dim分が回転されます。 - rope_theta (
float、デフォルト値は10000.0) —rope.inv_freqバッファの計算に用いられる、ロータリー周波数スケジュールの基数です。 - norm_eps (
float、デフォルトは1e-5) — アテンション前およびフィードフォワード前の正規化におけるエプシロン。 - qk_norm_eps (
float, デフォルトは1e-5) — ヘッドごとのクエリ/キーノルムのエプシロン。 - final_norm_eps (
float、デフォルトは1e-5) — トークンリファイナー出力のノルムおよびnorm_outのエプシロン。
MiniMax-H3 で紹介された、動画と音声の同時生成を行う Transformer モデルです。
MiniMax-H3 は、テキスト条件、条件付け画像/動画の行、オーディオの行、およびターゲット動画の行を保持する1 つのパックされた 1 次元シーケンスに対して、単一のブロックスタックを実行します。アテンションは、そのシーケンス全体に対する完全な自己アテンションであり、クロスアテンションやモダリティごとのブロック重みは存在しません。モダリティ固有の挙動は、2 つの入力パッチ射影、行ごとの AdaLN モダリティタグ、および 2 つの出力ヘッドからのみ生じます。
呼び出し側がパックされたレイアウトを構築する責任を負います。具体的には、動画の潜在変数をパッチ化し、行の順序を決定し、(t, h, w) の位置グリッド、行ごとのモダリティタグ、および行ごとのタイムステップインデックスを生成します。シーケンスにはパディングが含まれていません。参照実装では FlashAttention 向けに 64 の倍数までパディングし、cu_seqlens = [0, used, S] を用いて末尾を切り離していましたが、この移植版ではそれを使用しません。そのため、アテンションは 1 つのドキュメントに対してマスクなしで実行され、すべてのアテンションバックエンドが利用可能になります。
バッチ軸は純粋なレプリケーション軸です。構造引数（timestep、timestep_indices、token_tags、position_ids および 3 つのインデックステンソル）は、すべてのバッチ項目が共有する 1 つのパック済みレイアウトを記述し、各項目は単一のアテンション文書です。
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 (
torch.Tensor、shape(batch_size, num_video_tokens, in_channels * prod(patch_size))) — パッチ化された動画の潜在行列 — 条件行とターゲット行 — packed シーケンスに現れる順序で並べられており、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、shape(num_timesteps,)) — パックされたシーケンスに存在する個別のタイムステップ値です。[0, 1]の範囲で、スケーリングされていません。1回のフォワードで、異なるノイズレベルの行（ターゲット動画、ターゲット音声、条件付け行）を処理します。 - timestep_indices (
torch.Tensor、shape(seq_len,)) — パックされたシーケンスの各行について、timestepにおけるそのタイムステップのインデックスです。 - token_tags (
torch.Tensor、shape(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、shape(num_audio_tokens,)) — パックされたシーケンスにおけるオーディオ行の位置です。 - text_indices (
torch.Tensor、形状(num_text_tokens,)) — パックされたシーケンス内のテキスト行の位置です。 - attention_kwargs (
dict、省略可) — 指定された場合、LoRA レイヤーに適用されるscaleエントリを含むことができる kwargs 辞書です。 - return_dict (
bool、デフォルトはTrue) —MiniMaxH3TransformerOutputを返すか、通常のタプルを返すかを指定します。
戻り値
MiniMaxH3TransformerOutput または tuple
video_indices および audio_indices の行順に従う、形状 (batch_size, num_video_tokens, in_channels * prod(patch_size)) の動画の速度と、形状 (batch_size, num_audio_tokens, audio_in_channels) の音声の速度です。
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、shape(batch_size, num_audio_tokens, audio_in_channels)、デフォルトはNone) —audio_indicesで指定された行のオーディオ速度予測で、同じ順序です。forwardは常にこれを設定します。デフォルトがNoneであるのは、そのフィールドの通常の dict から出力を再構築できるようにするためです。accelerate のオフロードフックがBaseOutputを入力デバイスに戻す際にこの方法が使われます。