Antirez/h3.c: Mac用MiniMax H3推論エンジン
Antirez/h3.c: MiniMax H3 inference engine for Mac computers (github.com)
要約
Antirez氏が開発したh3.cは、Apple Silicon Mac向けに最適化されたMiniMax-H3推論エンジンです。Metal APIを活用し、プロンプトから動画や音声を生成する機能や、画像・動画・音声を参照する機能(Ref2VA)を実装しています。コマンドラインインターフェース(CLI)を通じて、モデルの検査、インタラクティブなセッション、高速な動画生成、参照品質に近い動画生成など、様々な設定で推論を実行できます。
全文翻訳
h3-metal
Apple Silicon向けのネイティブMiniMax-H3推論エンジン。このプロジェクトは、動作する垂直スライスのシーケンスとして構築されています。まず、決定論的なホスト/モデルメタデータ、次にポータブルなMetalブロックの同等性、プロンプトエンコーディング、プロンプトからビデオ/オーディオへの変換、そして最初/最後のフレーム条件付け、順序付けられた参照です。
プロンプトからビデオ/オーディオへの変換、最初/最後のフレーム条件付け、順序付けられたRef2VA画像/ビデオ/オーディオ参照はエンドツーエンドで動作します。現在の作業は、M3 MaxおよびM5 MaxでのH3固有のMetalパフォーマンスとメモリ最適化の増分的なものです。
チュートリアル
1. モデルのビルドと検査
例では、Hugging Faceのスナップショットが./MiniMax-H3にあり、FFmpegとFFprobeがPATHで利用可能であることを想定しています。
make -j8
mkdir -p outputs
./h3 --info -d ./MiniMax-H3
--infoはモデルレイアウトをチェックし、すべての重みをマッピングしたりメディアを生成したりせずに、選択されたMetalデバイスを表示します。完全なCLIリファレンスについては、./h3 --helpを実行してください。
-pなしでは、同じバイナリがIrisスタイルのインタラクティブセッションを開始します。
./h3 -d ./MiniMax-H3 --width 512 --height 512 --steps 6
プロンプトを入力すると、番号付きのビデオが生成されます。セッションは、BF16プロンプト条件付け、準備されたDiT、およびビデオデコーダーをメモリ内に保持するため、別のシードでプロンプトを繰り返しても、それらを再度ロードおよびエンコードする必要がありません。便利なコマンドは!status、!seed random、!seconds 2、!show、!save output.mp4、!cacheです。完全な短いリストについては!helpを使用してください。
最初/最後のフレーム条件付けはセッション内で永続化されます。
h3> !first opening.png
h3> !last ending.png
h3> The camera moves slowly around the subject.
アンカーを削除するには、!first clearまたは!last clearを使用します。生成されたビデオは、起動時に表示されるセッションディレクトリに書き込まれます。
一般的なRef2VA条件付け画像には、代わりに!ref-image PATHを使用してください。画像は順序付けられて追加され、モデルには<Picture 1>、<Picture 2>などとして公開されます。ファイル名にモデルにとっての意味はありません。
h3> !ref-image person.png
h3> Make the person shown in Picture 1 wave to the camera.
!refsは現在の順序をリストし、!ref-remove Nは1つのエントリを削除し、!refs clearはすべて削除します。Ref2VA参照は!first/!lastアンカーと混在させることはできません。
2. 最初の高速ビデオを作成する
検証済みのバランスの取れたプリセットから始めます。これは24fpsで22フレーム(約0.92秒)を生成し、サポートされているグラフィカルターミナルで各デノイズ遷移後に進化する中間ビデオフレームを表示し、フェーズタイミングを印刷します。
./h3 --profile \
-d ./MiniMax-H3 \
-p "A red fox walks through fresh snow in a pine forest. Medium tracking shot, natural winter light, realistic fur, soft footsteps and wind."
--width 512 --height 512 \
--frames 22 --steps 20 \
--layers 45 --reuse 2 \
--show \
-o outputs/fox-fast.mp4
これは意図的に最もアグレッシブな設定ではありません。
--steps 20はデフォルトの20回のデノイズパスを実行します。--reuse 2は、すべての20回ではなく11回の新しいデノイザー速度を計算し、スキップされた遷移を補外します。--layers 45は50個のTransformerブロックのうち45個を実行し、時間とユニファイドメモリの使用量を削減します。--showはオプションです。Kitty/GhosttyおよびiTerm2/WezTerm/Konsoleグラフィカルプロトコルをサポートします。常駐プレビューVAEをロードし、各Euler遷移後に代表的な中間ビデオフレームを1つ表示し、その後すべての最終フレームを表示します。表示寸法はデフォルトで2xなので、画像はmacOS Retinaディスプレイで意図した論理サイズになります。HiDPIディスプレイでない場合は--zoom 1を使用してください。これはプレビューデコード時間と約10GiBの一時的なモデル常駐を追加します。--showなしの実行は変更されません。--profileはオプションであり、異なる生成パスを選択しません。
最初のプロセス呼び出しでは、モデルロードとファイルシステムキャッシュのコストもかかります。繰り返し実行を使用してパフォーマンスを比較し、このワークロードは熱スロットリングに敏感であるため、マシンがウォームアップしている間にバリアントを切り替えてください。
非常に短いイテレーションのために、直接4回のデノイズパスを要求します。
./h3 --profile \
-d ./MiniMax-H3 \
-p "A red fox walks through fresh snow in a pine forest. Medium tracking shot, natural winter light, realistic fur."
--width 512 --height 512 --frames 22 \
--steps 4 --layers 50 --reuse 1 \
--show \
-o outputs/fox-four-step.mp4
--steps Nは常に正確にN回のデノイズパスを意味します。4から7パスは、低予算比較で勝利したのと同じスケジュールを使用します。4から7への増加は、詳細とモーションを段階的に改善します。このような小さな予算では--reuse 1を維持して、要求されたすべてのパスがモデルを実行するようにしてください。--showは各パスの後に1つのプレビューを表示します。
ほとんどの視覚的なクリーンアップは長い実行の後半で発生するため、いくつかのテールヘビーなスケジュールが評価されました。それらは初期のコンポジション更新を十分に保持せず、織り交ぜられたテクスチャ、弱いモーション、またはクリップされた色を生成しました。保持モードは、1つの終端点を持つリリースされた線形ベースグリッドを使用します。512平方、22フレームのキツネテストでは、選択された4パスの結果は29パス参照に対して0.556のフルビデオSSIMでした。独立したサーファーテストでは0.547を測定しました。4パスデノイズはM5 Maxで約3.5秒かかりましたが、参照は26.4秒でした。
低メモリ実行のために、--ssd-streamingを追加します。
./h3 --profile \
-d ./MiniMax-H3 \
-p "A red fox walks through fresh snow in a pine forest."
--width 512 --height 512 --frames 22 --steps 20 \
--layers 50 --reuse 1 --ssd-streaming \
-o outputs/fox-ssd.mp4
これは、変換または量子化なしで元のBF16チェックポイントを使用します。2つのDiTブロックをメモリに保持し、GPUが現在のブロックを実行している間にSSDから次のブロックを読み取ります。M5 Maxでは、512平方で約36.5GiBから2.0GiB、864x480で2.1GiBにDiTストレージが減少しました。ウォームな50ブロックフォワードは、512平方で1.35秒対2.49秒(84%遅い)、864x480で2.14秒対2.68秒(26%遅い)を測定しました。これらは同じフルレジデンシーBF16パスとの比較であり、結果は両方のチェックでバイト単位で同一でした。
2.0--2.1 GiBという数値は、DiTの追跡されたテンソルストレージであり、システムRAMの合計ではありません。プロンプトエンコーディングと2つのVAEは、それぞれのピークをそれに加えるのではなく、別々のフェーズで実行されます。OS、メディアバッファ、および出力解像度は依然としてヘッドルームを必要とします。--showはプレビューVAEを常駐させ、約10GiBを追加するため、最低メモリ実行では省略してください。
SSDストリーミングは明示的なメモリ/速度のトレードオフであり、デフォルトではありません。--use-int8-row-fc2と組み合わせることはできません。インタラクティブセッションでは、!ssd-streaming onを使用します。
3. リファレンス品質に向けて進む
品質を評価する際は、一度に1つのコントロールを変更してください。まずすべてのレイヤーを復元し、次にすべてのデノイザー評価を復元し、最後にデフォルトの20パススケジュールをより遅い50パスリファレンスに引き上げます。
./h3 --profile \
-d ./MiniMax-H3 \
-p "A red fox walks through fresh snow in a pine forest. Medium tracking shot, natural winter light, realistic fur, soft footsteps and wind."
--width 512 --height 512 \
--frames 22 --steps 50 \
--layers 50 --reuse 1 \
-o outputs/fox-close.mp4
デフォルトは--steps 20 --layers 50 --reuse 1です。このクローズパスでは--steps 50を明示的に維持してください。これは50回の完全な50ブロックデノイザーフォワードを実行し、デフォルトよりもはるかにコストがかかりますが、高速モードが被写体、解剖学的構造、モーション、またはコンポジションを変更した場合の適切なオラクルです。MLXとの数値的なピクセル同一性は、乱数および実行エンジンが異なるため期待できません。描画されたコンテンツとモーションは一致するはずです。
4. スピード/品質プリセットを選択する
これらのコントロールは、特に記載がない限り独立しています。
| コントロール | スローリファレンス | デフォルト | アグレッシブ | 主な影響 |
|---|---|---|---|---|
| デノイズパス | --steps 50 | --steps 20 | --steps 4..7 | 数値は常に実際のデノイズパスを指します。 |
| 全デノイザー再利用 | --reuse 1 | --reuse 2 | --reuse 3 | 20ステップで: 20、11、または8回の新しいDiT評価。 |
| アクティブDiTブロック | --layers 50 | --layers 45 | --layers 40 | ブロック数が少ないほど、計算と常駐Transformerウェイトが削減されます。 |
| コア残差再利用 | --core-reuse 1 | --core-reuse 4 | --core-reuse 6 | ステップごとにパッチ/ヘッドワークをリフレッシュしますが、高コストなコアの実行頻度は低くなります。 |
| トークン削減 | オフ | オプション | --token-reduction | 中間ブロックで水平ビデオトークンをペアにします。高速ですが、コンポジションが変更される可能性があります。 |
| 内部キャンバス | 出力サイズ | 512平方出力の場合384x384 | 320x320 | DiT/VAEを小さく実行し、vImageでアップスケールします。 |
M5では、--use-int8-row-fc2はFC2行ごとに1つのアクティベーションスケールと単一のフル幅TensorOps積を使用します。グループ化されたint8よりも数値的に保守的ではないため、オプションです。逆テストでは、完全なデノイザーフォワードを約2.6%削減しました。一致した4ステップのキツネとサーファーのビデオは、同じ被写体、設定、モーション(フルビデオSSIM 0.919および0.828)を維持しました。インタラクティブセッションでは、!int8-row-fc2 onを使用します。
--reuseと--core-reuseは排他的です。レイヤーの間引きは、どちらかの再利用と組み合わせることができます。
最初のコマンドを高速化し、出力解像度を維持するには、トークン削減を追加します。
./h3 --profile \
-d ./MiniMax-H3 \
-p "A surfer riding inside a sharp blue ocean wave, one rider and one white board, realistic spray."
--width 512 --height 512 --frames 22 --steps 20 \
--layers 45 --reuse 2 --token-reduction \
-o outputs/surfer-fast.mp4
検証済みの512平方形状で、トークン削減はIT M5 Maxで45 layers + reuse 2デノイズプロファイルを16.69秒から12.60秒に削減しました。独立したキツネとサーファーのレンダリングは一貫性を保ちましたが、コンポジションはクローズパスからより逸脱する可能性があります。
アグレッシブなプレビューのために、320平方で内部的にレンダリングし、要求された512平方出力にアップスケールします。
./h3 --profile \
-d ./MiniMax-H3 \
-p "A red fox walking through snow, realistic, tracking shot."
--width 512 --height 512 \
--render-width 320 --render-height 320 \
--frames 22 --steps 20 --layers 40 --reuse 3 \
-o outputs/fox-aggressive.mp4
この組み合わせは、検証でクリーンで認識可能な22フレームのキツネを生成しましたが、細かいディテールを失い、フレーミングを変更する可能性があります。--layers 40と--reuse 3の両方に--token-reductionを追加しないでください。そのテストされた組み合わせは、許容可能なラテントノルムにもかかわらず、色のにじみ、輪郭、およびゴーストのような手足を生成しました。
全体的な速度再利用の代替として、これはタイムステップ依存のパッチと出力ヘッドを各遷移で新鮮に保ちます。
./h3 --profile \
-d ./MiniMax-H3 \
-p "A surfer riding a blue ocean wave."
--width 512 --height 512 --frames 22 --steps 20 \
--layers 45 --core-reuse 4 \
-o outputs/surfer-core-reuse.mp4
--core-reuse 6はアグレッシブなプレビューとしてのみ使用してください。6を超える値は、検証で被写体の忠実度が失われたため公開されていません。
5. 解像度と期間を選択する
幅と高さはそれぞれ32の倍数で、少なくとも32である必要があり、それらの積は768 * 1344ピクセルを超えてはなりません。これらは機械的な制限であり、すべての小さなキャンバスに良いモデル品質があるという保証ではありません。H3-Baseは768pモデルです。
| キャンバス | 現在のガイダンス |
|---|---|
512x512 | 最も安全な開発サイズ。複数のプロンプトで繰り返し検証済み。 |
768x768 | 検証済みのクローズ品質スクエア出力。大幅に高コスト。 |
1344x768、768x1344 | リリースされた768pクラスのランドスケープ/ポートレート制限。 |
1024x768、768x1024 | 有効な4:3および3:4の768pクラスキャンバス。 |
512x512への内部384x384 | 検証済みの高速品質スケーリングポイント。 |
512x512への内部320x320 | 検証済みのアグレッシブスケーリングポイント。 |
256x256 | 自動低解像度RoPEアダプテーションを備えたネイティブ高速プレビューキャンバス。 |
高速ネイティブ256スクエアプレビューの場合。
./h3 -d ./MiniMax-H3 \
-p "A red fox walks through fresh snow in a pine forest."
--width 256 --height 256 \
--frames 22 --steps 20 \
--layers 50 --reuse 1 \
-o outputs/fox-256.mp4
256平方では、H3は8x8の有効な空間トークングリッドしか持たないため、細かいディテールや複雑なコンポジションの余地が少なくなります。H3は、正確に256平方で空間RoPE座標を自動的に半分にします。これにより、長いキツネのレンダリングでの繰り返し格子アーティファクトが削除され、独立したポートレートで一貫性が保たれ、トークンや実行時間を追加することなく実現しました。リリース/MLX座標を復元してパリティチェックを行うには、--use-reference-ropeを使用します。このサイズではトークン削減をオフのままにしてください。ネイティブ128平方は引き続きサポートされていません。その4x4トークングリッドは、調整されたRoPEを使用しても認識可能な被写体を回復しませんでした。
--render-widthと--render-heightは一緒に設定する必要があり、出力と同じアスペクト比を持ち、出力寸法を超えることはできません。モデルとVAEは内部サイズを使用し、ターミナルフレームとエンコードされたビデオは要求された出力サイズを保持します。
H3は24fpsを出力し、フレーム要求を5 + 17*nに上限します。
期間指向の要求には--seconds Nを使用するか、直接フレーム制御には--frames Nを使用します。これら2つのオプションは排他的です。小数秒も受け入れられます。秒は24fpsで変換され、次に合法的なH3時間形状の次のものに切り上げられます。したがって、--seconds 10は243フレーム(10.125秒)を生成します。
| フレーム | おおよそのビデオ期間 |
|---|---|
| 22 | 0.917秒 |
| 39 | 1.625秒 |
| 56 | 2.333秒 |
| 107 | 4.458秒 |
| 243 | 10.125秒 |
| 362 | 15.083秒 |
短いクリップは開発に役立ちます。リリースされたワークフローは、約4〜15秒のビデオを対象としています。--frames 23のような要求は、任意の時間形状を生成するのではなく、39フレームに切り上げられます。
6. プロンプトを改善する
短いプロンプトでも機能しますが、リリースされたシステムはContext-IRライクな説明を期待しています。被写体、アクション、設定、カメラ、照明/スタイル、および望ましいサウンドを記述してください。例:
Scene: a single red fox in a snow-covered pine forest at dawn.
Action: the fox walks steadily left to right and looks toward the camera once.
Camera: medium-height lateral tracking shot, 50 mm lens, stable framing.
Look: photorealistic fur, cold blue ambient light, warm sunrise rim light.
Audio: soft footsteps in snow, light wind through pine branches, no music.
重要であれば、アイデンティティとオブジェクトの数を明示してください。--seed Nはネイティブ乱数ストリームを制御します。デフォルトは42です。同じプロンプト、シード、解像度、フレーム数、およびステップ数でオプションを比較してください。
7. フレームのプレビューとパフォーマンスの診断
--showは、各デノイズ遷移後に代表的なフレームを表示し、その後、完了したビデオのすべてのフレームを表示します。Irisと同様に、デフォルトでRetinaターミナル用に2倍の表示寸法を広告します。--zoom Nは、生成されたビデオやエンコードされたターミナル画像のサイズを変更せずに、その係数を変更します。--frames-dir DIRは、最終的なコールバックフレームをPPMファイルとして書き出します。中間的な--showプレビューはそこに書き込まれません。-o ''はMP4エンコーディングを無効にします。FFmpegが利用できない場合は、--frames-dirと組み合わせて使用してください。--profileは、フェーズの壁時間、Metalエンコーディング/待機時間、ピークライブテンソルストレージ、累積割り当て、およびディスパッチカウントを報告します。
例:
./h3 --profile -d ./MiniMax-H3 -p "A hummingbird hovering over red flowers."
--width 512 --height 512 --frames 22 --steps 20 \
--layers 45 --reuse 2 --frames-dir outputs/hummingbird-frames \
-o ''
8. 画像、ビデオ、およびオーディオ参照を追加する
最初/最後のフレームアンカーはFL2VAパスを選択します。
./h3 -d ./MiniMax-H3 -p "The fox keeps walking through the snow."
--width 512 --height 512 --frames 22 --steps 20 \
--layers 45 --reuse 2 \
--first-frame fox.png --last-frame fox-later.png \
-o outputs/fox-anchored.mp4
順序付けられた参照は、個別のRef2VAチェックポイントを選択します。メディアセマンティクスに対応するフラグを使用してください。
# 1つの画像参照。
./h3 -d ./MiniMax-H3 -p "Use the animal and setting in the reference."
--width 512 --height 512 --frames 22 --steps 20 \
--ref-image fox.png -o outputs/fox-reference.mp4
# クリップを続行しますが、サウンドトラックは無視します。
./h3 -d ./MiniMax-H3 -p "Continue the motion in this clip."
--width 512 --height 512 --frames 22 --steps 20 \
--ref-silent-video fox.mp4 -o outputs/fox-video-reference.mp4
# クリップの埋め込みオーディオを保持します。
./h3 -d ./MiniMax-H3 -p "Continue this audiovisual scene."
--width 512 --height 512 --frames 56 --steps 20 \
--ref-video fox-with-audio.mp4 -o outputs/fox-video-audio.mp4
# ビデオのサウンドトラックを明示的に置き換えます。
./h3 -d ./MiniMax-H3 -p "Continue the scene with the supplied music."
--width 512 --height 512 --frames 56 --steps 20 \
--ref-video-audio silent-fox.mp4 replacement.wav \
-o outputs/fox-replaced-audio.mp4
# 順序付けられた画像とスタンドアロンオーディオ参照。
./h3 -d ./MiniMax-H3 -p "Use the animal and music from the references."
--width 512 --height 512 --frames 56 --steps 20 \
--ref-image fox.png --ref-audio music.wav \
-o outputs/fox-image-audio.mp4
参照フラグは繰り返し指定でき、コマンドラインの順序が保持されます。スタンドアロンオーディオは、画像またはビデオ参照と組み合わせて指定する必要があります。オーディオ参照は2〜15秒である必要があり、最大3つのオーディオ入力が受け入れられ、それらの合計デコード期間は15秒に制限されます。
テストと実行時要件
make test
make parity
make testは決定論的なホストスイートを実行し、無視されるMLXフィクスチャがmisc/fixtures/の下にインストールされている場合、実行時にMetalソースをコンパイルし、名前付きMLX出力に対して完全なトイH3ブロックをチェックします。実行時コンパイルは意図的です。Irisに従い、XcodeのオプションのオフラインMetalツールチェーンは必要ありません。テストはF32診断パスとプロダクションBF16ストレージパスの両方をカバーします。ワイドBF16行列積とSDPAはキャッシュされたMPSGraphグラフを使用し、直接Metalの正確性フォールバックを使用します。make parityはこれらのMetal/MLXチェックのみを実行します。
メディア入力とMP4出力(H3_FFMPEGおよびH3_FFPROBEは明示的な実行可能ファイルを選択できます)には、FFmpegとFFprobeがPATHで利用可能である必要があります。生成されたRGB24および32kHzステレオF32 PCMは、同時パイプを介して供給されます。中間非圧縮メディアファイルは作成されません。
実装とパフォーマンスに関する注記
残りは、チュートリアルプリセットの背後にある実装と、正確なA/B診断のために保持されている環境変数について説明します。
サンプラーとDiTコントロール
デフォルトのサンプラーは、リリースされたシフトされたビデオ/オーディオスケジュールを使用します。--stepsは常にデノイズパスの数を指し、最後のパスの後に終端ゼロが追加されます。全体的なデノイザー再利用は、最初と最後のパスに加えて要求された各間隔を評価し、その後、独立したスケジュールでスキップされたビデオとオーディオの速度を補外します。非常に少ないステップ数では、--reuse 1を維持してください。
低予算パスでは、リリースされた線形ベースグリッドは、実際のビデオシグマ線形間隔、二次および三次ワープ、正確な30点テールサブセット、軽度のパワーワープ、ゼロ次ホールドされたフルグリッド速度、線形速度補外、およびRESに対して優位でした。よりテールヘビーな候補は、しばしば被写体をシャープにしましたが、モーションを損傷したり、繰り返し織り交ぜられた背景を残したりしました。スパースRESと長い補外間隔は、はるかに目に見えて失敗しました。
レイヤーの間引きは、構造的に重要な最初と最後のブロックを保護しながら、チェックポイントの実際のAdaLNゲートをランク付けします。未使用の重みとスケジュールテンソルは保持されないため、--layers 45と--layers 40はTransformer時間とユニファイドメモリの両方の使用量を削減します。コア再利用は、パッチ射影とタイムステップ対応ヘッドをリフレッシュしながら、前の完全なTransformer残差を保持します。これは全体速度再利用と排他的です。
Exact DiTフュージョン
各アクティブなDiTブロックは、そのアテンション残差ゲートを次のMLP AdaLNと融合します。丸められたBF16残差は依然として正確に書き込まれますが、正規化のために同じ行がスレッドグループメモリに保持され、1つのディスパッチと1つのグローバル再読み取りが不要になります。トークン削減境界から離れた場所では、MLP残差ゲートも次のブロックのアテンションAdaLNを生成し、その正規化された状態をループ全体で伝達します。H3_DISABLE_FUSED_GATE_ADALN=1およびH3_DISABLE_FUSED_CROSS_BLOCK_ADALN=1は、2カーネルオラクルを復元します。最終的なオーディオ/ビデオAdaLNカーネルは、残差ストリームのオフセットに直接バインドされ、2つのスライスブリットと512x512(864クラスベンチマーク形状で37.5/58.9 MiB)でのスクラッチを回避します。H3_DISABLE_FUSED_FINAL_SLICE=1は、ロード時のコピープラスAdaLNオラクルを復元します。BF16の最終ヘッドは、16x16射影タイルをロードしながらAdaLNを適用し、スタンドアロンの丸めと累積順序を保持しながら、等しいサイズの正規化されたアクティベーションを1つ削除します。これら2つの最適化は合計で37.5/58.9 MiBを節約します。H3_DISABLE_FUSED_FINAL_HEAD=1は、ロード時のオフセットAdaLNプラスリニアオラクルを復元します。
トークン削減の内部構造
--token-reductionは独立したアグレッシブなDiTモードです。ブロック3の後、テキスト、オーディオ、条件、および参照トークンは正確なまま、隣接する水平ターゲットビデオトークンをペアにします。完全なフル解像度状態はバイパスとして保持されます。最初の10回のノイズの多い評価中に、ブロック40の前に復元されます。後続の詳細形成評価は、ブロック30の前に復元されます。各トークンは、ペアによって学習された更新に加えて元の値として返されるため、ペア内の詳細は破棄されません。プーリングカーネルは、真のペアベースラインのみを既に割り当てられているアテンションスクラッチバッファの密なテールに書き込みます。奇数幅のシングルトン・トークンはベースラインを必要としません。フルバイパスは、オーバーサイズのQKVテールが収まる場合にそれを使用し、参照が多いレイアウトのために保護された専用フォールバックのみを使用します。したがって、一般的なテキストのみのキャンバスは、任意のトークングリッド幅でアクティベーションアリーナを追加しません。プーリングは、ソーストークンの両方をスナップショットし、それらのBF16値が既にレジスタにある間に、別個のフル隠蔽ブリットと冗長なソース読み取りを回避します。同じエントリカーネルは、各プーリングされた行をスレッドグループメモリに保持し、最初の削減ブロックのアテンションAdaLNをエミットし、別のグローバル残差読み取りを不要にします。復元境界では、最初のフル解像度アテンションAdaLNは拡張に融合されます。10.5 KiBのスレッドグループ行は、正確なバイパスが必要な次の残差ブランチを書き込みながら、グローバル残差の再読み取りを回避します。サーマルバランスの取れた512x512x22、19フォワードIT M5 Max A/Bで、これはデノイズ時間を39.13秒から28.06秒(28.3%)に削減しました。最終的なビデオ/オーディオラテント相対L2は5.56%/15.14%でした。最初/中間/最後のキツネフレームは、1つのクリーンなマズル、一貫した脚、およびシャープな毛皮を保持しました。独立したサーファーは、波の飛沫を通して1人のライダーとボードと一貫性を保ちました。コンポジションを変更するため、クローズリファレンスデフォルトではなくオプトインです。H3_TOKEN_REDUCTION_BLOCKSは、後者の4:30間隔をオーバーライドできます。H3_TOKEN_REDUCTION_EARLY=STEPS:ENDは早期スケジュールをオーバーライドし、0はそれを無効にします。H3_DISABLE_TOKEN_REDUCTION=1は、インコンテキストの正確なオラクルを提供します。H3_DISABLE_FUSED_TOKEN_POOL_ADALN=1およびH3_DISABLE_FUSED_TOKEN_ADALN=1は、診断のために2カーネルエントリとエグジット境界を個別に復元します。トークン削減は、検証済みの--layers 45 --reuse 2設定とクリーンに構成されます。同じ512ベンチマークで、それはそのプロファイルを16.69秒から12.60秒(24.5%のマージナル)に削減し、独立したキツネとサーファーのレンダリングは一貫性を保ちました。--layers 40と--reuse 3の両方と組み合わせないでください。その6.47秒の実験は、許容可能なラテントノルムにもかかわらず、色のにじみとゴーストのような手足を生成しました。
内部キャンバスとビデオVAE
--render-widthと--render-heightは、モデルとVAEをより低い同じアスペクト比の内部キャンバスで実行し、コールバック、ターミナル表示、およびエンコーディングの前に要求された出力サイズに高品質のvImageスケールRGBフレームをアップスケールします。これは明示的な品質/速度のトレードオフです。測定された384から512へのプロンプトレンダリングは、M5のDiT時間を33%、ビデオVAE時間を18%削減し、クリーンで認識可能なフォトリアリスティックな結果を維持しました。両方の値は32の倍数である必要があります。正確な出力キャンバスはデフォルトのままです。スクエア512出力の場合、384は高速品質ポイントであり、320は検証済みのアグレッシブポイントです。後者は一貫した歩行キツネを生成し、ネイティブの約15.82秒に対してDiTで8.02秒で繰り返されました。ネイティブ256は同じコストの空間RoPEアダプテーションを使用します(上記参照)。これは、512または768クラスの最終レンダリングの代替ではなく、高速コンポジションプレビューのままです。ビデオVAEは、要求されたキャンバスジオメトリから256-320ピクセルの空間タイルを自動的に選択し、繰り返しオーバーラップ作業を最小限に抑えながらピークストレージを制限します。H3_VAE_TILE_PIXELS=256は、クローズリファレンス診断のために元の保守的なタイル計画を復元します。
重み常駐とストリーム化されたプロンプトエンコーディング
M5クラスのGPUでは、永続的なTransformer重みは、匿名共有バッファにコピーされるのではなく、safetensorシャードから直接ファイルバックされます。これにより、37GiBのモデルファイルがバックアップ/回収可能になり、合計Transformer時間がわずかに改善されます。M3はより高速なコピーバッファパスを使用します。H3_ZERO_COPY_WEIGHTS=0は、診断のためにM5の選択を無効にします。ストリーム化されたQwenテキストエンコーダーは、少量の将来のレイヤーバッファリングを事前割り当てし、Metalが現在のレイヤーを実行している間に8つのI/Oワーカーでそれらを埋めます。デフォルトのリング深度は、ターゲットマシンが128GiBを持つM3/古いハードウェアでは2レイヤー、M5では3レイヤーです。H3_QWEN_PREFETCH=0は単一レイヤー同期リファレンスパスを復元します。値1-8はワーカー数を選択し、H3_QWEN_PREFETCH_DEPTH=1から6はリング深度をオーバーライドします。
--ssd-streamingは、DiTのための別の、よりアグレッシブな常駐モードです。その小さなブロックごとの正規化重みのみが常駐します。2つの完全なBF16行列スロットが交互に配置され、バックグラウンドリーダーがチェックポイントオフセット順に次のスロットを埋めます。現在のMetalコマンドバッファは並列に実行されます。Darwinのキャッシュされていない読み取りは、ファイルシステムキャッシュに2番目のコピーを保持することを回避します。最初のアクティブブロックは、最後のブロック中に再度プリフェッチされるため、キャッシュされたインタラクティブDiTは次のデノイザー評価の準備ができています。測定では、内部SSDから約13〜14.6 GiB/sに達しました。H3_PROFILE=1は、合計バイト数、読み取りスループット、およびGPU作業によって隠されなかった読み取り待機部分を報告します。
Metal 4とTensorOpsパス
M5 GPUは、シーケンス長が2,048まで、DiT QKVおよびアテンション出力射影のために、ネイティブBF16 Metal 4/TensorOpsを自動的に使用します。コンパクトなモートン・スケジュールは、Q/K/Vをヘッドメジャー・アテンション入力に直接ルーティングし、3つのMPSGraph入力トランスポーズを回避し、ポータブルパスとバイト単位で同一です。これは、完全な512x512 50ブロックフォワードを、繰り返し実行されるIT/US M5 Max実行全体で約2%改善します。2,049〜3,072行(864x480を含む)の場合、2つの行オフセットモートンディスパッチは効率的なタイルジオメトリを維持し、バランスの取れた実行で完全なフォワードを約2%改善します。さらに大きなシーケンスはMPSGraph上に残ります。H3_NAX=0は、正確なA/B診断のためにTensorOpsを無効にします。選択は実行時に保護され、コンパイルが利用できない場合は変更されていないポータブルライブラリにフォールバックします。
H3_NAX=1は、より広範なネイティブBF16リニアパスを強制します。これは完全な50ブロックMLXフィクスチャをパスしますが、オプトインのままです。正確な形状のマイクロベンチマークは、その128行タイルを好みますが、完全なDiT実行は現在MPSGraphスケジューリングを好みます。これは、ベンチマークの低下をデフォルトにすることなく、将来の量子化/融合カーネルのために動作するNAX統合を利用可能に保ちます。H3_NAX=mlpは、より専門化されたMetal 4パスを選択します。ペア化されたFC1ゲート/アップTensorOpsタイルは、スレッドグループメモリでSwiGLUを適用し、14,336幅のアクティベートされた中間結果のみを書き込みます。その後、FC2もTensorOps上に残ります。H3_DISABLE_NAX_MLP=1は、この方法で作成されたコンテキストでMPSGraph MLPを保持し、プロセス内A/Bテストを行います。このパスは、スケジューリングがOS GPUスタックに依存するため、意図的にオプトインです。プライマリmacOS 26.5.2 M5 Maxは、分離されたリアルウェイトMLP実行で1.3〜2.0%向上しましたが、同様のmacOS 26.5 M5 Maxでは完全な50ブロックフォワードで約1〜3%低下しました。結果の50ブロック速度は近かった(ビデオで1.9%、オーディオで2.4%の相対L2)ですが、バイト単位では同一ではありませんでした。
特殊化された射影カーネル
狭いDiTオーディオ/ビデオ出力ヘッドは、小さなリリースされたF32重みをBF16に一度変換し、Iris由来の16x16タイルリニアをBF16アクティベーションで直接使用します。プロダクションの320レンダリングジオメトリでは、分離されたペアヘッド測定はM3 Maxで2.30倍、M5 Maxで1.83倍高速で、相対L2は8.64e-4です。絶対M5の節約は約0.6 ms/評価ステップです。完全なキツネとサーファーのシーケンスはクリーンなままで、F32ヘッドレンダリングに対して29.9/38.4 dBを測定しました。H3_DIT_F32_FINAL=1は、クローズリファレンスヘッドとその追加のアクティベーションバッファを復元します。F32 96->5376ビデオおよび32->5376オーディオパッチ射影は、専用の16x16協調タイルを使用し、F32重み、入力、および累積を保持しながら、タイルの結果を直接BF16に丸めます。ペア化されたプロダクション形状測定は、M3で1.77倍、M5で1.62〜1.78倍高速です。生成された完全なRGBストリームは、スカラーパスとバイト単位で同一です。最終キャストの融合は、2835行タイル自体をM3で2.499 msから1.734 ms、M5で1.555 msから1.186 msに改善し、512/864クラスのジオメトリでF32スクラッチを38.27/59.66 MiB削除します。H3_DISABLE_FUSED_PATCH_CAST=1は、タイル化されたF32出力とスタンドアロンキャストを復元します。H3_SCALAR_PATCH=1はスカラー診断パスを選択します。同じタイルは、その出力をパックされた隠蔽ストリームに直接バインドし、BF16メディアステージングバッファとそのブリットを不要にします。これにより、さらに19.13/29.83 MiBが節約され、2835行境界がM3で1.847 msから1.730 ms、M5で1.282 msから1.184 msに改善されます。連続したT2VAはバイトオフセットを使用します。FL2VA/Ref2VAはコンパクトな宛先行マップを使用するため、各モダリティは1つの大きなディスパッチのままです。完全な6セグメントRef2VA M5 ABBAはバイト単位で同一であり、測定されたフォワードペアあたり5.067秒から5.033秒に改善されました。H3_DISABLE_FUSED_PATCH_PACK=1は、ステージングバッファとパッキングブリットを復元します。
スケジューリングとアクティベーションメモリ
DiTコアは2つの順序付けられたMetalコマンドバッファに分割されているため、最初の部分のGPU実行は2番目の部分のCPUエンコーディングとオーバーラップします。サーマルバランスの取れたABBA測定では、M5で60%の深度分割(30/50、27/45、24/40)が選択され、約0.5〜1.8%の勝利が得られます。M3は検証済みの30/50ケースのみを自動的に分割し、1.2%高速と測定されました。なぜなら24/40はそこで後退したからです。操作順序と生成されたバイトは変更されません。H3_DIT_COMMAND_BLOCKS=0は1つのコマンドバッファを復元します。値1〜50は、さらなるチューニングのために分割をオーバーライドします。DiTアクティベーションバッファも実際のブロック内ライフタイムに従います。QKV射影アリーナは、まずアテンションヘッドに、次に正規化されたMLP入力に再利用され、現在のアテンション出力アリーナは、そのブランチが消費された後にMLP出力になります。これにより、512クラスのジオメトリで61.25 MiB、864クラスのジオメトリで99.63 MiBが削除され、ディスパッチや算術演算は変更されません。H3_DISABLE_DIT_ACTIVATION_ALIAS=1は、別々のアクティベーションバッファを復元します。不変のDiT重みとバイアスのためのMPSGraphテンソルデータラッパーは、それらの常駐バッファと共に保持されます。これにより、テンソルストレージをコピーせずに、各ブロックとデノイザー評価のために同じバインディングメタデータを再構築することが回避されます。測定されたABBAゲインはM3 Maxで1.6%、M5 Maxで0.4〜1.1%でした。アクティベーションラッパーは一時的なままですが、それらを保持するとM5が後退しました。出力はバイト単位で同一であり、H3_DISABLE_GRAPH_DATA_CACHE=1はすべてのテンソルのためのトランジェントラッパーを復元します。M3/古いハードウェアでは、各DiTブロックの4つのMPSGraphセグメントも、共通の基盤となるMetalコマンドバッファのために1つのMPSCommandBufferラッパーを再利用します。繰り返し実行されるサーマルバランスの取れた実行は、M3 Maxで1.0〜1.6%高速と測定されました。M5は中立と測定されたため、新鮮なラッパーを保持します。H3_REUSE_MPS_COMMAND=0または1は自動選択をオーバーライドします。結果はバイト単位で同一です。M5では、サービングEulerサンプラーは、パッチパックされたF32ラテントとキャッシュされたBF16速度をMetalバッファに保持します。選択された各デノイザーリフレッシュは、次のものがエンコードされる前に完了し、MPSGraphのバックプレッシャーを回避しながら、すべての中間ラテント/速度の読み取りと再パッキングを削除します。2つのウォーム8回実行A/Bシーケンスは、バイト単位で同一の最終ラテントで小さな0.1%および0.3%のゲインを測定しました。このパスは、ビデオラテント要素あたり約16バイトの一時的なホスト状態(768p形状で約136 MB)も節約します。M3および古いGPUはデフォルトでCPUサンプラーを保持します。H3_CPU_SAMPLER=1はM5でそれを復元します。H3_GPU_SAMPLER=1はGPU状態パスを明示的に選択し、H3_GPU_SAMPLER_WINDOW=0はより遅い無制限エンコードアヘッド診断を有効にします。
チェックポイントレイアウトとメディアパイプライン
リリースされたチェックポイントは、アテンションヘッドごとにインターリーブされたDiT QKV行を格納します。ネイティブMetalは、融合されたQK正規化/RoPEカーネルでそのレイアウトを直接消費し、チェックポイントトランスポーズと追加のRAMを不要にします。以前の同一性解釈が、ノイズの多い診断出力の原因でした。
公開生成パスは、ストリーム化されたネイティブBigVGAN/AudioVAEで結合オーディオラテントをデコードし、同期されたH.264と32 kHzステレオAACを書き込みます。ネイティブ波形は、修正されたMLXオラクルと相対L2 6.94e-5で一致します。--first-frame、--last-frame、およびそれらの組み合わせは、リリースされたビジュアルVAEエンコーダー、Qwen3-VLビジョンタワーと3層マルチモーダルプレゼンテーション、0.999条件拡張、およびネイティブDiTの固定条件行を使用します。最初の画像はターゲットキャンバスに引き伸ばされます。最後の画像はアスペクトカバーでスケーリングされ、中央でクロップされ、参照実装と一致します。--ref-imageは、個別のRef2VAトランスフォーマーを選択し、順序付けられた<Picture N>プレゼンテーションを保持し、リリースされたダウンオンリーアスペクト保存参照キャンバスを使用します。--ref-silent-videoはさらに、境界付き24 fpsデコード、ビジュアルVAEの因果的ceil(T/4)圧縮、2フレームQwenサンプリング、およびタイムスタンプ付き<Video N>プレゼンテーションを実行します。--ref-videoは埋め込みサウンドトラックを保持し、--ref-video-audio VIDEO AUDIOは明示的な置き換えを提供し、--ref-audioは順序付けられたスタンドアロンクリップを追加します。参照オーディオは32 kHzステレオF32としてデコードされ、ネイティブAudioVAE事後平均パスでエンコードされ、0.999クリーンラテントと0.001シードノイズとして混合され、オーディオ条件タイムステップ1.0にピン留めされ、ビジュアル参照と同じロータリータイムラインで幅32行としてパックされます。オーディオ入力は2〜15秒で、最大3つが受け入れられ、合計デコード期間は15秒に制限され、スタンドアロンオーディオ参照は画像またはビデオ参照と組み合わせる必要があります。
ネイティブオーディオエンコーダーは、実際の2秒ステレオフィクスチャで相対L2 3.59e-6で修正されたMLXオラクルと一致します。修正は重要です。元のMLXリシェイプは左右サンプルをインターリーブしましたが、公式のPyTorch/SGLangパスは完全なステレオチャンネルをバッチ次元に折りたたみます。128 GB M5 Maxでは、クリーンなエンドツーエンド画像+オーディオおよび埋め込みビデオ+オーディオレンダリングはそれぞれ74.58秒と76.99秒で完了し、ピーク物理フットプリントは約40.1 GBで、スワップはゼロでした。
プロファイリングと診断パス
--profileは、各Metalバックエンドフェーズを個別に報告します。壁時間、CPU側コマンドエンコーディング、完全なコミットからフェンスまでの待機時間、ルートコマンドGPUタイムスタンプ、ピークライブテンソルストレージ、累積割り当て、およびディスパッチカウント。待機測定は完全なコマンドターンアラウンドです。ルートGPUタイムスタンプのみでは、MPSGraphによって内部的にスケジュールされた子バッファが省略される可能性があり、そのようにラベル付けされます。
DiT高速パスは、各BF16 fc1 -> SwiGLU -> fc2ブロックを1つのキャッシュされたグラフとして評価し、別々のグラフ境界と永続的な中間テンソルを回避します。H3_DISABLE_FUSED_MLP=1を設定すると、数値診断のためにクローズリファレンス操作境界を保持します。
サポートされているM5 Metal 4 TensorOpsハードウェアでは、ネイティブint8 MLPエンジンがデフォルトです。動的にアクティベーションを量子化し、出力チャネルごとの重みスケールを使用し、デリケートなFC2入力に1,024チャネルごとに1つのスケールを与えます。選択されたFC2カーネルは、32 KiBのスレッドグループタイルを繰り返しスピルするのではなく、プライベート協調フラグメントにスケールされた部分積を保持します。固定の50レイヤー、19トランジション512x512レンダリングは、M5 MaxでBF16 MPSで36.30秒、int8で25.80秒を測定しました。開始、中間、および最終のデコードされたフレームは、同じ被写体、コンポジション、およびモーションを維持しました。小さなエッジと毛皮のディテールは異なる場合があります。現在の診断実装は、A/B診断が要求した場合にのみ、BF16とint8 MLPの両方の重みを保持します。通常のint8ロードは、量子化が完了した後に各ブロックのBF16 FC1/FC2バッファを解放し、BF16パスの36.4 GiBから測定されたピークテンソルストレージを25.9 GiBに削減します。実行時重み量子化は、起動時間を追加します。
最も高速なM5パスは、DiT QKV射影を量子化し、既存のQ/K正規化およびRoPEカーネルの前に、Q/K/Vタイルを直接ヘッドメジャーアテンションレイアウトで書き込みます。固定の50レイヤー、19トランジション512x512レンダリングでは、デノイズが25.80秒から19.32秒にさらに削減されました。サンプリングされた開始、中間、および最終フレームは、雪の中を歩く詳細なキツネと一貫性を保ちました。量子化されたアテンションは、フレーミングと細かいディテールを変更する可能性があります。クローズリファレンスBF16射影には、--use-slower-bf16-qkvを使用してください。通常のint8ロードは、量子化後に冗長なBF16 QKV重みを解放します。
そのint8パスでは、SDPAは結果をネイティブ[head,row,dimension]順序で残します。特殊化された256スレッドカーネルは、各H3行を射影の行メジャーint8バッファに直接収集および量子化します。これにより、中間的なフル幅BF16トランスポーズが不要になり、出力バイトは変更されません。サーマル制御されたクロス実行は、512および864で完全なフォワードを約0.2〜1.2%改善します。--use-slower-row-major-attention-outputを使用して、明示的なBF16行メジャーSDPA出力と通常の量子化器を復元します。
M5パスでは、QKVおよびMLPアクティベーション量子化を、前のゲート付きAdaLNカーネルに折りたたみます。これにより、50レイヤーフォワードあたり99のスタンドアロン量子化器ディスパッチが不要になり、以前の出力バイトを維持しながら、クロス512/864測定を約0.3〜0.6%改善します。--use-slower-unfused-int8-inputsを使用して、スタンドアロン量子化器を復元します。
融合ゲート付きAdaLNパスは、フル5,376幅H3行をBF16x4ベクトルとしてロードし、int8x4を書き込みます。元の各スレッドRMSシーケンスを計算する前に、丸められた値をローカルにステージングするため、削減ツリーとすべての出力バイトは変更されません。クロス測定では、さらに約0.1〜0.5%が節約されます。既存の--use-slower-unfused-int8-inputsオプションは、ポータブルスカラーおよびスタンドアロン量子化器フォールバックを復元します。
Q/K RMS正規化とRoPEは、int8 QKV射影タイル内でも実行されます。融合エピローグはバイト単位で同一であり、クロスM5測定で512および864で完全なフォワードを2.1〜3.2%、および1.0〜1.8%改善します。--use-slower-unfused-qkv-ropeを使用して、別個のQ/Kカーネルを復元します。
そのエピローグは、BF16x4ロードとストアを使用して、4つの隣接するQ/K次元をワークアイテムごとに処理します。要素ごとの算術演算とBF16丸め順序は変更されていませんが、クロスクールステート測定では、両方のサイズで完全なフォワードが約0.4〜1.0%改善されます。同じ--use-slower-unfused-qkv-ropeオプションは、スカラーのスタンドアロンパスを復元します。
最大2,048行まで、正確なRMSループはBF16x4ロードとそれに続く4つの明示的な順序付けられたFMAを使用します。これはすべての出力ビットを保持し、512クラスのフォワードをさらに0.5〜0.6%改善します。より大きな形状では、2つのフォームがそこでタイする場合、スカラーロードが維持されます。--use-slower-scalar-qkv-rmsを使用して、スカラーロードを強制します。
int8アテンション出力射影は、協調フラグメント要素ごとに再読み取りする代わりに、1 KiBのスレッドグループメモリに128行と列のスケールをキャッシュします。2,048行を超える場合、融合QKVカーネルは同じアイデアを使用し、その後、逆RMS値をリサイクルするためにそのストレージをリサイクルします。より小さなQKV形状では、2つのフォームがそこでタイするため、直接ロードが維持されます。両方ともバイト単位で同一であり、選択された場所で完全なフォワードを約0.2〜0.7%改善します。--use-slower-uncached-int8-scalesを使用して、直接デバイススケールロードを復元します。
最大2,048行のシーケンスの場合、H3アテンション出力射影は、その7,168x5,376形状をTensorOpsカーネルにコンパイルします。結果はバイト単位で同一であり、クロスされた完全な512フォワード測定で約0.2〜0.8%節約されます。より大きなシーケンスでは、専門化がそこで後退するため、動的形状カーネルが維持されます。--use-slower-uncached-int8-scalesは、一般的な動的、直接スケールロード実装を復元します。
FC1も、コンパイル時に5,376幅のH3特殊化されたTensorOpsループを使用します。これは汎用ループとバイト単位で同一であり、クロスされた完全なフォワードで約0.1〜0.4%節約されます。--use-slower-dynamic-fc1-kを使用して、実行時バウンドループを復元します。
./h3 --profile -d ./MiniMax-H3 \
-p "A red fox walks through fresh snow."
--width 512 --height 512 --frames 22 --steps 20 \
--layers 50 --reuse 1 -o outputs/fox-int8.mp4
数値比較のために、ポータブルなクローズリファレンスMPS/BF16 MLPパスを強制するには、--use-slower-bf16-mlpを使用してください。古いMetalハードウェアは、必要なネイティブTensorOpsカーネルが利用できない場合に、自動的にそのパスを選択します。FC2アクティベーション量子化の場合、最大2,048行のシーケンスは、正確な128スレッド削減を使用します。各スレッドは、グループ最大値を計算しながら8つのBF16入力値を保持し、int8値をエミットする際に2番目のデバイスメモリ読み取りを回避します。クロスM5測定では、完全な512フォワードで約0.2〜0.8%改善され、出力バイトは変更されません。より大きなシーケンスは、測定された256スレッドカーネルを維持します。--use-slower-grouped-quantizerは、A/B比較のためにすべてのサイズで後者を強制します。
ネイティブベースラインは、元のFL2VA/およびRef2VA/チェックポイントツリーを対象としています。モデルフェーズは個別にロードおよび解放されるため、33Bトランスフォーマー、Qwenエンコーダー、およびデコーダーがユニファイドメモリに共存する必要はありません。