llama.cpp量子化でimatrixの効果を測る設計

先に結論

imatrixの効果は、量子化後fileが小さくなったかだけでは判定できません。llama.cpp b10447、同じHugging Face source revision、同じ高精度GGUF、同じcalibration data、同じquant typeを固定し、imatrixなし／ありを二つの経路へ分けます。そのうえでfile size、peak RAM、変換時間、prompt処理・decode速度、perplexityまたは固定task品質を別々に記録します。実測していないため、特定の方式を最良とは結論しません。

確認日時: 2026年8月20日（Asia/Tokyo）
対象版: llama.cpp b10447（commit 22b8e31）。量子化README、imatrix README、convert_hf_to_gguf.pyをb10447へ固定して照合しました。
検証区分: 公式資料に基づく机上調査・実験計画です。変換、imatrix生成、推論、perplexity、速度、memoryの実測は行っていません。
適用外: source revisionが不明なGGUF、calibration dataと評価dataを混ぜた比較、元から量子化済みfileの再量子化、hardwareをまたいだ速度の一般化。

固定する対象と変数

最初に「何を変えないか」を実験台帳へ書きます。変換と量子化は別stageなので、高精度GGUFを共通入力にします。sourceから二つの量子化経路を作り、片方だけにimatrixを渡します。

項目	固定または記録する値	理由
source	repository、revision、architecture、tokenizer、license	モデル差と変換差を混ぜない
高精度入力	F16／BF16 GGUFのhashとmetadata	量子化前の同じ基準を使う
imatrix生成	calibration dataとhash、--chunk／--chunks、--parse-special、GPU offload	重要度の計算条件を固定する
量子化	Q4_K_Mなどのtype、thread数、--imatrix以外のoption	量子化条件の差をimatrix有無だけにする
推論評価	hardware、backend、context、thread、GPU offload、prompt set	速度・memoryと品質の測定条件を揃える
品質評価	calibration dataとは分離したperplexity dataと固定task	calibration dataへの過適合を隠さない

公式imatrix READMEでは、modelとtext datasetを入力にimportance matrixを計算し、--imatrixで量子化へ利用します。--chunkは先頭からskipするchunk位置、--chunksは処理する最大chunk数です。--parse-special、GPU offload、perplexity計算の有無もimatrix生成条件になるため、defaultを暗黙に済ませず記録します。一方、b10447のllama-quantizeは末尾のnthreadsで量子化thread数を受け取り、imatrix生成や推論で使う-nglを量子化optionとしては扱いません。

比較手順と観測方法

各runは別directoryに出力し、前のfileを上書きしません。以下は構文の骨格であり、実行例のmodel名・data・thread・GPU設定は対象hardwareに合わせて固定してください。

# 共通入力: model-bf16.gguf / calibration-data.txt
./build/bin/llama-imatrix \
  -m model-bf16.gguf \
  -f calibration-data.txt \
  -o imatrix.gguf \
  -ngl 99

# baseline: imatrixなし、量子化thread数は8
./build/bin/llama-quantize \
  model-bf16.gguf \
  model-q4km-no-imatrix.gguf \
  Q4_K_M \
  8

# treatment: imatrixあり、ほかはbaselineと同じ
./build/bin/llama-quantize \
  --imatrix imatrix.gguf \
  model-bf16.gguf \
  model-q4km-imatrix.gguf \
  Q4_K_M \
  8

この制作環境ではbinaryを用意していないため、コマンド、model、GPU offload、結果は未実行です。b10447の--helpと固定版READMEで、build時点の引数名・出力順・対応quant typeを先に照合します。-ngl 99は公式imatrix READMEのGPU offload例であり、全hardwareで成功する保証値ではありません。利用できないbackendでは値を外すか実機に合わせ、比較する全runで同じ設定を使います。実験では次の順に観測します。

1. 再現性: command、commit、環境、入力hash、data hash、開始・終了時刻を保存する。
2. 資源: 同じOS計測方法で入力・出力file size、processのpeak RAM、disk使用量、量子化時間を測る。imatrix生成時間は量子化時間と分ける。
3. 推論: 同じhardware、backend、model、context、prompt setでprompt processingとdecodeを分け、warm-upと測定回数も固定する。
4. 品質: calibration dataとは分離したperplexity dataまたは固定taskを使い、入力・採点規則・出力差を保存する。

結果の読み方とトレードオフ

imatrixありのfileが同じsizeでも、品質が上がる可能性と速度が変わらない可能性は両立します。逆に品質指標が改善しても、calibration dataが実運用の入力分布から離れていれば、その改善を本番へ一般化できません。数値を一つの順位にまとめず、次のように判断します。

• 容量が最優先: 量子化typeと高精度入力からの容量を確認し、imatrixのために増える補助fileと作業diskも含める。
• 品質が最優先: 評価taskの再現性、prompt長、言語、出力採点方法を固定し、単一promptの印象で決めない。
• 速度が最優先: prompt処理とdecode、load時間、推論時のGPU offload、threadを分け、別hardwareの数字を混ぜない。
• 再現性が最優先: 同じ高精度GGUFから再実行できるようにし、量子化済みGGUFからのrequantizationを別実験として隔離する。

公式quantize READMEは、すでに量子化されたtensorを再量子化するoptionに品質低下の警告を付けています。再量子化とimatrixの効果を同じ「imatrixあり」の結果として扱うと、原因を切り分けられません。

未検証範囲と採用基準

この時点で未検証なのは、具体的なmodel familyごとの品質差、calibration dataの量と分布の最適値、Apple Silicon・CUDA・CPU間の速度差、multimodal projector、個別license、長文context、実運用trafficです。公式quantize READMEの容量表も特定model familyの見積もり例であり、本番値ではありません。

採用するなら、まずsourceと高精度GGUFを固定し、baselineを先に保存します。imatrixありの結果が評価dataで改善しても、別のholdout task、memory、速度、再実行差を確認できない限り、全ユーザー向けの既定量子化へ昇格させません。初めて変換する場合は入門記事の二段階手順から始めます。

参考資料

• llama.cpp b10447公式 quantize README（量子化option、thread引数、imatrix、requantization警告を2026年8月20日に確認）
• llama.cpp b10447公式 imatrix README（入力data、chunk、perplexity、GPU offloadを2026年8月20日に確認）
• llama.cpp b10447公式 convert_hf_to_gguf.py（対応output typeと変換条件を2026年8月20日に確認）
• llama.cpp b10447 release（2026年8月15日公開、2026年8月20日に確認）