冒頭：发生了什么问题

llama.cppでモデルを量子化しようとすると、以下のようなエラーに遭遇する場合があります。

Error: invalid quantization type 'Q4_0'
Error: failed to quantize model
Assertion failed: (false), function quantize, file quantize.cpp

または、モデルの変換段階で以下のエラーが発生することもあります。

Error: unknown model format 'pth' or invalid path
Error: failed to load model

環境：

OS: Ubuntu 22.04 / macOS / Windows
llama.cpp: コミットハッシュ b3000fe
対象モデル: Hugging Face HubのFP16モデル

結論：解決策

このエラーは、モデルの量子化タイプ指定の誤り、またはモデル形式の不一致によって発生します。解決策は、①サポートされている量子化タイプの確認、②正しい変換スクリプトの使用、③モデルの正しい前処理の3ステップです。

具体的な手順

ステップ1：サポートされている量子化タイプを確認する

llama.cppのバージョンによって、サポートされている量子化タイプが異なります。最新の情報を得るには、以下のコマンドを実行してください。

# llama.cppのビルド済みバイナリの場合
./llama.cpp-quantize --help

# ソースからビルドしている場合
./build/bin/llama-quantize --help

主要な量子化タイプとその特徴は次の通りです。

量子化タイプ  ビット数   推奨用途
---------   ------   ---------
Q4_0        4ビット   バランス重視（デフォルト推奨）
Q4_1        4ビット   精度重視の低容量
Q5_0        5ビット   中間的な精度
Q5_1        5ビット   高精度
Q2_K        2.96ビット 超低容量（注意が必要）
Q3_K_S      2.75ビット 極めて低容量
IQ2_S       2.5ビット  改善された2ビット量子化
IQ2_M       2.7ビット  中間的なIQ2

ステップ2：モデルを変換する（HF形式からGGUF形式へ）

Hugging Face形式のモデル（safetensorsまたはpytorch_model.bin）をGGUF形式に変換する必要があります。

# 1. llama.cppリポジトリをクローン
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp

# 2. Python依存関係をインストール
pip install -r requirements.txt

# 3. モデルを変換（例：Qwenモデル）
python3 convert-hf-to-gguf.py /path/to/your/model --outfile model.gguf

重要：変換時にモデルのアーキテクチャを自動検出できない場合があります。その場合は、以下のオプションを追加してください。

# モデルタイプを明示的に指定する場合
python3 convert-hf-to-gguf.py /path/to/your/model 
    --outfile model.gguf 
    --model-name Qwen2.5

ステップ3：量子化する

変換が完了したら、適切な量子化タイプで量子化を実行します。

# 量子化の実行
./build/bin/llama-quantize model.gguf model-quantized.gguf Q4_0

または、ビルド済みのバイナリを使用する場合：

./llama.cpp-quantize model.gguf model-quantized.gguf Q4_0

ステップ4：量子化されたモデルをテストする

量子化が完了したら、実際に動作するか確認します。

./build/bin/llama.cpp -m model-quantized.gguf -n 128 -p "Hello, world!"

補足・注意点

バージョン依存の問題

llama.cppは活発に開発されており、量子化タイプや変換プロセスが変更されることがあります。古いバージョンのドキュメントを参考にする場合は、以下の点に注意してください。

IQ2/IQ3などの新しい量子化タイプは、2024年後半のバージョンからサポートされています
convert.py（旧スクリプト）は非推奨となり、convert-hf-to-gguf.pyに統一されました

環境による違い

Linux/macOS：

# CMakeでのビルド
cmake -B build
cmake --build build --config Release

Windows（Visual Studio）：

cmake -B build -G "Visual Studio 17 2022"
cmake --build build --config Release

よくある落とし穴

モデルのパスが通っていない：相対パスではなく絶対パスを使用してください
量子化タイプを大文字で指定：「q4_0」ではなく「Q4_0」と指定してください
ディスク容量不足：変換・中間ファイル用に十分な空き容量を確保してください（元のモデルの2倍程度）
量子化による精度低下：Q2_KやQ3_Kは容量削減効果が高い一方で、perplexity（困惑度）が上昇します。用途に合わせて選択してください

損失精度の検証

量子化による精度への影響を評価するには、perplexityを比較します。

# 元モデルのperplexity
./build/bin/llama.cpp -m model.gguf --dummy -fa

# 量子化モデルのperplexity
./build/bin/llama.cpp -m model-quantized.gguf --dummy -fa

参考値として、Q4_0は通常+0.4〜+0.5程度のperplexity上昇に収まります。

【llama.cpp】GGUF量子化時の「invalid quantization type」エラーの解決法