GGUFへの変換と量子化は二段階：convert_hf_to_gguf.py、llama-quantize、imatrixを公式資料で確かめる

この記事は、実際に使って確かめた記録ではありません。この記事は公式の文書や論文を読んでまとめたものです。数字の比較や割り算は、公式の表から僕らが計算したものです。

先に結論

自分で量子化する価値があるのは、配布元が欲しい圧縮の種類を用意していないとき、imatrixを自分のデータで作りたいとき、あるいは仕組みを理解したいときです。単に4ビット版を使いたいだけなら、すでに誰かが作ったGGUFを使うほうが手間は少ないはずです（見立てです）。

手順は短いです。公式READMEの流れは次の三つです。

1. Hugging Faceのモデルを、BF16かF16のGGUFにする（変換）。
2. llama-quantize で、Q4_K_Mなどの形式に圧縮する。
3. 画像などを扱うモデルなら、mmproj（画像用の部品）も別に作る。

前提：用語

• GGUFは、ggmlの仕組みでモデルを動かすためのファイル形式です。ggmlの文書によると、1つのファイルで配れ、mmap（ファイルをメモリに直接割り当てる方式）での高速な読み込みに対応し、モデルを動かすのに必要な情報（設定のメタデータ）をすべて含みます。
• 量子化は、重みの精度を下げて（例：32ビットの小数から4ビットの整数へ）、ファイルを小さくする処理です。llama.cppのREADMEは、サイズが縮み、推論が速くなることがある一方、精度が落ちることがあると説明しています。
• perplexity（ppl）は、文章の予測のしやすさの指標で、低いほど良い値です。KLダイバージェンス（kld）は、元のモデルとの出力の分布のずれです。公式は、量子化による劣化をこの2つで測るとしています。
• bits/weightは、重み1つあたりの平均ビット数です。名前に「4」とあっても、実際は表のように4.89ビットなどになります。
• BF16は16ビットの小数の形式で、多くのモデルがこの形式で配られています。

手順1：Hugging Faceのモデルを、高精度のGGUFにする

公式READMEの例です。この記事では、実行していません。

python convert_hf_to_gguf.py --outfile gemma-4-E2B-it-bf16.gguf --outtype bf16 --remote google/gemma-4-E2B-it

事前に、リポジトリの requirements.txt で、Pythonの部品を入れます。READMEの補足は次のとおりです。

• 配布が16ビット形式の通常のケースでは、--outtype auto（または指定なし）でもよい。
• 手元にダウンロード済みなら、--remote を外し、フォルダを指定する。
• 互換性のため、要件ファイルはtransformers 4を入れるが、Gemma 4のようにtransformers 5が要るモデルが増えている。pip install -U transformers で更新してよい。

スクリプトのソースで確認した --outtype の選択肢は、f32・f16・bf16・q8_0・tq1_0・tq2_0・auto です。auto は「16ビット浮動小数点で最も忠実な型」と説明されています。--remote は実験的な機能で、safetensorsファイルをダウンロードせずに読む、とあります。ログイン制限のあるリポジトリには、環境変数 HF_TOKEN が要ります。

手順2：llama-quantizeで圧縮する

公式READMEの例です。この記事では、実行していません。

./build/bin/llama-quantize gemma-4-E2B-it-bf16.gguf gemma-4-E2B-it-Q4_K_M.gguf Q4_K_M

引数は「入力のGGUF、出力のGGUF、量子化の種類、（任意で）スレッド数」です。

主なオプションです（READMEとソースの --help の記述）。

見立てです。最初は、種類だけを指定した最小の形（上の例）で作り、--dry-run でサイズを先に見る、という順番が安全だと思います。

imatrix（重要度行列）を作る

imatrixは、サンプル文章（キャリブレーションデータ）をモデルに読ませて、各層の入力の大きさを記録したものです。圧縮のときに「効く重みを丁寧に、効かない重みは粗く」扱うために使われます。元のプルリクエスト（#4861）の説明は、各テンソルの列ごとの活性化の二乗の平均を重みとして、重み付きの誤差を最小にする、という考え方です。この説明は、WebFetchの要約で読んだもので、原文の確認は十分ではありません。

公式の tools/imatrix のREADMEの例です。この記事では、実行していません。

# 重要度行列を作る（99層をGPUに載せる）
./llama-imatrix -m ggml-model-f16.gguf -f calibration-data.txt -ngl 99

# それを使って Q4_K_M に圧縮する
./llama-quantize --imatrix imatrix.gguf ggml-model-f16.gguf ./ggml-model-q4_k_m.gguf q4_k_m

READMEから読み取れる点です。

