GGUF（量子化モデル）を使う

GGUFで用意するもの・しないもの

MiniMax H3のモデルは、いくつかの部品でできています。GGUFで配られているのは重みの大きな部品だけで、残りは公式のモデルから取ります。

トークナイザーは重みではなく数MBの辞書なので、GGUFにする意味がなく、配られていません。VAEもGGUFでは配られていませんが、unslothとComfy-Orgが単体のsafetensors（映像のVAEをFP16にした小さいもの）を配っていて、H3cAppはそれも読めます。

ダウンロードウィザードで用意する（おすすめ）

1. ウィザードを開きます。最初の起動時に出る「MiniMax-H3 モデルの用意」を使います。モデル管理の「ダウンロードして追加…」からも開けます。
2. 「GGUF（量子化）と必要な部品」を選びます。「ダウンロードするもの」の切り替えで選びます。
3. 部品ごとにファイルを選びます。初期値の配布元のままなら、次の組み合わせがおすすめです。

   部品	おすすめ	小さくしたいとき
   DiT（FL2VA）	unslothのQ8_0（21.4GB、動作確認済み）	Q4_K（11.4GB）
   文章の部分	unslothのH3専用Q4_K_M（18.2GB、50層・画像の部分入り）	—
   VAE	unslothのVAE（5.9GB、動作確認済み）	—

   文章の部分の画質をいちばん確実にするなら、Qwen公式のQ8_0（34.8GB、動作確認済み）も選べます。この場合は取り込みのときに使う50層だけに切り詰めて書き出す（約27GB）ので、そのぶんの空きも必要です。画像の部分が入っていないので、mmproj（F16、1.2GB）も自動で加わります。参照画像・動画・音声を使う生成もしたいときは「Ref2VA も含める」をオンにします。
4. 保存先を決めます。「保存する場所」と「フォルダ名」が、取り込んだモデルのフォルダになります。ダウンロードしたファイルも、いったんこの中に置きます。外付けディスクを選んでも、取り込みは同じディスクの中の複製なので、容量は二重になりません。
5. 「ダウンロードして取り込む」を押します。ダウンロード、取り込み、モデル管理への登録まで自動で進みます。中断しても、次回は続きからダウンロードします。

ボタンを押す前に、ダウンロードの量、取り込みで書き出す量、保存先のディスクの空き容量が表示されます。足りないときはボタンが押せません（余裕として2GBを残します）。

配布元を変える

各部品の配布元（Hugging Faceのリポジトリ）は変えられます。

• 既知の配布元から選ぶ：配布元の欄の横のメニュー（≡）から、その部品を配っている配布元を選べます。
• 一覧を読み込む：「↓」ボタン（または欄でReturn）を押すと、その配布元の全ファイルの先頭を読み、中身を見てその部品のファイルだけを並べます。ファイル名ではなく中身で見分けるので、配布元ごとに名前の付け方が違っても正しく分かれます。一度読んだ結果は保存され、2回目からはすぐ出ます。
• カスタム：メニューの「カスタム…」で、リポジトリ名かHugging FaceのURLを入力できます。リポジトリ（https://huggingface.co/owner/name）、フォルダ（…/tree/main/vae）、1つのファイル（…/blob/main/xxx.gguf、…/resolve/main/xxx.gguf）、main以外のブランチのどれでも構いません。入力した場所は部品ごとに「カスタム」として残り、「カスタムを削除」で消せます。
• 記憶：選んだ配布元は部品ごとに記憶され、次に開いたときの初期値になります。

アプリで使えないファイルも一覧には出し、「（未対応：理由）」と添えます。選んでも選ばれません。理由は対応している形式を参照してください。

手元のGGUFを取り込む

すでにGGUFファイルを持っている場合は、モデル管理の「GGUFを取り込む…」を使います。

1. ファイルを選びます。「GGUFファイルを追加…」でファイルを、「フォルダから追加…」でフォルダごと（3階層下まで）追加します。ファイルごとに中身を調べて、DiT・文章の部分・画像の部分のどれかを表示します。DiTのFL2VAとRef2VAは中身では区別できないので、名前に ref2va を含むものをRef2VAとみなします（切り替えもできます）。足りない部品には、入手先の例と「ダウンロード…」ボタンが出ます。
2. 内容を確認します。部品ごとに使うファイルと足りないものが表示されます。同じ部品のファイルが複数あるときは、使うものを選びます。「部品の複製元」で、トークナイザー・VAE・設定をどこから取るかを選びます（モデル管理に登録したモデル、「フォルダを登録…」で選んだフォルダ、または「共通部品をダウンロード…」で取った公式の共通部品）。
3. 「取り込む」を押します。~/Library/Application Support/H3cApp/Imported/ にモデルのフォルダを作り、モデル管理に登録します。

