ローカルAIが動かない原因を切り分ける
ローカルAIが動かない・遅いときは、ファイル、形式とアーキテクチャ、メモリ、実行、出力の順に原因を分けます。GGUFで「unknown model architecture」と出た場合は、PC性能を見る前に、その構造へ実行ソフトが対応しているかを確認します。
視覚図
- 1ファイル最後まで保存され、必要なファイルが揃っている？
- 2形式・構造実行ソフトはこの形式とアーキテクチャを読める？
- 3メモリモデルの読み込み中に止まっている？
- 4実行・加速読み込み後の生成だけが遅い？
- 5出力動くが、回答の内容が期待と違う？
図は装飾です。問題の所在を順に絞り込みます。テキスト同等物は下を参照してください。
図のテキスト説明
- ファイル：ダウンロードが完了しているか、分割モデルや補助ファイルが必要な構成なら揃っているかを確認します。
- 形式・構造：GGUFはファイル形式です。拡張子がGGUFでも、実行ソフトが中に記録されたモデルアーキテクチャを処理できるとは限りません。「unknown model architecture: <名前>」と出たら、まずその名前と実行ソフトの現在の対応状況を照合します。対応済みの名前なら、モデルの配布元、revision、変換、metadataも確認します。
- メモリ：ファイルと形式を認識した後、読み込みで止まる場合は重み、実行時の作業領域、KV cache、context長などの負荷を分けます。
- 実行・加速：モデルを読み込めてから遅い場合は、生成速度、CPU/GPUの分担、offload、contextを確認します。
- 出力：生成は進むのに回答が不自然な場合は、モデルの用途、入力形式、tokenizerやchat templateとの組み合わせを確認します。
押さえておく用語
- offload
- モデルの一部をGPUとCPU/RAMに分けて載せる方式。
- context
- 一度に扱える入力の長さ。長いとメモリを消費。
- モデルアーキテクチャ
- モデル内部の構造を示す名前。GGUF metadataに記録され、実行ソフト側にもその構造を処理する実装が必要です。対応状況は実行ソフトとバージョンで変わります。
注意点
- 同じ拡張子でも、モデル構造・metadata・実行ソフトの対応が一致するとは限りません。
- エラー全文、モデル名、実行ソフトとバージョンを記録してから、公式ドキュメントや配布元の情報へ進みます。
- 製品ごとの画面操作や具体的な修復手順はLocal AI Compassへ。
詳しく知りたいときは Local AI Compass へ
確認した主な情報源とこのページの範囲
- GGUF 公式仕様（general.architecture metadata） — https://github.com/ggml-org/ggml/blob/master/docs/gguf.md
- llama.cpp 公式：新しいモデルアーキテクチャの追加 — https://github.com/ggml-org/llama.cpp/blob/master/docs/development/HOWTO-add-model.md
ファイル、形式とアーキテクチャ、メモリ、実行、出力を分ける概念マップです。GGUF形式だけでruntime互換性は決まらず、architectureの対応は実行ソフトと版で変化します。具体的な製品手順はLocal AI Compassを参照してください。
詳細な手順・最新仕様は、各公式ドキュメントおよび Local AI Compass を参照してください。