GGUF を読む — Q4_K_M の正体

GGUF は「1 ファイルで自己完結する推論用の器」

GGUF は llama.cpp が使うモデル保存形式です。LM Studio は公式ドキュメントで「Mac / Windows / Linux 上で llama.cpp を使って LLM を動かす」と明言していて、Ollama も量子化を llama-quantize に投げる作りなので、3 者は同じファイルを読みます。公式仕様は冒頭で「GGML および GGML ベースの実行系で推論するためのモデル保存形式」「高速なロードと保存、そして読みやすさのために設計されたバイナリ形式」と定義しています。学習は PyTorch 等で行い、推論のために GGUF へ変換するという一方向の位置づけです。

中身は 4 つの領域が順番に並んだだけの単純な構造です。ヘッダ（マジック GGUF・バージョン・テンソル数・メタデータ件数）、型付きの key-value であるメタデータ、テンソル（= 多次元の数値配列）1 件ごとの目録、そして重みの生バイト列。

旧形式（GGML → GGMF → GGJT）との決定的な違いは、仕様書が明言するとおり「ハイパーパラメータを型なしの値の並びではなく key-value 構造にした」ことです。これによってキーを足しても既存ファイルが壊れなくなり、「このモデルは何アーキテクチャなのか」がファイル自身から分かるようになりました。未対応のモデルに対して賢く失敗できるのはこの変更のおかげです。

もう 1 つの設計目標が mmap（= ファイルをメモリ空間に貼り付け、実際に触ったページだけを OS が読み込む仕組み）への対応です。テンソルデータは量子化ブロックの生バイト列がそのまま連続配置されていて、各テンソルの開始位置は必ずアラインメントの倍数に揃っています（general.alignment というキーが無ければ 32 と仮定する、と仕様が定めています）。だからロードは「ファイルを mmap して、目録の offset を指すポインタを設定する」だけで終わり、展開もコピーも要りません。

本ガイドの調査で ggml-org/gemma-3-1b-it-GGUF の gemma-3-1b-it-Q4_K_M.gguf を実際に解析すると、メタデータ 38 件・テンソル 340 件で、テンソルデータの開始位置は 6,533,120 バイトでした。そこへ末尾テンソルの offset 799,520,512 とサイズ 4,608 を足すと 806,058,240 バイトになり、実ファイルサイズと完全に一致します。ヘッダ側だけで 6.5 MB もあるのは、262,144 語の語彙とスコア・トークン種別の 3 配列、さらに chat template まで同居しているからです。これが「単一ファイル自己完結」の実体です。

名前を 4 つに分解する

Q4_K_M は 4 つのパートの連結です。Q は Quantized（量子化済み）、4 は 1 重みあたりの基本ビット数、_K は方式のファミリ、_M はサイズ配分の等級。ここで最も重要なのは、llama.cpp には 2 つの階層があるという点です。

Q4_K は ggml のデータ型（enum ggml_type）で、テンソル 1 個の符号化方式を表します。一方 Q4_K_M はファイルタイプ（enum llama_ftype）で、モデル全体の配合レシピ、つまり「だいたい Q4_K だが一部のテンソルは Q5_K や Q6_K にする」という指示です。_S / _M / _L はレシピ名にしか付きません。だから llama-quantize の --output-tensor-type に渡せるのは q5_k であって q5_k_m ではありません。

接尾辞の意味は、llama.cpp の実装と導入時の PR に明記されています。特に _0 と _1 は、K-quants より前の「legacy 系」で復元式そのものを表していました。

ブロックを開ける — 4bit が 4.5 bpw になる理由

ここが本章の山場です。新しい道具は要りません。使うのは第 3 章の 2 つだけ — ブロックごとに scale を持たせると誤差が閉じ込められるという話と、追加ビット = scale のビット数 ÷ ブロックサイズ という割り算です。第 3 章では素朴な 4bit 型（Q4_0）で「FP16 の scale を 32 要素ごとに持って +0.5 bpw」まで確かめました。Q4_K がやるのは、その scale 自体を 6bit に縮めて本数を増やすという一手だけです。以下はその一手を、バイト単位で追っているにすぎません。

