Hugging FaceモデルをGGUFへ変換して量子化する

先に結論

Hugging Faceのcheckpointをllama.cppで使うときは、いきなり小さな量子化fileへ変換するのではなく、まずF16またはBF16の高精度GGUFを作り、そこからQ4_K_Mなどへ量子化します。途中の高精度GGUFを残せば、量子化前後のload確認と再作成の基準を分けられます。この記事は公式文書に基づく再現手順で、変換・推論・速度・品質の実行結果は含みません。

確認日時: 2026年8月20日（Asia/Tokyo）
対象版: llama.cpp b10447（commit 22b8e31）。build、量子化、imatrix、変換引数はb10447へ固定した公式文書とsourceを照合しました。
検証区分: 公式資料から作った机上調査・再現手順です。この制作環境ではPython依存関係、model download、build、変換、量子化、loadを実行していません。
適用外: 対応architectureが確認できないcheckpoint、licenseやtokenizerを特定できないartifact、multimodal projectorを含む構成、再量子化後の品質保証。

変換前に確認すること

GGUFはllama.cppが読むmodel file形式です。量子化はweightの表現精度を下げて容量を小さくする処理で、常に品質や速度が改善する処理ではありません。先に次の条件を固定します。

• checkpoint: 開発元のHugging Face repository、revision、対応architectureを確認する。
• tokenizer: modelと同じsource revisionのtokenizerを使う。tokenizerが不明なGGUFは成功判定を急がない。
• license: 元modelのlicense、利用制限、gated repositoryの条件を読む。
• toolchain: Git、CMake、C/C++ compiler、Python 3を用意する。GPU backendを使う場合は対象hardware向けの公式build手順も確認する。
• 作業領域: source、変換途中の高精度GGUF、量子化後GGUFを同時に置くdiskと、source modelを読み込むRAMを確保する。

b10447時点の公式quantize READMEのLlama 3.1容量表では、8Bのoriginal sizeが32.1 GB、Q4_K_Mが4.9 GBです。これは必要な中間fileとRAMを見積もるための資料上の例であり、別modelの必要量へそのまま一般化できません。量子化後のfileだけでなく、sourceと変換途中のGGUFを同時に置く容量を先に確保してください。

最短手順：buildして高精度GGUFを作り、量子化する

llama.cppのsourceをb10447へ固定し、公式quantize READMEが例示する公開modelを使った形です。実際に使う前にmodel cardとlicenseを確認し、gated modelの認証情報をshell履歴へ直書きしないでください。

git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
git checkout --detach b10447

cmake -B build
cmake --build build --config Release

python3 -m pip install -r requirements.txt
python3 -m pip install -U transformers

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

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

公式READMEは変換と量子化を二段階として説明し、変換前にPython requirementsの導入を求めています。b10447の例にあるGemma 4はTransformers 5を必要とする一方、互換性のため標準requirementsはTransformers 4を導入するため、公式注記どおりTransformersも更新しています。別modelではmodel cardと変換時の依存条件に合わせ、導入したpackage versionを記録してください。--outtype autoを使う選択肢もありますが、記事の再現条件を残す場合はf16またはbf16を明示します。Windowsやmulti-config generatorでは実行fileの場所が異なるため、build結果とllama-quantize --helpを確認してください。

成功確認と失敗時の戻し方

最初の成功は「品質が高い」ことではなく、変換したfileと量子化後fileの両方が対象版のloaderで読め、model metadataと選んだ量子化typeがログに現れることです。変換前後のfile名、sha256、実行したcommit、Python package versionを記録し、量子化前のGGUFを消さずに残します。

./build/bin/llama-cli --version

./build/bin/llama-cli -m ./gemma-4-E2B-it-bf16.gguf \
  -p "日本語で短く自己紹介してください。" \
  -n 16

./build/bin/llama-cli -m ./gemma-4-E2B-it-Q4_K_M.gguf \
  -p "日本語で短く自己紹介してください。" \
  -n 64

このコマンドはload確認の例示であり、この制作環境では動かしていません。生成文の良し悪しを1 promptで品質判定せず、まず両fileのload成否を分けます。llama-cliの名前やbuild directoryが異なる場合は、b10447のbuild結果に合わせます。loadに失敗したら、次の順で戻ります。

1. file path、全shard、disk容量、sha256を確認する。
2. 量子化後だけでなく、元のBF16 GGUFを同じloaderで読む。
3. BF16も読めなければ、checkpointの対応architecture、tokenizer、Python依存関係、変換時の最初のエラーへ戻る。
4. BF16は読めてQ4_K_Mだけ失敗するなら、量子化引数、対象版、再量子化の有無を確認し、別の量子化方式へ勝手に置き換えない。

すでに量子化されたGGUFを、もう一度量子化するrequantizationは、公式READMEでも16-bitまたは32-bitからの量子化より品質を大きく損なう場合があると注意されています。再作成できるなら、元checkpointから高精度GGUFを作り直して比較します。

imatrixを試す前に分けること

calibration dataからimportance matrix（重みの量子化で重要度を考慮するためのデータ）を作り、--imatrixで量子化へ渡す方法があります。これは品質改善を自動で保証するスイッチではありません。data、量子化type、量子化thread数、imatrix生成時のGPU offload、評価時のbackendとpromptを固定し、imatrixなし／ありを別条件として比べます。詳しい評価設計は玄人向けの検証記事で整理しています。

参考資料

• llama.cpp b10447公式 build guide（CPU buildのCMake手順を2026年8月20日に確認）
• llama.cpp b10447公式 quantize README（変換・依存導入・容量例・requantization警告を2026年8月20日に確認）
• llama.cpp b10447公式 imatrix README（calibration dataと--imatrixを2026年8月20日に確認）
• llama.cpp b10447公式 convert_hf_to_gguf.py（出力typeと変換引数を2026年8月20日に確認）
• llama.cpp b10447 release（2026年8月15日公開、2026年8月20日に確認）