# MiniMaxH3Transformer3DModel

MiniMax による [MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3) で紹介された、動画と音声の同時生成を行う Diffusion Transformer モデルです。

MiniMax-H3は、テキストの条件付け、条件付け画像と動画の行、音声の行、およびターゲット動画の行を同時に保持する**1つのパックされた1次元シーケンス**に対して、単一のブロックスタックを実行します。アテンションはこのシーケンス全体に対するフルセルフアテンションであるため、クロスアテンションやモダリティごとのブロック重みは存在しません。モダリティ固有の挙動は、2つの入力パッチ投影、AdaLNのモジュレーションパラメータを選択する行ごとのモダリティタグ、および2つの出力ヘッドからのみ生じます。

パック済みレイアウトの構築は呼び出し側の責務です。そのため、forward のシグネチャでは、潜在変数とは別にレイアウトを受け取ります。具体的には、`(t, h, w)` の位置グリッド、行ごとのモダリティタグ、行ごとのタイムステップインデックス、そして動画・音声・テキストの行を参照するための3つのインデックステンソルです。[MiniMaxH3Blocks](/docs/diffusers/main/ja/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks) と `MiniMaxH3Ref2VABlocks` がこれらすべてを構築します。

`-1` のタグを持つパディング行を含むレイアウトでは、これらの行がブールマスクによって独自のアテンションドキュメントに保持されるため、マスク付きアテンションバックエンドが必要です。一方、パディングのないシーケンスではマスクが不要であり、すべてのバックエンドが利用可能です。

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

チェックポイントは混合精度です。2 つの入力パッチ投影、タイムステップ MLP、および 2 つの出力ヘッドは float32 であり、ブロックスタックは 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`) : 投影されたテキストストリームに適用されるトークンリファイナーブロックの数。

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`) : timestep MLPの内部次元です。

time_embed_dim (`int`、デフォルトは `2688`) : timestep 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`) : token refiner の出力ノルムおよび `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[[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`、shape は `(batch_size, num_video_tokens, in_channels * prod(patch_size))`) : パッチ化された動画潜在行列 — 条件付け行とターゲット行 — パックされたシーケンスに現れる順序で並べられており、`video_indices` と一致します。

audio_hidden_states (`torch.Tensor`、shape `(batch_size, num_audio_tokens, audio_in_channels)`) : `audio_indices` と一致する順序に並べられた、オーディオの潜在行列。

encoder_hidden_states (`torch.Tensor`、shape `(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`、shape `(seq_len, 3)`) : パックされたシーケンスの各行の `(t, h, w)` 回転座標。

video_indices (`torch.Tensor`、shape `(num_video_tokens,)`) : パックされたシーケンスにおける動画行の位置。

audio_indices (`torch.Tensor`、shape `(num_audio_tokens,)`) : パックされたシーケンスにおけるオーディオ行の位置。

text_indices (`torch.Tensor`、shape `(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[[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`、shape は `(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` を入力デバイスに戻す際にこの方法が使われます。

[MiniMaxH3Transformer3DModel](/docs/diffusers/main/ja/api/models/minimax_h3_transformer3d#diffusers.MiniMaxH3Transformer3DModel)の出力です。