# MiniMax-H3 MiniMax-H3 は、動画とそのサウンドトラックを同時に生成します。単一の transformer が、テキストの条件付け、条件付けメディア、およびターゲットとなる動画と音声の潜在変数を含む、1 つのパックされたシーケンスをデノイズします。独立した vocoder も、事後の音声処理パスも存在しません。動画と音声は、同じデノイジングループから出力されます。 [MiniMaxAI](https://huggingface.co/MiniMaxAI)組織の下で、元のMiniMax-H3のチェックポイントを見つけることができます。 MiniMax-H3 は [Modular Diffusers](../../modular_diffusers/overview) ブロックのみとして統合されており、[Anima](./anima) と同じです。つまり、ブロックとその [MiniMaxH3ModularPipeline](/docs/diffusers/main/ja/api/pipelines/minimax_h3#diffusers.MiniMaxH3ModularPipeline) が統合のすべてであり、`DiffusionPipeline` 側は存在しません。 ## チェックポイントのレイアウト MiniMax-H3 は、transformer を除くすべてのコンポーネントを共有する 2 つのチェックポイントパーティションとしてリリースされたため、diffusers による変換では両方を**1 つのリポジトリ**にまとめます: | サブフォルダ | ワークフロー | |---|---| | `transformer/` | `t2va`（テキストのみ）、`fl2va`（最初のキーフレームと/または最後のキーフレーム） | | `transformer_ref/` | `ref2va`（画像、動画、音声の参照の順序付きミックス） | Transformer 以外のコンポーネント、すなわち動画 VAE、音声 VAE、Qwen3-VL conditioner、その tokenizer と processor、および 2 つの scheduler は共有され、1 回だけ保存されます。 conditioner は `Qwen3VLForConditionalGeneration` であり、MiniMax-H3 は最後の層ではなく 50 番目の decoder layer 直後の *正規化されていない* hidden state を読み取ります。そのため、公開されている完全な checkpoint が使用され、language-model head は使用されません。 3つのタスクはすべて [MiniMaxH3Blocks](/docs/diffusers/main/ja/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks) のワークフローであり、リポジトリには各コンポーネントを独自の読み込み仕様とともに列挙した `modular_model_index.json` が含まれています。単一のタスクをサーブするには、そのワークフローを `from_pretrained` に渡します。これにより、そのワークフローのブロックのみが保持されるため、パイプラインのシグネチャ（`pipe.doc`）にはそのタスクのインプットのみがドキュメント化され、そのタスクのコンポーネントのみが宣言され、`load_components` はそれらのサブフォルダのみを取得します。つまり、`t2va` / `fl2va` パイプラインは `transformer_ref/` にアクセスせず、`ref2va` パイプラインは `transformer/` にアクセスしません。 ```py import torch from diffusers import ModularPipeline pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va") pipe.load_components(dtype=torch.bfloat16) ``` > [!TIP] > `pipe.doc` は、対象の pipeline が受け取る入力と返す出力を表示します。デフォルト値付きのすべての入力、期待されるコンポーネント、および生成される出力が列挙されます。特定の 1 つのワークフローに絞り込むことで、そのタスクが正確に記述されるため、リクエストを作成する前に必要なものを把握する最速の方法となります。 すべてのワークフローを1つのパイプラインで利用可能にするには、`workflow`引数を省略してください。そうすると、パイプラインは渡された入力に基づいて、呼び出しごとにワークフローを選択します。 ```py pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3") ``` *読み込み*は、依然としてワークフローごとに1つずつ行われます。この1回の呼び出しで、`transformer/`とすべての共有コンポーネントを取得し、`t2va`と`fl2va`の両方に使用できます。 ```py pipe.load_components(workflow="t2va", dtype=torch.bfloat16) ``` `load_components()` に `workflow=` を指定しない場合、**両方の** 61.7GB の transformer パーティションが読み込まれます。これにより、追加の読み込み呼び出しなしで 1 つのパイプラインが 3 つのワークフローすべてに対応できます。[ComponentsManager](/docs/diffusers/main/ja/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) と自動オフロードを組み合わせると、重みはホスト RAM に保持され、マネージャーは各ステップに必要な分だけをアクセラレーター上に移動します。そのため、`ref2va` デノイザーがデバイスが必要になったとき、戦略は十分な空き領域を確保するためにオフロードを行います。具体的な手順は [メモリ](#memory) を参照してください。 ## 2つのスケジューラ 1ステップごとの単一のtransformer呼び出し内で、動画と音声のlatentsはそれぞれ異なるスケジュールに沿ってステップダウンするため、ブロックは2つの[MiniMaxH3Scheduler](/docs/diffusers/main/ja/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler)インスタンスを期待します。動画latents用の`scheduler`（公開されているチェックポイントでは`shift=12.0`）と、音声latents用の`audio_scheduler`（`shift=3.0`）です。 両方の transformer パーティションは guidance-distilled であるため、この点はすべてのワークフローに当てはまります。guidance は重みに組み込まれており、guider も `negative_prompt` も `guidance_scale` も存在せず、各ステップでは正確に 1 回の forward pass が実行されます。 ## 生成の制約 - **24 fps、5〜15秒。** `num_frames`は、動画VAEがデコード可能な次の`17 * n + 5`に切り上げられ、生成される動画の長さはその範囲内に収まる必要があります。 - **短辺768ピクセル。** `height`と`width`のデフォルト値は、MiniMax-H3独自のキャンバス（最初のキーフレームのアスペクト比、キーフレームがない場合は16:9）であり、32の倍数である必要があります。 - **1つのジェネレーターから3回のサンプリング。** リクエストは、まずキーフレームまたは参照条件のノイズ、次に動画ノイズ、最後に音声ノイズを、渡された`generator`から順にサンプリングします。そのため、同じジェネレーター状態から2回実行しても、同じ動画とサウンドトラックが返されます。`latents`または`audio_latents`を渡すと、対応するサンプリングが置き換えられます。 - **`num_inference_steps` counts sigma grid points**, the terminal `0` included, so it drives one model evaluation less. ## メモリ transformer 単体は bfloat16 で 61.7 GB、Qwen3-VL conditioner はさらに 62.1 GB あるため、読み込み方法はハードウェアに依存します。すべての環境において、最も大きな速度改善の要因はキャンバスのサイズです。`height` と `width` は 32 の倍数であればよく、学習時の 1344x768 と比べて 960x544 を使用すると、ステップあたりの処理速度が約 2.3 倍速くなります。 80 GBのカード1枚上で、コンポーネントを[ComponentsManager](/docs/diffusers/main/ja/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager)に登録し、アクセラレーターへの移動と退避を委ねます: ```py import torch from diffusers import ComponentsManager, ModularPipeline manager = ComponentsManager() pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager) pipe.load_components(workflow="t2va", dtype=torch.bfloat16) manager.enable_auto_cpu_offload(device="cuda", memory_reserve_margin="12GB") # or "mps", "xpu", "cpu" pipe.transformer.set_attention_backend("_flash_3_hub") # Hopper, roughly 3x faster; kernels fetched from the Hub ``` コンシューマー向けGPU（24〜32 GB）では、読み込み時に2つの大きなコンポーネントをint8に量子化し、transformerのブロックをCPU RAMからストリーミングします。以下では、サポートされているローダーのみを使用し、パッチは不要で、bfloat16のチェックポイントからそのまま動作します。 ```py import torch from diffusers import MiniMaxH3Transformer3DModel, ModularPipeline, TorchAoConfig from diffusers.hooks import apply_group_offloading from transformers import Qwen3VLForConditionalGeneration from transformers import TorchAoConfig as TransformersTorchAoConfig from torchao.quantization import Int8WeightOnlyConfig pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3") pipe.update_components( transformer=MiniMaxH3Transformer3DModel.from_pretrained( "MiniMaxAI/MiniMax-H3", subfolder="transformer", dtype=torch.bfloat16, quantization_config=TorchAoConfig( Int8WeightOnlyConfig(version=2), modules_to_not_convert=[ "proj_in", "audio_proj_in", "context_embedder", "time_embedder", "time_proj", "token_refiner", "norm_out", "proj_out", "audio_proj_out", ], ), low_cpu_mem_usage=False, ), text_encoder=Qwen3VLForConditionalGeneration.from_pretrained( "MiniMaxAI/MiniMax-H3", subfolder="text_encoder", dtype=torch.bfloat16, quantization_config=TransformersTorchAoConfig( Int8WeightOnlyConfig(version=2), modules_to_not_convert=["model.visual", "model.language_model.embed_tokens", "model.language_model.norm", "lm_head"], ), ), ) pipe.load_components(workflow="t2va", dtype=torch.bfloat16) # version=2 int8 tensors are pinnable, which streamed offload needs, and freezing removes the one autograd # path the quantized tensors cannot serve. pipe.transformer.requires_grad_(False) pipe.text_encoder.requires_grad_(False) offload = dict(onload_device=torch.device("cuda"), offload_device=torch.device("cpu"), use_stream=True) pipe.transformer.enable_group_offload(offload_type="block_level", num_blocks_per_group=1, **offload) apply_group_offloading(pipe.text_encoder.model, offload_type="leaf_level", **offload) pipe.vae.to("cuda") # or "mps", "xpu", "cpu" pipe.audio_vae.to("cuda") ``` 12〜16 GB の環境では、`offload_type="leaf_level"`（ストリームなし）でビデオ VAE グループもオフロードし、960x544 のような小さなキャンバスを使用することで、同じレシピが機能します。重みはホスト RAM に配置されるため、int8 量子化の場合、約 75 GB の RAM が必要になることを想定してください。 2枚のカードを使用する場合、オフロードは不要です。パイプラインを2分割し、それぞれの半分を個別のデバイスに配置します。 ```py import torch from diffusers import ComponentsManager, ModularPipeline workflow = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3").blocks.get_workflow("t2va") text_manager = ComponentsManager() text_manager.enable_auto_cpu_offload(device="cuda:1") conditioner = workflow.sub_blocks.pop("text_encoder").init_pipeline( "MiniMaxAI/MiniMax-H3", components_manager=text_manager ) conditioner.load_components(dtype=torch.bfloat16) manager = ComponentsManager() manager.enable_auto_cpu_offload(device="cuda:0") rest = workflow.init_pipeline("MiniMaxAI/MiniMax-H3", components_manager=manager) rest.load_components(dtype=torch.bfloat16) prompt = "A red fox trotting through a snowy pine forest, snow crunching underfoot" state = conditioner(prompt=prompt) results = rest( state=state, num_frames=124, generator=torch.Generator().manual_seed(42), output=["videos", "audio", "sampling_rate"], ) ``` 2枚の80 GBカードでは、この方法でフルのbfloat16を実行できます。各半分がそれぞれ1枚のカードに収まるため、一度メモリに読み込まれた後はホストメモリへ退避されません。2枚の48 GBカードでも、上記のint8読み込みを両方のコンポーネントに適用することで同様に動作します。 ## テキストとキーフレーム [MiniMaxH3Blocks](/docs/diffusers/main/ja/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks)は、テキストから動画と音声への生成、およびキーフレーム条件付けに対応しています。キーフレームは、動画の開始フレーム(`image`)、終了フレーム(`last_image`)、またはその両方として指定できます。 ```py import torch from diffusers import ComponentsManager, ModularPipeline from diffusers.utils import load_image from diffusers.utils.export_utils import encode_video # 61.7GB of transformer and 62.1GB of conditioner do not sit on one accelerator, so the components are # registered in a manager that moves each one on and off as the blocks reach it. See [Memory](#memory). manager = ComponentsManager() manager.enable_auto_cpu_offload(device="cuda") # or "mps", "xpu", "cpu" pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager) pipe.load_components(workflow="fl2va", dtype=torch.bfloat16) prompt = "A red fox trotting through a snowy pine forest, snow crunching underfoot" # `output=` returns exactly the named outputs instead of the whole pipeline state. outputs = ["videos", "audio", "sampling_rate"] # Text to video + audio. results = pipe(prompt=prompt, num_frames=124, generator=torch.Generator().manual_seed(42), output=outputs) # First frame (and optionally last frame) to video + audio. The canvas follows the first keyframe. image = load_image( "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg" ) results = pipe(prompt=prompt, image=image, num_frames=124, generator=torch.Generator().manual_seed(42), output=outputs) encode_video( results["videos"][0], fps=24, output_path="minimax_h3_fl2va.mp4", audio=results["audio"][0], audio_sample_rate=results["sampling_rate"], ) ``` 動画と音声は同時に生成され、`sampling_rate` を伴うサウンドトラックとともに、`videos` と `audio` という別々の出力として呼び出しから返されます。これらを1つのファイルにマックスする処理は呼び出し側で行う必要があり、例えば [encode_video()](/docs/diffusers/main/ja/api/utilities#diffusers.utils.encode_video) を使用します。 ## オムニリファレンス `ref2va`ワークフローは、順序付きの参照リストを条件として使用します。最大9枚の画像、3本の動画、3つの音声クリップ、合計12個まで指定できます。順序には意味があります。プロンプト内の参照のラベル（`""`、`"