basic / format

GGUFとは？ファイル形式の仕組みと対応ランタイムを初心者向けに解説

GGUFは、ローカルLLMで使われるモデルファイルの形式（フォーマット）です。アプリではなく、 AIモデルの重み（パラメータ）や設定を1つのファイルにまとめたデータ形式です。 LM Studio、Ollama、llama.cpp、KoboldCpp などが読み込みます。

読了後に判断できること：GGUFが「何を格納しているか」「アプリとの違い」「safetensorsとの使い分け」 「自分のPCに合うファイルを選ぶために見るべき場所」。内部仕様をすべて覚える必要はありません。

GGUFという言葉の意味

GGUFは GGML Unified Format の略で、もともと llama.cpp ecosystem で使われていた GGML 形式の後継として設計されました。「Unified（統一された）」という名の通り、 モデルの重みだけでなく、トークナイザー、チャットテンプレート、アーキテクチャ情報などを 1つのファイルにまとめることを目的としています。

日常的な使い方では「LM Studio でローカルAIを動かすためのモデルファイルの形式」と 理解すれば十分です。内部のバイナリ構造を覚えるより、後述の「自分のPCに合うファイルを選ぶ」方が先です。

図：GGUFの位置づけ

GGUFファイル (.gguf)
  ├─ metadata（名前/アーキテクチャ/chat template/context等）
  ├─ tensors（モデル重み＝パラメータ、量子化済み）
  └─ vocab/tokenizer（テキスト変換用）
        ↑ アプリ(LM Studio / Ollama / llama.cpp) が読み込んで推論を実行

図は概念図。実際のバイナリ配置は GGUF 仕様（ggml-org/ggml）を参照。

GGUFに含まれているもの

GGUFファイルには、推論に必要な情報が1つのファイルにまとめられています。主な構成要素は次の通りです。

GGUFの主要構成要素
要素役割選び方への影響
metadataモデル名、アーキテクチャ、チャットテンプレート、推奨コンテキスト長など。ツールが「どう扱うか」を判断するために使います。アプリが自動設定するため、基本的にユーザー選択は不要。但し互換性判定の根拠。
tensorモデルの重み（パラメータ）そのもの。量子化によって精度が落とされている場合があります。ファイルサイズ・品質の決定要因。Q4_K_M等の表記はここを指す。
vocab / tokenizerテキストをトークンに変換するための情報。会話の前処理・後処理に使います。モデルと一致している必要あり。不一致は文字化け・崩れた出力の原因。
chat templateユーザー・アシスタントの発話をどう囲むかの書式。Instruct系で重要。欠落すると「指示に従わない」ように見える。多くはmetadataから自動適用。

詳細な仕様は一次資料（ggml-org/ggml の GGUF仕様）を参照してください。出典一覧 からたどれます。

対応しているランタイム（読み込む側）

GGUFを扱える主なツールは以下の通りです。同じGGUFでも、ツールによって細かい対応に差があります。

LM Studio：GUIで models/ から選んでチャット。初心者に扱いやすい。
Ollama：コマンドでモデルを管理・実行。Modelfileで設定を記述。
llama.cpp：C++実装の推論エンジン。多くのツールの基盤。
その他：KoboldCpp、text-generation-webui など。

「GGUF対応」と書かれていても、マルチモーダル（mmproj）や特定量子化の扱いはツールごとに異なります。 使うアプリの対応表も確認してください。

llama.cpp ecosystem の役割

llama.cpp は GGUF を直接読み込める C++ 推論エンジンであり、LM Studio や Ollama の多くも内部で これと互換の処理系を利用しています。このため「GGUF の挙動」は、最終的に 読み込むツールが採用している llama.cpp のバージョン・設定に依存します。 同じ GGUF でも、アプリのバージョンによって細かい挙動が変わることがあります。

GGUFはアプリではない

GGUFはあくまで「モデルファイル」です。LM Studioのようなアプリに .gguf ファイルを 読み込ませて使います。「GGUFをインストールする」ではなく「LM StudioにGGUFを読み込ませる」のが正確です。

よくある誤解：「GGUFをダウンロードすればAIが動く」と思いがちですが、GGUF単体では推論できません。 必ず llama.cpp 系のランタイム（LM Studio 等）と組み合わせます。

safetensors との違い

Hugging Face の safetensors もモデル重みを格納する形式ですが、設計目的が異なります。

GGUF と safetensors の使い分け
観点GGUFsafetensors
主な用途ローカル推論（llama.cpp系）での配布・実行学習・変換・Hub上の保存（PyTorch等）
付帯情報chat template・アーキテクチャ等を含むテンソルデータ中心。設定は別管理のことが多い
量子化K-quant/I-quant等の多様な量子化を標準サポート変換時に別ツールを経由
選ぶ基準「PCで動かす」ならGGUF「学習・微調整・変換」ならsafetensors

優劣ではなく用途の違いです。ローカルでチャットしたい場合は GGUF を選び、 モデルを自分で変換・学習したい場合は safetensors を扱うのが一般的です。 詳しくは GGUFとsafetensorsの違い を参照。

metadata が「自動設定」を担う

GGUF の大きな利点の一つが、metadata に推論に必要な設定が含まれていることです。 アプリはこれを読んで、チャットテンプレートやコンテキスト長の初期値などを自動で決めます。

  • architecture：モデルの構造（層数・head数・アテンション種別など）。互換性判定の根拠。
  • chat template：Instruct系モデルで「どう指示を囲むか」。欠落すると会話品質が落ちる。
  • context length：モデルが想定する最大コンテキスト。アプリの既定値の目安になる。
  • quantization：適用された量子化方式。ファイル名の表記と一致するはず（不一致は要確認）。li>