取り込んだあと

• モデル管理の「ⓘ」で、モデルの中身（各部品の形式・大きさ、AdaLNの形、層の数、キャッシュの有無、取り込みの記録）と、このモデルでできることを確かめられます。
• M5で速く生成したいときは、詳細設定の「キャッシュを作成…」でint8キャッシュ（約19GB）を作ります。GGUFのモデルでも作れます。
• M1〜M4ではSSDストリーミングで動きます。GGUFの重みは量子化されたまま読み込んでGPUで展開するので、読み込む量が減ります。

配布元と対応している形式

既知の配布元

いずれも、ダウンロードの画面でファイルの先頭を読んだ結果に基づく分類です。どの配布元も、Q4前後の代表的なファイルで短い動画を作れることを確かめています（下の「動作を確かめた組み合わせ」）。

対応している形式

• 量子化形式：Q8_0、Q4_0、Q4_1、Q5_0、Q5_1、Q2_K〜Q6_K、F16、BF16、F32。unslothの「UD-○○_XL」のような混在も、これらだけでできていれば使えます。
• 未対応（一覧に理由付きで出ます）：IQ系（IQ4_XS、IQ3_XXSなど）やI8などを含むファイル、分割されたGGUF、safetensors形式のDiT・文章の部分（取り込めるのはGGUFだけ）、読めない数値形式（F8、int8など）のVAE、層が50に足りない文章の部分。
• AdaLNの形：DiTのGGUFには、AdaLNが「曲線形」（ComfyUIのpruned形式）と「密な形」の2種類があります。どちらも使えます。密な形はファイルが8GBほど大きくなります。
• 文章の部分：エンジンが使うのはQwen3-VL-32Bの最初の50層です。64層のものは取り込みのときに50層だけに切り詰めて書き出します。

動作を確かめた組み合わせ

既知の配布元ごとに、なるべく同じ配布元・同じ量子化のDiTと文章の部分を組み合わせて、3秒・512×512・SSDストリーミングで同じプロンプトとseedの動画を作り、映像と音声（話し声）を確かめました（2026年10月19日、Apple M5・24GB）。配布元に文章の部分がないものはunslothのQ4_K_Mを、文章の部分だけの配布元はDiTにunslothのQ4_Kを使っています。

画像の部分（mmproj）は参照画像を使う生成でしか使わないため、この確認では読み込みまでです。

ただし、Q2_KだけでできたDiT（unslothのminimax_h3_fl2va_pruned-Q2_K）は、人物が溶け、背景が格子状になり、音声がうなりになるなど、動画が大きく崩れます。ブロックの行列がすべてQ2_Kで、Q8_0との相対誤差が27.7%（Q3_Kは15.6%、Q4_Kは7.4%）あるためです。Q3_K_M以上を使ってください。H3cAppはこうしたファイルに警告を出します。Q2_Kの文章の部分は問題なく使え、「UD-Q2_K_XL」のような混在は確かめていません。

モデルの削除とディスク容量

GGUFの取り込みは、同じディスク上のファイルをAPFSの複製（クローン）で置くので、取り込み自体ではほとんど容量を使いません。その代わり、モデルどうしやダウンロードした元のファイルとデータを共有することがあります。モデル管理の「…」→「削除…」では、次のように動きます。

• 登録を外すだけの場合でも、そのモデル用の生成キャッシュ（int8キャッシュなど）はすぐに削除します（作り直せます）。
• 「モデルファイルも削除する」をオンにすると、もう一度確認してから、モデルのフォルダをゴミ箱に移します。ゴミ箱を空にすると解放される容量を表示します。ほかのモデルや元のファイルと共有している部分は、そちらで使われているので残ります。
• 最後の1つのモデルを削除するときは、ダウンロードした共通部品・GGUFと、使われていないキャッシュも削除します。

ライセンス

• MiniMax H3のモデル（公式のもの、unslothなどのGGUF）にはMiniMax H3 Community License Agreementが適用されます。要点はライセンスと利用条件にあります。
• Qwenの文章の部分・画像の部分（Qwen3-VL-32B-Instruct）にはApache License 2.0が適用されます。
• それぞれの配布元のライセンスも確認してください。ダウンロードと利用の前に各ライセンスを読み、その条件に従ってください。

仕組みとAPIの詳細は、GitHubのGGUF.ja.mdを参照してください。