Q4_K のブロック構造体 block_q4_K は、ggml-common.h の static_assert でバイト数が厳密に固定されています。中身は 3 種類です。

• 量子値: 256 要素分の 4bit 値（qs、128 バイト）
• サブブロックのスケールと最小値: 8 個のサブブロック × (6bit + 6bit) を詰めた 12 バイト（定数 K_SCALE_SIZE の正体）
• スーパーブロック共通の d と dmin: FP16 × 2 = 4 バイト

「スーパーブロック」は 256 要素をまとめた大きい単位、「サブブロック」はその中を 32 要素ずつに割った小さい単位です。ビットの家計簿にすると次のようになります。

256 × 4 bit（量子値）+ 8 × (6 + 6) bit（サブスケール）+ 16 bit × 2（d と dmin）= 1024 + 96 + 32 = 1152 bit

bpw（1 重みあたりのビット数）は「ブロック 1 個のバイト数 × 8 ÷ ブロックの要素数」で出ます。block_q4_K は 128 + 12 + 4 = 144 バイトなので、計算例として当てはめると (144 × 8) ÷ 256 = 1152 ÷ 256 = 4.5。0.5 ビットの超過分は、まるごとスケール情報です。そしてこの 0.5 ビットが 4bit 量子化の精度を支えています。

復元の式も見ておきます。言葉で言えば「4bit の量子値を、そのサブブロック専用のスケールで伸ばし、そのサブブロック専用の最小値の分だけ下へずらす。ただしスケールと最小値それ自体が 6bit に量子化されているので、スーパーブロック共通の FP16 で伸縮し直す」。dequantize_row_q4_K の実装はこうなっています。

w = (d × sc) × q − (dmin × m)

q は 0〜15 の 4bit 量子値、sc と m は 0〜63 の 6bit 値、d と dmin はスーパーブロック共通の FP16 です。計算例として d = 0.000143、dmin = 0.000873、sc = 51、m = 57、q = 11 を入れると、実効スケールは 0.000143 × 51 = 0.007293、実効オフセットは 0.000873 × 57 = 0.049761 なので、w = 0.007293 × 11 − 0.049761 = 0.0305 になります（値は説明のために置いたものです）。

なぜこの二段構えなのか。32 個ずつの小さな窓に区切れば、その窓の中の重みの値域は狭く、狭い値域を 16 段階に割れば相対誤差は小さくなります。しかし窓を小さくするほどスケールの本数が増えてビットを食う。そこでスケール自体を 6bit に量子化し、そのスケールのスケールを 256 個で 1 個だけ FP16 で持つことで折り合いをつけている、というのが K-quants の発明です。

タイプ別の bpw と、モデル全体の実効値

同じ算術をすべての型に適用した表が次です。バイト数は ggml-common.h の static_assert から、bpw はそこからの計算値です。Q2_K / Q3_K / Q4_K / Q6_K については Hugging Face Hub の GGUF ドキュメント記載値と一致することを確認しました（2026-08 時点）。

ここで注意したいのは、この bpw は「その型だけで全部を詰めたとき」の値だという点です。実際のファイルは配合レシピなので、モデル全体の実効 bpw はずれます。tools/quantize/README.md の Llama-3.1-8B 実測表がその差を示しています。

bits/weight とサイズは Llama-3.1-8B の実測、ΔPPL は llama-quantize のヘルプに載っている Llama-3-8B での F16 比 perplexity（= 次の 1 トークンを当てるとき実質何択で迷っていたか。低いほど良い）増分です（測り方と読み方は第 9 章で扱います）。なお第 9 章が引く tools/perplexity/README.md のスコアボードは別の測定なので、同じ型でも下 1 桁が違います（Q4_K_M はこの表で +0.1754、第 9 章で +0.1755）。Q4_K_M が 4.5 ではなく 4.8944 なのは、一部テンソルが上位型に昇格しているから。逆に IQ1_S は型単体で 1.5625 bpw ですが、モデル全体では 2.0042 bpw あります。埋め込み層と出力層が高ビットで残っているからです。

