科学と神々株式会社アドベントカレンダー 2025
LLM量子化 Day 21: プログレス表示
「待つ」体験をデザインする
大規模モデルの量子化は時間がかかります。その間、ユーザーは不安になります：
- 「本当に動いているのか？」
- 「あとどれくらいかかるのか？」
- 「フリーズしていないか？」
プログレス表示は、この不安を解消し、「待つ」体験を改善します。
Richライブラリの活用
llm-quantizeは、Richライブラリを使用してリッチなターミナルUIを実現しています。
Richの特徴
- カラフルなテキスト出力
- プログレスバー
- テーブル表示
- マークダウンレンダリング
- 自動的なターミナル幅対応
プログレスバーの設計
Quantizing to GGUF Q4_K_M...
Layer 15/32 [████████████████ ] 47% ETA: 2:30
↑ ↑ ↑ ↑
| | | └── 残り時間の推定
| | └── 進捗率
| └── 視覚的な進捗
└── 現在の処理内容
プログレスバーは、以下の情報を伝えます：
- 現在何をしているか: Layer 15/32
- どれだけ進んだか: 47%
- あとどれくらいか: ETA 2:30
- 動いているか: バーのアニメーション
冗長性レベル（Verbosity）
ユーザーによって、欲しい情報量は異なります：
Quiet モード
$ llm-quantize --verbosity quiet quantize model gguf -q Q4_K_M
# 最小限の出力、エラーのみ表示
バッチ処理や大量のログを見たくない場合に。
Normal モード（デフォルト）
$ llm-quantize quantize model gguf -q Q4_K_M
Starting quantization...
[████████████████████████████████] 100%
✓ Complete: model-Q4_K_M.gguf (4.0 GB)
通常の使用に適した情報量。
Verbose モード
$ llm-quantize --verbosity verbose quantize model gguf -q Q4_K_M
Loading model: meta-llama/Llama-2-7b-hf
Architecture: LlamaForCausalLM
Parameters: 7,000,000,000
Quantizing to GGUF Q4_K_M (group_size=128)
Layer 1/32 [████████████████████████████████] 100%
Layer 2/32 [████████████████████████████████] 100%
...
Validating output...
✓ Complete: model-Q4_K_M.gguf (4.0 GB)
Compression ratio: 72%
詳細な進捗を確認したい場合に。
Debug モード
$ llm-quantize --verbosity debug quantize model gguf -q Q4_K_M
[DEBUG] Config: {"target_format": "gguf", "quantization_level": "Q4_K_M", ...}
[DEBUG] Loading tokenizer...
[DEBUG] Tokenizer loaded in 0.5s
[DEBUG] Loading model weights...
[DEBUG] Layer 0: 256MB, dtype=float16
...
トラブルシューティング用の詳細ログ。
適切なログレベルの選択
情報の種類 Quiet Normal Verbose Debug
─────────────────────────────────────────────────────
致命的エラー ✓ ✓ ✓ ✓
警告 ✓ ✓ ✓ ✓
完了メッセージ ✓ ✓ ✓
進捗バー ✓ ✓ ✓
詳細ステップ ✓ ✓
内部状態 ✓
ProgressReporterクラス
llm-quantizeでは、ProgressReporterクラスがすべての進捗表示を担当します：
ProgressReporter
├── start(total, description) # 新しい進捗を開始
├── update(advance, description) # 進捗を更新
├── complete(message) # 完了メッセージ
├── log_info(message) # 情報ログ
├── log_warning(message) # 警告ログ
├── log_error(message) # エラーログ
└── log_debug(message) # デバッグログ
スピナーの活用
進捗率が計算できない処理には、スピナーを使います：
Loading model... ⠋
↑ 回転アニメーション
「動いている」ことは伝わりますが、「あとどれくらい」は不明な場合に使います。
時間推定の精度
ETAの計算は難しい問題です：
単純な推定:
ETA = 経過時間 × (残りレイヤー / 完了レイヤー)
問題:
├── 各レイヤーの処理時間が異なる
├── システム負荷が変動する
└── I/O待ちで大きくぶれる
llm-quantizeでは、最近N個のレイヤーの平均処理時間を使って、より正確なETAを計算しています。
メモリ使用量の表示
大規模モデルでは、メモリ使用量も重要な情報です：
Layer 15/32 [████████████] 47% Memory: 12.5GB / 16GB
メモリが上限に近づいていることがわかれば、ユーザーは対策を取れます。
エラー時の表示
エラーが発生した場合も、適切にフィードバックします：
Layer 15/32 [████████████] 47%
✗ Error: Out of memory at layer 15
Suggestion:
- Reduce batch size with --batch-size 1
- Use a smaller model
- Free up system memory
単にエラーを表示するだけでなく、解決策も提示します。
Tips: プログレス表示のコツ
1. 嘘をつかない
# 悪い例: 99%で長時間止まる
[████████████████████████████████████] 99% ← 最後の1%が10分
# 良い例: 正確な進捗
Layer 31/32 [████████████████████████████████████████] 97%
最後のレイヤーが重いなら、正直にそれを示す。
2. 適度な更新頻度
# 悪い例: 更新が多すぎる
# 毎ミリ秒更新 → ターミナルがちらつく
# 良い例: 人間が認識できる頻度
# 100ms〜500ms間隔で更新
3. 重要な情報を最後に
✓ Quantization complete!
Output: ./model-Q4_K_M.gguf
Size: 4.0 GB (72% compression)
Time: 15 minutes
完了時のサマリーは、コピペしやすい形式で。
4. カラーは意味を持って使う
緑: 成功 ✓
黄: 警告 ⚠
赤: エラー ✗
青: 情報
色に意味を持たせることで、一目で状況がわかります。
5. 非対話環境への配慮
# パイプやファイルリダイレクト時はシンプルに
llm-quantize quantize model gguf -q Q4_K_M > log.txt
# プログレスバーのエスケープシーケンスは出力しない
次回予告
Day 22では「エラーハンドリング」として、予期しない状況に対処する設計について解説します。
プログレス表示は「機能」ではなく「体験」です。技術的には不要でも、ユーザーの安心感と信頼を得るために欠かせません。