• -m（モデル）と -f（サンプル文章のファイル）は必須です。
• 出力は既定で imatrix.gguf です。古い .dat 形式にもでき、変換もできます。
• --process-output は、既定で無効です。READMEは、出力の重みと単語の埋め込みには、通常はimatrixを使わないほうがよい、と書いています。
• --in-file で、複数回の結果を結合できます。
• GPUに載せる指定（-ngl）で速くなります。

サンプル文章に何を使うかの具体的な推奨は、今回読んだ範囲のREADMEにはありませんでした。READMEの例は wiki.train.raw です。

見立てです。imatrixは、サンプル文章に近い使い方で効果が出る仕組みなので、日本語で使うなら、日本語を含む文章で作ったほうがよいのではないかと思います。ただし、公式がそう書いているわけではなく、確かめてもいません。

数字を読む：種類によるサイズと速さ

見立てです。この表を見ると、「生成」の速さはファイルが小さいほど上がり、「読み込み」の速さはあまり変わらないように見えます。生成では、1トークンごとに重みを読み直すためメモリの読み出し量が効く、という一般的な説明と合いますが、公式のREADMEがその理由を述べているわけではありません。

作業に必要なメモリとディスク

公式READMEの「Memory/Disk Requirements」節は、次のように書いています。

• モデルは現状、全体をメモリに読み込むので、ディスクの保存場所と、読み込むRAMが十分に要る。
• 今のところ、メモリとディスクの必要量は同じである。

例（Llama 3.1）は、8Bが元の32.1GBから4.9GB、70Bが280.9GBから43.1GB、405Bが1,625.1GBから249.1GB（Q4_K_M）です。元のサイズは、32ビットで保存した場合に見えます（8B×4バイト）。

見立てです。32GBのMacでは、8Bの変換と量子化は余裕がありそうですが、70Bのような大きいモデルは、変換の入力が数百GBになるので、ディスクの空きを先に確かめる必要があります。

画像・音声に対応するモデル

公式READMEによると、llama.cppは既定でモデルのLLM部分だけを変換します。画像や音声を使うには、別のファイル（mmproj）を作ります。

python convert_hf_to_gguf.py --mmproj --outfile mmproj-gemma-4-E2B-it-Q8_0.gguf --outtype q8_0 --remote google/gemma-4-E2B-it

公式の説明では、これらの部品は本体より小さく、品質が出力に直接影響するので、BF16かQ8程度の高い品質で残すのが普通です。速度とメモリへの影響は、小さい形式にしても無視できる程度、とあります。

よくある失敗・つまずき

• 圧縮済みのGGUFをもう一度圧縮する：--allow-requantize が要り、品質が大きく落ちることがあります。元のBF16かF16から作り直すほうが確実です。
• 変換でエラーになる：新しいモデルで、transformersのバージョンが足りない例がREADMEに書かれています。
• mmprojを忘れる：画像を渡せません。
• サイズだけで選ぶ：表のppl差は、Llama-3-8Bでの値です。使うモデルでの差は別です。
• コマンド名の混在：READMEの最新版では、llama cli、llama serve のようにスペース区切りの形が出てきます。一方、量子化の説明には llama-quantize、llama-imatrix のようなハイフンつきの名前が残っています。手元のビルドで --help を確かめてください。

気をつけること

• この記事では、ここで紹介した変換・量子化・imatrixの作業を実行していません。作業時間、実際の品質低下、メモリの使用量は確認できていません。
• 公式READMEの表（Llama-3.1-8B）の測定環境（機種・ビルド）は、読んだ範囲に書かれていません。速度は、自分のマシンの値と同じではありません。
• READMEとソースは、2026年10月8日にmasterブランチで読みました。llama.cppは更新が非常に速く、オプション、形式の種類（Q1_0やQ2_0などの新しい名前も増えています）、コマンド名は変わることがあります。
• imatrixの元のプルリクエストの内容は、要約で読んだだけです。現在の既定値（出力ファイル名など）は、READMEのほうが新しく、プルリクエストとは違います。
• モデルごとにライセンスがあります。元のモデルの利用条件を確かめてから、変換したファイルを公開してください。個別の判断は専門家に相談してください。

出典

• quantize README（llama.cpp、ggml-org、2026年10月8日確認）
• quantize.cpp（llama.cpp、ggml-org、2026年10月8日確認）
• imatrix README（llama.cpp、ggml-org、2026年10月8日確認）
• convert_hf_to_gguf.py（llama.cpp、ggml-org、2026年10月8日確認）
• llama.cpp README（ggml-org、2026年10月8日確認）
• GGUF（ggml docs、ggml-org、2026年10月8日確認）
• Pull request 4861 imatrix（llama.cpp、ggml-org、2026年10月8日確認）

更新履歴

• 2026年10月25日 書き方を直しました。
  • 前：運営者が使っていないと読める書き方 → いま：「この記事は、実際に使って確かめた記録ではありません」。公式の資料を読んでまとめた記事で、使い心地は書いていない、という意味に直した