目次 / トラブルシュート

トラブルシュート

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

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

原因はほぼ --jinja の付け忘れです。 llama.cpp は画像トークン処理にチャットテンプレートが必要で、無いと即クラッシュします。Pixubus EX は自分で起動した llama-server につなぐ方式なので、起動コマンドに --jinja を必ず付けてください(設定画面の推奨コマンドにも入っています)。これでも落ちるならビルドが環境に合っていない可能性(下の GPU 項目)。

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 に。
• 接続先が GPU を使うなら Ollama を停止(ollama ps が空)。同じ GPU の VRAM を奪い合います。
• GPU を使うなら llama-server の起動に -ngl を大きく付ける(全層なら 99 等)。CPU のみなら速度は割り切る。
• 細かさ(--image-max-tokens)を下げると速くなります(アプリの image-max-tokens もサーバの値に合わせる)。

目安は 速度の目安 へ。

接続できない

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

リモート(RunPod)で 1 回目のジョブが「llama-server 524」で失敗する

初回だけの現象で、多くは待てば直ります。 RunPod の公開 proxy は Cloudflare 経由のため、リクエストが約 100 秒を超えると 524(タイムアウト)で切られます。初回のジョブはモデルの自動ダウンロード + ロードを伴うので、この制限を超えがちです(実測: 26B の初回で発生)。

• サーバー側ではダウンロード/ロードは続いています。 1〜2 分待って同じジョブをもう一度実行すると、ロード済みで成功します。
• 恒久対策は Tailscale 接続(公開 proxy を通らないので時間制限がありません)。→ 設定(リモートで動かす)

自動ダウンロードされたモデルはどこにある?(リモート)

リモート用 INI(hf-repo 方式)で自動ダウンロードされたモデルは、サーバーの ~/.cache/llama.cpp/ に置かれます。

LLAMA_CACHE=/workspace/llama-cache ./build/bin/llama-server --models-preset ./pixubus-ex-remote.ini --models-max 1 --jinja --no-warmup --host 0.0.0.0 --port 8080

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

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

Node のエラー / SQLite の警告

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

モデルのダウンロードが途中で失敗する

• もう一度 npm run fetch:model を実行してください。済んだ分は記録されているので続きから再開します(ゼロからやり直しにはなりません)。
• 小さな通信エラーは自動でリトライされます。何度実行しても同じ場所で止まる場合は、回線を替える(テザリング等)か、表示される手動ダウンロードの案内(Hugging Face の Files)からブラウザで落として models/<種類>/ に置いてください。
• 空き容量にも注意(実行時に必要量と空きが表示されます)。

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

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

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

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