GGUFが読み込めない・unsupportedになるときの原因と対処法

GGUFをLM Studio、Ollama、llama.cppへ読み込んだときにunsupportedやfailed to load modelが出ても、すぐにGPU不足と判断するのは早い。読み込みエラーには、ファイル破損、分割ファイル不足、未対応アーキテクチャ、古いランタイムなど複数の原因がある。

切り分けは、ファイル → モデルアーキテクチャとランタイム → チャットテンプレート → マルチモーダル補助ファイル → メモリの順で進めると分かりやすい。

1. エラー全文と使用条件を残す

最初に、エラーメッセージを省略せず保存する。同時に次の情報も確認しておく。

• GGUFの配布元とリポジトリ
• モデル名とリビジョン
• 正確なファイル名と量子化
• 使用しているLM Studio・Ollama・llama.cppのバージョン
• 読み込み方法や実行コマンド
• マルチモーダルなら使ったprojector/mmproj

unsupportedという一語だけでは原因を特定できない。どの処理段階で、何というエラーが出たかが重要になる。

2. ファイル破損と分割不足を確認する

次に、GGUFそのものが完全かを見る。

ダウンロードが途中で終わっていたり、分割GGUFの一部だけを取得していたりすると、ランタイム側の設定が正しくても読み込めない。

配布元がチェックサムを公開している場合は、手元のファイルと照合できる。Windowsでは次のようにSHA-256を確認できる。

Get-FileHash C:/models/model.gguf -Algorithm SHA256

分割GGUFでは、必要なpartがすべて同じ場所にそろっているか、配布時のファイル名を変更していないかも確認する。

拡張子を.binなどへ変えてもファイル形式やモデル構造は変わらない。名前を変更して読み込ませる方法は、破損や未対応アーキテクチャの解決にはならない。

3. モデルアーキテクチャがランタイムに対応しているか見る

GGUFは共通のファイル形式だが、GGUFを読めるランタイムがすべてのモデルアーキテクチャへ同時に対応するわけではない。

特に新しいモデルでは、llama.cppへ対応が追加された後、それを取り込むLM Studioなどのランタイム更新が必要になる場合がある。OllamaでもGGUF importの経路があることと、任意のアーキテクチャを扱えることは別だ。

確認するのは次の三点になる。

1. GGUFが何のモデルアーキテクチャか
2. 使用中のランタイムがそのアーキテクチャへ対応しているか
3. その対応が自分のバージョンに含まれているか

「最新版では対応した」という情報があっても、手元の固定リリースへ同じ変更が入っているとは限らない。

GGUF対応と個別モデル対応の違いは、GGUFはLM Studio・Ollama・llama.cppでどこまで互換？で詳しく確認できる。

4. 読み込めるのに会話がおかしいならテンプレートを見る

モデルファイル自体は読み込めるのに、返答が崩れる、役割指定が効かない、特殊トークンがそのまま出るといった場合は、ファイル読み込みよりチャットテンプレートの問題を疑う。

確認するのは、モデル配布元が案内するテンプレートと、ランタイムが実際に使用しているテンプレートだ。

別モデル用のテンプレートを名前が似ているという理由で流用すると、会話形式、thinking、tool callingなどが合わない可能性がある。まずモデル本来のテンプレートで短い会話を確認し、その後にシステムプロンプトやツール機能を追加する方がよい。

5. 画像入力だけ失敗するならmmprojを確認する

テキスト生成は成功するのに画像入力だけ失敗する場合は、モデル本体のGGUFとは別にprojectorやmmprojが必要な経路かを確認する。

projectorは別モデル用のものを流用せず、本体と対応する系列・リビジョンのものを使う必要がある。さらに、ランタイム側がそのモデルのマルチモーダル経路へ対応していることも必要になる。

確認順は次のとおりだ。

1. モデル自体が目的の入力形式へ対応しているか
2. 対応するprojector/mmprojが必要か
3. 本体とprojectorの組み合わせが正しいか
4. ランタイムのバージョンがその経路へ対応しているか
5. テンプレートやprocessorが必要か

詳しくはローカルLLMで画像入力するには？ mmprojとランタイムの確認方法で整理している。

6. OOMはunsupportedとは別に切り分ける

モデルの解析や初期化まで進んだ後にout of memoryやメモリ確保失敗になる場合は、未対応アーキテクチャとは別の問題だ。

この場合は、量子化、コンテキスト長、KVキャッシュ、GPU offload、システムRAMなどを確認する。ファイルを読み込める状態まで進んでいるなら、ランタイム更新だけを繰り返すよりメモリ配置を見た方がよい。

反対に、アーキテクチャ未対応で読み込み前に止まっているなら、VRAMを増やしてもその問題は解消しない。

一度に一つだけ変更する

原因を探すときに、ランタイム更新、別GGUF、別テンプレート、GPU設定変更を同時に行うと、何が効いたのか分からなくなる。

ファイルを再取得したら同じランタイムで試す。ランタイムを更新したら同じGGUFで試す。テンプレートを修正したらモデルとGPU設定は変えない、といった形で一項目ずつ確認する。

GGUFが読み込めないときは、ファイルの完全性 → アーキテクチャ対応 → ランタイムのバージョン → テンプレートやmmproj → メモリの順で見れば、原因候補をかなり絞れる。ダウンロード前の確認へ戻る場合は、GGUFモデルをダウンロードする前に確認したい5項目も参考になる。