S / M / L は「どこを厚くするか」の違い

Q4_K_S と Q4_K_M はどちらも基本が Q4_K です。違うのは昇格の範囲だけ。llama-quant.cpp の判定は次のラムダに集約されています。

auto use_more_bits = [](int i_layer, int n_layers) -> bool {
    return i_layer < n_layers/8 || i_layer >= 7*n_layers/8 || (i_layer - n_layers/8)%3 == 2;
};

読み下すと「先頭 1/8 の層、末尾 1/8 の層、そして残りは 3 層ごとに 1 層」。Q4_K_M はこの条件に当たる層の attn_v（Attention の Value 射影）と ffn_down（FFN の出力側）を Q6_K に上げます。attn_qkv（Q・K・V を 1 本のテンソルにまとめたアーキ用）だけは層の条件と無関係で、該当するテンソルが全層いっせいに Q5_K になります。一方 Q4_K_S は attn_v の先頭 4 層と ffn_down の先頭 1/8 層だけを Q5_K にして、あとは全部 Q4_K です。

なぜ全部同じビット数にしないのか。答えは、テンソルはサイズが桁違いで、量子化誤差への感度にも大きな差があるからです。小さくて敏感なテンソルを厚くしてもファイルはほとんど太らないのに精度は大きく戻る。実装のコメント自身が attn_v 系を「量子化に対してより敏感」と書いています。70B モデルには「8 ヘッドが attn_v を共有していて attn_q の 1/8 のサイズしかないので、ビットを増やしてもサイズ増はごくわずか」という理由付きの特例もあります。

さらに output.weight（最後の語彙射影）はレシピが何ビットであっても既定で Q6_K です。導入 PR が「これ以降すべての量子化バリアントは output.weight に 6bit を使う。これで例えば 7B の Q4_0 の perplexity が約 0.03 下がる」と根拠を示しています。ただし例外が 2 つあり、IQ1 / IQ2 台の超低ビットレシピでは Q5_K、行の長さが 256 で割り切れないモデルや Falcon 系では Q8_0 になります。token_embd.weight は逆に巨大なので、超低ビットレシピでは Q2_K や IQ3_S に落として節約します。

ただし実測では、昇格した 13 層のうち attn_v が Q6_K ではなく Q8_0 になっていました。理由は形です。gemma-3-1b の隠れ次元は 1152 で、これは 256（K 系のブロックサイズ）で割り切れません。行の長さがブロックサイズの倍数でないテンソルはその型で保存できないので、llama.cpp は Q4_K → Q5_0、Q6_K → Q8_0 と型を落とします。attn_v の行の長さは 1152 なので落ち、ffn_down は 6912（= 27 × 256）なので予定どおり Q6_K のまま残りました。結果として 340 テンソル中、Q4_K は 39 個（attn_output 26 + ffn_down 13）しかなく、Q5_0 が 117 個、量子化されない正規化層（norm）の F32 が 157 個、Q8_0 が 14 個（昇格した attn_v 13 + token_embd 1）、Q6_K が 13 個（昇格した ffn_down）という構成でした。同じ「Q4_K_M」でもモデルの形によって中身は変わり、bpw の表から逆算したサイズと合わないことがあります。

i-quants と imatrix — 2bit 台を成立させる装置

IQ 系（i-quants）は K-quants とは発想が違います。K-quants が「値をスケールで割って丸める」のに対し、i-quants はあらかじめ用意した数百個の代表パターン（コードブック）の中から一番近いものを選び、その番号を記録する方式です。身近な対比で言えば、ここまでは「目盛りの上のどこか」を書き留めていたのに対し、i-quants は「よく出る並びに番号を振った一覧の、何番目か」を書き留めます。2bit 台では 1 要素につき 4 通りしか書けないので、要素を 1 個ずつ表すのを諦めて数個まとめて 1 つの番号にするしかない、というのが動機です。以下の格子やビット詰めの話は、その番号をどう安く作るかの工夫です。導入 PR は QuIP#（= 格子状のコードブックで重みを符号化する量子化手法の論文）から 2 つのアイデアを借りたと述べています。8 個ずつのグループで符号の数を偶数に強制して 8 個の符号を 7 ビットに詰めること、そして E8 格子（= 8 次元空間に規則正しく並んだ点の集合）から選んだ 256 点をコードブックにすること。これで「重み 32 個（= ブロック 1 個）あたりちょうど 64 ビット」を達成し、スーパーブロック 1 個の FP16 スケール分（16 ÷ 256 = 0.0625 bpw）を足して IQ2_XXS の 2.0625 bpw になります。

