目次 / トラブルシュート

トラブルシュート

つまずきやすい所を、起きやすい順にまとめました。多くは llama.cpp 周りです。

画像を渡した瞬間にクラッシュする(0xC0000409 など)

原因はほぼ --jinja の付け忘れです。 llama.cpp は画像トークン処理にチャットテンプレートが必要で、無いと即クラッシュします。

• managed モード:アプリが自動で付けます。これでも落ちるならビルドが環境に合っていない可能性(下の GPU 項目)。
• connect モード(自分で起動):起動コマンドに --jinja を必ず付ける。

llama-server -m model.gguf --mmproj mmproj-F16.gguf --jinja

Blackwell(RTX 50 系)で固まる / 落ちる

新しい GPU 世代(sm_120)はビルドの相性があります。

• CUDA 12.4 ビルドを使う(本 PoC で動作確認)。
• CUDA 13.x は不可(MMQ でクラッシュ)。
• Vulkan は不安定(モデルは載るが推論で固まる)。
• 確実さ優先なら CPU ビルド(遅いが堅実)。

→ llama.cpp の準備(Windows)。cudart-… を一緒に展開し忘れていないかも確認。

遅い / VRAM が足りない

• 31B は 16GB GPU に載りきりません。共有メモリにあふれて 1 枚あたり 2 分超になることがあります。速度優先なら 12B に。
• managed では Ollama を停止(ollama ps が空)。同じ GPU の VRAM を奪い合います。
• GPU を使うなら ngl を大きく(全層なら 99 等)。CPU のみなら速度は割り切る。
• 細かさ(image-max-tokens)を下げると速くなります。

目安は 速度の目安 へ。

接続できない(connect モード)

• llama-server が起動しているか、URL とポートが合っているか(既定 http://127.0.0.1:8080)。
• ブラウザで http://127.0.0.1:8080/health を開いて応答があるか。
• 別 PC の場合、起動時に --host 0.0.0.0 を付けたか、ファイアウォールで弾かれていないか。
• 設定の「接続テスト / 状態」で確認。

起動直後にターミナルへ赤いエラー(ECONNREFUSED)

多くは正常です。 開発時(npm run dev)、サーバーが立ち上がるまでの数秒だけ画面側が接続を試みて出ることがあります。両方そろえば消えます。

Node のエラー / SQLite の警告

• Node.js 24 以上が必要です(node:sqlite を使用)。node -v で確認。
• 起動時の SQLite ExperimentalWarning は無害です(無視して OK)。
• 依存で詰まったら npm ci(配布)/ npm install(開発)をやり直す。

読み取りが甘い / 細部を間違える

• トリミングで背景を切り、キャラを大きく送る(コツ)。
• image-max-tokens を上げる(細部が読める代わりに重くなる)。
• より大きいモデル(31B)に替える(遅くなる)。
• 出てきたタグは手で直せます。誤認は編集で補正を。

画像が扱えない / mmproj 関連のエラー

• mmproj を指定し忘れていないか(画像にはモデル本体 + mmproj の 2 つが要る)。
• サイズの対応が合っているか(12B 本体には 12B 用 mmproj)。同じリポジトリのものを使うと確実。
• Ollama の非 QAT 版の projector は読めないことがある → Hugging Face の mmproj-F16.gguf を使う(詳細)。