metadata は アプリが自動で読むため、初心者が手動で編集する場面は稀です。 ただし「なぜか動かない・おかしい」ときは、metadata とアプリの対応がズレている可能性を疑います （トラブルシューティング参照）。

splitファイルと mmproj

split（分割）ファイル

大きなモデルは 00001-of-00003.gguf のように複数のシャードに分割されて配布されることがあります。 この場合、全シャードが揃わないとロードできません。ダウンロード漏れがないよう注意してください。 詳しくは split GGUFファイルの扱い を参照。

mmproj（マルチモーダル投影ファイル）

画像・音声などのマルチモーダルモデルでは、LLM本体とは別に mmproj（projector）ファイルが必要です。 「mmproj」という通称は projector を指しますが、実際には vision/audio encoder 等を含み得ます。 mmproj が不足・不一致だと画像が扱えないなどのエラーになります。 詳しくは mmprojとマルチモーダル を参照。

フォーマットバージョン

GGUF にはフォーマットバージョン（GGUF v2, v3 等）があり、読み込むランタイムが対応していない新しいバージョンだと エラーになることがあります。通常はアプリが自動判別しますが、非常に古いツールで新しい GGUF を開こうとすると 「unsupported GGUF version」のようなエラーが出る場合があります。その際はアプリのアップデートを検討してください。

metadata viewer で中身を確認

Hugging Face のモデルページには GGUF の metadata viewer が用意されており、 アーキテクチャやチャットテンプレート、量子化方式をブラウザで確認できます。 自分がダウンロードしようとしているファイルが「どのモデルで、どう量子化されているか」を確認するのに便利です。

viewer は配布元が提供する補助機能です。必ずしもすべてのリポジトリで利用できるとは限りません。

得意・不得意と適用外

GGUFが得意なこと

  • PC1台でモデルを動かす配布形式として整っている
  • 量子化済みで軽量、チャット等の設定も含む
  • llama.cpp系ツールでの読み込みが広く支持されている

適用外・注意

  • GGUF単体では推論できない（ランタイム必須）
  • 量子化により元モデルとの品質差が生じる（タスク・モデルによる）
  • マルチモーダルは本体＋mmproj の組み合わせが必要
  • 配布元の信頼性は GGUF 形式自体では保証されない（安全な取得参照）
限界の明示：本ページの説明は GGUF の「形式」に関する一般論です。 特定モデルの動作や品質は、モデル本体・量子化・実行環境に依存します。数値的な保証ではありません。

実際にファイルを選ぶときのチェックポイント

GGUF の仕組みを知った上で、実際にファイルを選ぶときに見るべきポイントをまとめます。 これらは「形式」ではなく「中身」に関わるため、他の記事と併せて判断します。

選ぶときのチェックポイント
見るべき点確認方法判断のヒント
モデル規模（パラメータ）ファイル名の 7B / 14B 等、またはモデルカードPCのメモリに合わせる（メモリ目安）
量子化精度Q4_K_M / IQ4_XS 等の表記まず Q4_K_M から（量子化の基本）
Instruct / Baseモデル名の接尾辞、または説明チャットなら Instruct 系を選ぶ
分割の有無-00001-of-00003.gguf 等の命名全シャードが必要（split解説）
マルチモーダルmmproj / vision の表記画像入力には mmproj が別途必要（mmproj解説）
配布元リポジトリの所有者・説明信頼できる配布元から（安全な取得）

ファイル名だけでは「リポジトリ固有の表記」が含まれることがあり、断定はできません。 不明な場合は ファイル名デコーダー で推定し、モデルカードで最終確認します。

よくある質問

GGUF と safetensors はどちらをダウンロードすべき？

PCでモデルを動かすなら GGUF を選びます。safetensors は学習・変換・Hub 上での保存に使われる形式で、 そのままローカル推論ツールで動かすには GGUF へ変換するのが一般的です。用途の違いなので、「どちらが優秀」ではありません。

GGUF の拡張子は？

通常は .gguf です。分割ファイルも個々に .gguf となります。 実行ファイル（.exe 等）が同梱されている場合は警戒します（安全な取得）。

古い GGUF は使える？

フォーマットバージョンが古すぎると、新しいランタイムでエラーになることがあります。 その際はランタイム（LM Studio 等）を最新にするか、配布元の推奨バージョンを確認します。

GGUF 単体でチャットできる？

できません。GGUF はモデルファイルであり、LM Studio 等のランタイムと組み合わせて初めて推論します。

よくある失敗例

  • 「GGUFをダブンロードすれば動く」と思った：ランタイムが必要。LM Studio 等を別途用意。
  • 分割ファイルの一部だけ取得した：全シャードが揃わないとロードエラー。全部揃える。
  • Base モデルをチャットに使った：指示に従わない。Instruct/Chat 系を選ぶ。
  • mmproj を忘れた：画像入力が動かない。本体＋mmproj のセットを用意。
  • メモリ不足で動かないのに同じファイルを試した：より小さい規模・軽い量子化へ（チェッカー）。
  • metadata の意味が分からない：GGUFメタデータ項目 で general/architecture/tokenizer を確認。
これらの失敗は「GGUF の形式」そのものではなく、「どう扱うか」の問題です。 本サイトの各ガイドで、それぞれの切り分け方を扱っています。

次の行動

GGUFの概要を理解したら、次は「自分のPCで動くモデルを選ぶ」です。

LM Studioでダウンロードする手順へ 自分のPCで選ぶチェッカーへ 量子化の基本を理解する

更新履歴：2026-07-18 pillar 拡張（metadata/split/mmproj/version/viewer/限界を追加）。