もう 1 つの IQ 系のやり方が非線形マッピングです。IQ4_NL のルックアップテーブルは −127, −104, −83, −65, −49, −35, −22, −10, 1, 13, 25, 38, 53, 69, 89, 113 の 16 値で、0 の近くは刻みが細かく（−10 → 1 → 13）、端は粗い（−127 → −104）。第 2 章の NF4 とまったく同じ発想で、第 4 章の理由 1（重みが 0 のまわりに集まっている）を目盛りの側から利用しています。違うのは作り方で、NF4 が正規分布の分位点から導いた値なのに対し、こちらは実装が測って決めた 16 値です。同じサイズの Q4_0 より明確に良く、Q4_K_S とほぼ同等という PPL 実測が PR に載っています。

そして i-quants の前提が imatrix（importance matrix / 重要度行列）です。何を測っているのか。理想的には学習の勾配から「この重みがどれだけ重要か」を求めたいのですが、llama.cpp には学習機能がなく、行列もモデルと同じくらい巨大になります。導入 PR は数式を追って、非対角成分が小さいので対角成分だけで十分、つまり「キャリブレーション文章（= 校正のために流す、ごく普通のテキスト）を流したときに、その入力チャンネル（= 行列積でその重みに掛かってくる入力ベクトルの成分）が平均してどれくらい強く発火したか（二乗活性化の平均）」を並べたベクトル 1 本で近似できると示しました。量子化の際はこれが誤差最小化の重み付けに直接掛かります。

作る手順は llama-imatrix で測って llama-quantize --imatrix に渡す 2 段で、実際のコマンドとキャリブレーションデータの選び方は第 10 章で扱います。この章で押さえたいのは、どのタイプでそれが要るのかという線引きです。

IQ1_S / IQ1_M / IQ2_XXS / IQ2_XS / IQ2_S / IQ3_XXS は imatrix が必須で、無いと llama.cpp はそもそも実行を拒否します。

ERROR: this quantization requires an importance matrix!
       - offending tensor: ...
       - target type: ...

一方 K-quants はコード中のコメントが「一般則として K 系は imatrix を必要としない。例外は Q2_K_S ファイルの一部としての Q2_K テンソルだけ」と明言しています。つまり Q4_K_M は imatrix なしで作って構いません。低ビットになるほど、どの重みを犠牲にするかの判断が結果を左右するので、その判断材料として imatrix が要る、という構図です。

何を選び、ファイル名をどう読むか

最初の答えは Q4_K_M です。これは好みではなく、公式ツールの既定が 3 つとも一致しているという事実に基づきます。llama.cpp の -hf オプションのヘルプは「quant は省略可、大文字小文字を区別せず、既定は Q4_K_M」と書いています。Ollama で Hugging Face のモデルを直接実行する手順も、Hugging Face 側の公式ドキュメントが「既定では Q4_K_M がリポジトリ内にあればそれを使う」と書いています。LM Studio については「マシンが許すなら 4bit 以上を選べ」が公式の唯一の明示的な推奨です。

そこから動かす方向も上の表で決まります。余裕があれば Q5_K_M（ΔPPL 0.0569 / 5.33 GiB）→ Q6_K（ΔPPL 0.0217 / 6.14 GiB）。どうしても入らなければ Q4_K_S（ΔPPL 0.2689 / 4.36 GiB）→ IQ4_XS（4.17 GiB。こちらは公式の ΔPPL 値が無い）→ Q3_K_M（ΔPPL 0.6569 / 3.74 GiB）。Q2_K 以下は ΔPPL が 3.5199 に跳ねる領域で、ここは imatrix 前提の IQ 系の出番になります。自分のハードから形式を選ぶ話は第 7 章、必要メモリの計算は第 8 章、品質劣化の測り方は第 9 章で扱います。

