トラブルシューティング:症状 → 原因 → 修正
ローカル推論の失敗にはパターンがある。同じ12の症状がヘルプリクエストのほぼすべてを占め、それぞれに退屈な原因と2分の修正がある。表を走査し、修正を適用し、それから数値を読んで実際に直ったことを確認する。
診断表
| 症状 | 疑われる原因 | 修正 |
|---|---|---|
出力にロールトークンが含まれる(user:、`< |
im_start | >`) |
| 即座の空の返信 | テンプレートが「終わった」会話を描画、または誤ったEOSトークン | テンプレートを修正。EOSを確認:プロンプト |
| 質問に答える代わりに質問を反復 | instructモデルではなくベースモデル | instruct/chat GGUFを使う |
| ロード中にメモリ不足 | 重み+量子化がVRAMを超過 | より小さい量子化か小さいモデル:VRAM計算 |
| 生成中にメモリ不足 | KVキャッシュが余裕を超えて成長 | 短いコンテキスト、KVキャッシュq8_0:KVキャッシュ |
| GPUがあるのに1〜3 tok/s | レイヤーがまだCPUにある | フルオフロード(n_gpu_layers):エンジンパラメータ |
| 最初のトークンが遅く、その後のストリームは速い | プリフィル律速:非常に長いプロンプト | プロンプト短縮、バッチ、より速いプリフィル:速度 |
| 終わりのない反復、フレーズループ | サンプラが緩すぎ、ペナルティオフ | temp ≤ 0.8、repeat_penalty 1.05–1.1:サンプリング |
| 韓国語出力が文字化けまたは硬い | モデルの韓国語が弱い | 多言語ファミリー(Qwen、Gemma):モデルファミリー |
| 文の途中で出力が切れる | コンテキストウィンドウ満杯かmax_tokensが低すぎ | コンテキストを刈るか出力上限を上げる |
| 良いモデルなのに不正なJSON | 自由形式サンプリング | 制約付きデコーディング:構造化出力 |
| モデルが指示を無視 | 長いプロンプトでlost in the middle | 目標を最初に、ペイロードを最後に、要求を反復:プロンプト |
| ロード時にクラッシュかコアダンプ | 破損したダウンロード | チェックサムを検証し、再ダウンロード |
原因ファーストではなく症状ファーストで読むこと。見えるものを照合し、修正を適用し、再測定する。「モデルが壊れた」報告の大半は1、2、6行目で終わる。
5分のプレフライト
本格的なデバッグの前に、事実を集める。
nvidia-smi --query-gpu=name,memory.total,memory.used --format=csv # GPU + VRAM
ls -lh model.gguf # サイズ対VRAM
llama-server --version # エンジンビルド
モデルファイルが空きVRAMより大きければ、答えは4行目で、どのフラグも救わない。memory.usedが生成中に着実に登るなら、それはリークではなくKVキャッシュ。
正常の姿
パフォーマンスをデバッグする前に、相場を知ること。7〜8B Q4_K_Mモデルのデコード速度、バッチ1。
| ハードウェア | デコードtok/s |
|---|---|
| ミドルレンジGPU(RTX 3060/4060級) | 30–60 |
| ハイエンドGPU(RTX 3090/4090級) | 100–150 |
| Apple Mシリーズ(ユニファイドメモリ) | 20–40 |
| CPUのみ(現代の8コア) | 3–8 |
2つの式が大半を説明する。
decode tok/s ≈ メモリ帯域幅 (GB/s) ÷ モデルサイズ (GB)
必要VRAM ≈ 重み + KVキャッシュ + 1–2 GBのオーバーヘッド
288 GB/sカード上の4.5 GBの7B量子化は、理論上ほぼ64 tok/sが上限。実際は45〜55を期待。表の2倍以内なら、ハードウェアはバグではない。
初回トークンまでの時間(TTFT)は短いプロンプトなら1秒未満であるべき。プロンプト長をプリフィルスループット(デコード速度の10〜100倍)で割った値とともに伸びる。10kトークンのプロンプトが最初のトークン前に20秒かかるなら、壊れているのではなくプリフィル律速。
VRAM会計:重みは問題なくロードされたのに後でOOMするなら、それは量子化ではなくKVキャッシュかコンテキスト長——KVキャッシュ。
ワークフロー:1変数ずつ交換
2つ同時に変えるとバグは隠れる。このチェーンに沿って隔離すること——モデル → エンジン → 設定 → プロンプト。
- **ベースライン。**既知の良好なモデル、既知の良好なエンジン、デフォルトフラグ。チャットは動くか?ならスタックは正常。
- モデルを交換(同じエンジン、同じフラグ)。壊れる?ならファイルかそのテンプレート。
- エンジンを交換(同じモデル)。壊れる?ならエンジンのバグかフラグ変換。
- **フラグを二分探索。**デフォルトに戻し、壊れるまで1つずつフラグを戻す。
- **描画済みプロンプトをダンプ。**出力が奇妙だが動いているとき、真実が住むのは描画されたテンプレート。
進めながらメモを取ること——「temp 0.8で動き、min_p 0.2で壊れる」は診断で、「いろいろ試したがまだ悪い」は診断ではない。
上手に助けを求めるには
良いヘルプ投稿は実験レポートである。含めること。
- モデルファイル:正確な名前、量子化、ソース(
qwen2.5-7b-instruct-q4_k_m.gguf、どのリポジトリ)。 - エンジンとバージョン:llama.cppのビルド日、Ollamaのバージョン、vLLMのリリース——エンジンは週次で変わる。
- 正確なフラグまたはAPI呼び出し:言い換えではなく、コマンドラインまたはリクエストボディ全体。
- ハードウェア:GPU + VRAM(またはMac + RAM)。レイヤーを担っているならCPUも。
- 観測された数値:tok/s、TTFT、使用VRAM、あれば正確なエラーテキスト。
- すでに試したことと、その結果何が変わったか。
コピペの骨組み。
モデル: qwen2.5-7b-instruct-q4_k_m.gguf(bartowskiリポジトリ)
エンジン: llama.cpp b4321(llama-server)
フラグ: -ngl 99 -c 8192 --temp 0.7
ハードウェア: RTX 4060 8GB / Ryzen 7 / 32GB RAM
観測: 21秒でロード、~35 tok/s、TTFT ~1.2秒、その後ctx ~6kでOOM
試行: -c 4096 → クラッシュなし。q8_0 KV → クラッシュなし
この6つの事実があれば、大半の問題は1回の返信で上の表の行に対応する。このフォーラムはまさにこの種の投稿のために存在する——実験レポートを持ってくれば、修正が手に入る。