科学と神々株式会社アドベントカレンダー 2025
LLM量子化 Day 22: エラーハンドリング
エラーは必ず起きる
ソフトウェア開発において、「エラーが起きないように」設計するのは不可能です。代わりに、「エラーが起きたときに適切に対処できる」設計を目指します。
LLM量子化で起こりうるエラー：
入力関連:
├── モデルパスが存在しない
├── モデル形式が不正
├── 必要なファイルが欠落
└── 認証が必要（HuggingFace）
リソース関連:
├── メモリ不足（RAM/VRAM）
├── ディスク容量不足
└── GPU利用不可
処理関連:
├── 量子化アルゴリズムの失敗
├── 外部ツール（llama.cpp）のエラー
├── ネットワークエラー
└── チェックポイント破損
出力関連:
├── 書き込み権限なし
├── 出力ファイル破損
└── 検証失敗
エラーの分類と対処
エラーは、「回復可能か」と「ユーザーの責任か」で分類できます：
回復可能
↑
一時的な │ 設定で
ネットワーク │ 解決可能
エラー │
←────────────────┼────────────────→ ユーザー責任
内部の │ モデルが
バグ │ 見つからない
│
↓
回復不可能
ユーザー責任 × 回復可能: 明確なガイダンスを提供
ユーザー責任 × 回復不可能: 原因と対策を説明
システム責任 × 回復可能: 自動リトライ
システム責任 × 回復不可能: デバッグ情報を提供
エラーメッセージの設計
良いエラーメッセージには3つの要素があります：
1. 何が起きたか（What）
Error: Model not found
2. なぜ起きたか（Why）
Error: Model not found
The path '/path/to/model' does not exist.
3. どうすればいいか（How）
Error: Model not found
The path '/path/to/model' does not exist.
Suggestions:
- Check if the path is correct
- If using HuggingFace ID, run 'huggingface-cli login' first
- Ensure you have read permissions for the directory
例外の階層設計
llm-quantizeでは、エラーの種類に応じた例外クラスを定義しています：
QuantizationError (基底クラス)
├── ModelNotFoundError
│ └── 終了コード: 3
├── AuthenticationError
│ └── 終了コード: 4
├── OutOfMemoryError
│ └── 終了コード: 5
├── ValidationError
│ └── 終了コード: 6
├── CheckpointError
│ └── 終了コード: 7
└── ConversionError
└── 終了コード: 1
各例外は、適切な終了コードと紐づいています。
グレースフルデグラデーション
完全な失敗ではなく、機能を制限しながら続行する設計も重要です：
例: llama.cppが見つからない場合
llama.cppあり:
└── 完全なk-quant量子化（高品質）
llama.cppなし:
├── 警告: "llama.cpp not found. Using fallback mode."
└── 基本的な量子化（品質は劣るが動作する）
ユーザーに選択肢を残すことで、「何もできない」状況を回避します。
リトライ戦略
一時的なエラーには、自動リトライが有効です：
ネットワークエラー:
├── 1回目失敗: 1秒待ってリトライ
├── 2回目失敗: 2秒待ってリトライ
├── 3回目失敗: 4秒待ってリトライ
└── 4回目失敗: エラーとして報告
指数バックオフにより、サーバー負荷も軽減
ロギングとデバッグ情報
エラー発生時のデバッグを容易にするため、十分な情報を記録します：
通常モード:
Error: Quantization failed at layer 15
デバッグモード（--verbosity debug）:
[DEBUG] Processing layer 15/32
[DEBUG] Layer size: 256MB
[DEBUG] Available memory: 1.2GB
[ERROR] Quantization failed at layer 15
[DEBUG] Stack trace:
File "quantizers/gguf.py", line 123, in quantize_layer
result = self._quantize_weights(weights)
File "quantizers/gguf.py", line 156, in _quantize_weights
raise OutOfMemoryError("Insufficient memory for quantization")
[DEBUG] Memory dump: RSS=15.2GB, VRAM=7.8GB
エラーからの回復
チェックポイント機能と組み合わせることで、エラーからの回復が可能です：
通常の流れ:
Layer 1 → Layer 2 → ... → Layer 15 → エラー発生！
│
▼
チェックポイント保存済み
│
▼
問題を解決（メモリ確保など）
│
▼
同じコマンドで再実行
│
▼
Layer 15から再開
ユーザーへのフィードバック
エラー発生時のCLI出力例：
$ llm-quantize quantize large-model gguf -q Q4_K_M
Loading model...
Quantizing to GGUF Q4_K_M...
Layer 1/80 [████████████████████████████████] 100%
...
Layer 15/80 [████████████ ] 47%
✗ Error: Out of memory at layer 15
What happened:
The system ran out of memory while processing layer 15.
Required: ~18GB, Available: ~12GB
How to fix:
1. Close other applications to free memory
2. Try a smaller model
3. Use 8-bit quantization instead of 4-bit
Your progress has been saved. Run the same command to resume from layer 15.
Tips: エラーハンドリングのコツ
1. 早期に失敗する（Fail Fast）
# 悪い例: 30分処理した後に権限エラー
Processing for 30 minutes...
Error: Cannot write to output directory
# 良い例: 開始前にチェック
Checking output directory... Error: No write permission
2. ユーザーの言葉で説明する
# 悪い例（技術者向け）
CUDA error: out of memory (allocation failed)
# 良い例（ユーザー向け）
Error: GPU memory is full
Your GPU has 8GB, but this model needs 12GB.
Try using CPU mode with --device cpu
3. 次のアクションを明示する
# 悪い例: 何をすればいいかわからない
Error: Authentication required
# 良い例: 具体的な手順
Error: HuggingFace authentication required
Run: huggingface-cli login
Then try again.
4. ログは構造化する
# 悪い例: パースしにくい
ERROR 2024-12-22 10:15:30 Something went wrong with the model
# 良い例: 構造化
{"level": "error", "time": "2024-12-22T10:15:30Z",
"message": "Quantization failed", "layer": 15, "reason": "OOM"}
5. テストで例外パスも確認
def test_handles_missing_model():
with pytest.raises(ModelNotFoundError):
quantize("nonexistent/model")
次回予告
Day 23では「テスト戦略」として、97%のカバレッジを達成するためのテスト設計について解説します。
エラーハンドリングは「後付け」ではなく「設計の一部」です。最初から考慮することで、堅牢で使いやすいソフトウェアになります。