ファイル名を読む練習

仕様のファイル名規約は [<Sidecar>]<BaseName><SizeLabel><FineTune><Version><Encoding><Type><Shard>.gguf で、要素は - 区切りです。実際に読んでみます。

gemma-3-1b-it-Q4_K_M.gguf
Grok-100B-v1.0-Q4_0-00003-of-00009.gguf
mmproj-Qwen2-VL-7B-v1.0-F16.gguf

1 行目は BaseName が gemma-3、SizeLabel が 1b、FineTune が it（instruction tuned）、Encoding が Q4_K_M。2 行目の末尾 00003-of-00009 は Shard（分割番号）で、5 桁ゼロ埋め・開始は 00001 と決まっています。llama.cpp は 1 個目のファイルを指定すれば残りを同フォルダから自動で見つけるので、多くの場合そもそも結合は不要です。3 行目の先頭 mmproj は Sidecar で、マルチモーダルモデルの画像投影器。本体とは別ファイルで、通常 F16 や Q8_0 のような高品質形式のまま保たれます。

なお仕様書自身が「現存する gguf ファイル名は多様なので、完全にパースできることは意図していない」と断っています。Hugging Face 上の大半は Version を省くので、この規約の正規表現には通りません。ファイル名から確実に読めるのは Encoding（Q4_K_M の部分）と Shard くらいだと思っておくのが安全です。中身を正確に知りたいときは pip install gguf で入る gguf_dump.py でメタデータを覗くか、Hugging Face のモデルページの GGUF ビューアでテンソルの名前・形・精度を見ます。

つまずきポイント

理解度チェック

まとめ

• GGUF は「型付き key-value のメタデータ + テンソルの生バイト列」の単一ファイル。オフセットが揃っているので mmap でそのまま読める。トークナイザまで同居するのでヘッダは数 MB になる
• Q4_K_M = Q（量子化）/ 4（基本ビット数）/ K（K-quants）/ M（配分の等級）。Q4_K はテンソル単位のデータ型、Q4_K_M はモデル全体のレシピという 2 階層がある
• block_q4_K は 144 バイトで 256 要素。1024（量子値）+ 96（サブスケール）+ 32（d/dmin）= 1152 ビット、÷ 256 = 4.5 bpw。超過の 0.5 ビットがすべてスケール情報
• _S / _M / _L は精度の段階ではなく配分の段階。use_more_bits（先頭 1/8 層・末尾 1/8 層・3 層ごとに 1 層）が _M の実体で、output.weight は既定で Q6_K（超低ビットの IQ 系や、行の長さが 256 で割り切れないモデルは例外）
• IQ 系のうち 2〜3bit 台はコードブック方式で、IQ1_S / IQ1_M / IQ2 系 / IQ3_XXS は imatrix 必須。K-quants は原則不要
• 迷ったら Q4_K_M。llama.cpp -hf の既定・Ollama の既定・LM Studio の推奨が一致している

次章では、GGUF 以外の形式（MLX / GPTQ / AWQ / FP8）と並べて、自分のハードと目的からどれを選ぶべきかを整理します。

参考リンク

• GGUF 公式仕様（ggml-org/ggml docs/gguf.md）
• llama.cpp tools/quantize/README.md（型一覧・実測 bits/weight 表）
• llama.cpp tools/imatrix/README.md（llama-imatrix の使い方）
• ggml ggml-common.h（block_q4_K 等のブロック構造体）
• PR #1684 — k-quants の導入
• PR #4773 — i-quants（IQ2_XXS）の導入とコードブックの設計
• PR #4861 — Importance Matrix calculation
• PR #5590 — IQ4_NL（非線形 4bit）
• Hugging Face Hub — GGUF と量子化タイプ一覧
• Hugging Face Hub — Ollama で GGUF を実行（既定 Q4_K_M）
• Hugging Face Hub — LM Studio で GGUF を実行（「4bit 以上を選べ」）