GGUFを重点的に理解する

GGUFとは：ローカル実行のための全部入りファイル

GGUFは、それ以前に使われていたGGML、GGMF、GGJTという形式の後継です。古い形式は設定値を「型のない数値の列」として並べていたため、新しい項目を足すたびに互換性が壊れていました。GGUFは設定を「キーと値」の組で持つようにして、項目を足しても古いファイルが読めなくならないようにしています。

仕様書には、設計の目標が次のように挙げられています。

• 1ファイルで完結 — 外部のファイルなしで配布・読み込みできる。
• 拡張できる — 互換性を壊さずに新しい情報を追加できる。
• mmap対応 — ファイルをメモリに直接対応づけて、高速に読み込める。
• 使いやすい — 外部ライブラリなしの少ないコードで読み書きできる。

llama.cppやggml、GGUFを作ってきたggml.aiのチームは、2026年2月にHugging Faceへ合流しました（第3章）。llama.cppはMITライセンスのオープンソースとして開発が続いています。

ファイルの中身をのぞく

GGUFファイルは、先頭から次の順番で並んでいます。

flowchart TD
  A["ヘッダー
GGUF の4文字・版数 3
テンソル数・メタデータ数"] --> B["メタデータ
キーと値の組"]
  B --> C["テンソル情報
名前・形・型・位置"]
  C --> D["パディング
境界をそろえる"]
  D --> E["テンソルデータ
重みの本体"]

ファイルの最初の4バイトは文字どおり GGUF（0x47 0x47 0x55 0x46）で、続いて形式の版数が入ります。現在の版は3で、ビッグエンディアンへの対応が加わった版です。テンソルデータは決まったバイト境界（general.alignment、指定がなければ32バイト）にそろえて置かれるので、mmapで効率よく読めます。

メタデータ：設定・トークナイザ・テンプレート

メタデータは「general.architecture = llama」のような、ドットで区切った名前のキーと、その値の組です。値には整数、小数、真偽値、文字列、配列が使えます。代表的なキーを並べます。

これがGGUFの「全部入り」の正体です。safetensorsでは config.json や tokenizer.json に分かれていた情報（第4章）が、ここにまとめて入っています。

テンソル情報

テンソルごとに、名前、次元、型（どの量子化か）、データ部分の中での位置が記録されます。名前には標準の付け方があり、token_embd.weight（埋め込み）、blk.0.attn_q.weight（0番目のブロックのアテンションのQ）、blk.0.ffn_down.weight（フィードフォワード層）、output.weight（出力層）のようになります。テンソルごとに型を変えられるのがポイントで、これが後で出てくる _M や _L の正体につながります。

pip install gguf
gguf-dump Qwen3.5-0.8B-Q4_0.gguf | head -40

量子化の名前を読む

GGUFの中のテンソルは、たいてい量子化されています。量子化とは、重みを少ないビット数で近似して小さくすることです（基本は第10章）。名前は大きく4つの系統に分かれます。

imatrix（重要度行列）

imatrix（importance matrix）は、「どの重みが出力に強く効いているか」を、実際の文章をモデルに流して測ったデータです。量子化のときにこれを使うと、重要な重みの誤差を優先して小さくできます。llama-imatrix でサンプルの文章から作り、llama-quantize --imatrix に渡します。量子化したGGUFの配布ページに「imatrix」と書かれていたら、この方法で作られたものです。

実測値で比べる：サイズと品質

llama.cppの量子化ツールの説明書には、Llama 3.1 8Bを各形式に量子化した実測値が載っています。ここから代表的なものを抜き出しました（ppl増加は別のモデル Llama 3 8B での値で、ツール内の説明文から）。

ppl（パープレキシティ）は「次の単語をどれだけ迷うか」の指標で、増加が小さいほど元に近い。—は資料に記載なし。

表から読み取れる傾向は3つです。第一に、Q8_0〜Q5_K_Mでは劣化がごくわずか。第二に、Q4_K_Mあたりから劣化が目に見え始めるものの、サイズは16bitの3分の1以下。第三に、3bitを切ると劣化が急に大きくなります。名前の「4」や「2」は目安で、実際のbit/重みはそれより大きいことにも注目してください（スケールなどの付加情報があるため）。

下の計算機で、パラメータ数と量子化の種類から重みのサイズを見積もってみましょう。

どれを選べばいい？

迷ったら Q4_K_M から始めるのが定番です。llama.cppで -hf オプションを使ってHugging Faceから取得するときも、量子化を指定しなければQ4_K_Mが既定で選ばれます2026年10月時点。

• メモリに余裕がある → Q5_K_M、Q6_K、Q8_0 と上げていく。
• どうしても入らない → IQ4_XS、Q3_K_M、さらに IQ3/IQ2 系（imatrix付き）へ。小さなモデルの高ビットより、大きなモデルの低ビットの方が良いこともあるので試す価値あり。
• 重みのほかに、KVキャッシュ（第15章）と作業用のメモリが必要。重みがメモリの9割を超えるなら厳しいと考える。

ファイル名の読み方

GGUFの仕様書には、ファイル名の命名規則もあります。

[補助ファイル-]ベース名-サイズ[-微調整][-版][-エンコーディング][-種類][-分割].gguf

Mixtral-8x7B-v0.1-KQ2.gguf
Grok-100B-v1.0-Q4_0-00003-of-00009.gguf
mmproj-Qwen2-VL-7B-v1.0-F16.gguf

サイズの 8x7B は「7B規模の専門家（エキスパート）が8つ」というMoEの書き方です。エンコーディングの位置に量子化の種類が入ります。ただし実際の配布ファイルは、この規則どおりでないことも多いです。たとえば ggml-org/Qwen3.5-0.8B-GGUF のファイルは Qwen3.5-0.8B-Q4_0.gguf で、版の部分がありません。Unslothのリポジトリでよく見る UD-Q4_K_XL の UD- は、同社が層ごとに型を調整した独自の量子化（Unsloth Dynamic）を示す接頭辞で、GGUFの仕様で決まった名前ではありません。

手元のファイル名を下に貼り付けて、どこが何を表しているか確かめてみましょう。

分割ファイル、mmproj、mtp

分割ファイル

巨大なモデルのGGUFは、…-00001-of-00003.gguf のように分割されて配布されます。llama.cppでは、最初のファイル（00001）を指定するだけで、同じフォルダにある残りのファイルも自動で読み込まれます。分割や結合は llama-gguf-split で行えます。

# 2GBごとに分割
llama-gguf-split --split --split-max-size 2G model.gguf model-split
# 1つに結合（最初のファイルを指定）
llama-gguf-split --merge model-split-00001-of-00005.gguf model-merged.gguf

mmproj：画像や音声を読むための別ファイル

画像や音声を入力できるモデル（第29章）のGGUFには、mmproj-…gguf というファイルが付いてきます。mmprojは「multimedia projector」の略で、画像・音声のエンコーダーと、その出力をLLMが読める形に変換する層が入っています。本体のGGUFだけでも文章のやりとりはできますが、画像を読ませるにはこのファイルも必要です。

mmprojは本体よりずっと小さく、品質が入力の質に直結するため、BF16やQ8_0のような高い精度のまま使うのが普通です。llama.cppで -hf を使うと、リポジトリにmmprojがあれば自動でダウンロードされます。手動なら --mmproj で指定します。

最近は、投機的デコーディング（第16章）用の下書きモジュールを別ファイルにした mtp-（Multi-Token Prediction）という補助ファイルも、命名規則に加わっています2026年10月時点。

GGUFを作る・動かす

Hugging Faceのモデル（safetensors）からGGUFを作るのは2段階です。

flowchart TD
  A["Hugging Face のモデル
safetensors"] --> B["convert_hf_to_gguf.py
BF16 の GGUF に変換"]
  B --> C["llama-quantize
Q4_K_M などに量子化"]
  D["llama-imatrix
重要度を測る"] -.-> C
  C --> E["llama.cpp などで実行"]

# 1. 変換（llama.cpp リポジトリのスクリプト）
python convert_hf_to_gguf.py --outfile gemma-4-E2B-it-bf16.gguf \
  --outtype bf16 --remote google/gemma-4-E2B-it
# 2. 量子化
llama-quantize gemma-4-E2B-it-bf16.gguf gemma-4-E2B-it-Q4_K_M.gguf Q4_K_M

自分のPCで変換したくなければ、Hugging FaceのSpace「GGUF-my-repo」でブラウザから変換・量子化することもできます。

できあがったGGUFを動かすコマンドは、ツールによってこうなります。llama.cppは最近 llama cli / llama serve という1つのコマンドにまとめた入口を用意しています（従来の llama-cli、llama-server も含め、くわしくは第7章）2026年10月時点。

# llama.cpp: Hugging Face から取得して対話（量子化は :Q4_K_M のように指定可）
llama cli -hf ggml-org/Qwen3.5-0.8B-GGUF

# Ollama: Hugging Face の GGUF リポジトリを直接指定
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:IQ3_M