GGUF（GGML Universal File）は、テンソルとメタデータの両方を単一のファイルに格納するために設計されたバイナリファイル形式であり、モデルデータの高速な保存と読み込みを可能にする。2023年8月にllama.cppプロジェクトによって導入され、追加のモデルアーキテクチャのサポートが進む中で後方互換性を向上させるために作成された。GGUFは、GGMLなどプロジェクトで以前使用されていた形式を置き換え、通常は機械学習ライブラリ（PyTorchなど）で開発されたモデルを変換して生成される。この形式は、ローカル推論用に量子化された大規模言語モデルを配布する際の標準となり、llama.cpp、Ollama、LM Studio、GPT4All、Jan、koboldcppなどのツールでネイティブにサポートされている。2026年時点で、数万のGGUFチェックポイントがHugging Faceでホストされており、メタデータビューア、推論エンドポイントサービス、JavaScriptパーサライブラリを含むファーストクラスの統合が提供されている。
歴史
llama.cppプロジェクトで使用されるモデルファイル形式は、GGML、GGMF、GGJT、GGUFの4つの名前付き段階を経て進化した。元のGGML形式は、モデルのハイパーパラメータとトークナイザ情報をローダー内にハードコードした薄いテンソルコンテナであり、新しいモデルアーキテクチャや量子化スキームのサポートを追加するには、既存ファイルとの互換性を壊すコード変更が通常必要だった。
2023年にllama.cppがLlamaに加えてMistral、Falconなどの追加アーキテクチャをサポートするにつれて、これらの制限は管理がますます困難になった。GGUFは2023年8月21日に後方互換性のない後継として導入され、仕様はggerganov/ggmlリポジトリのプルリクエスト#302を通じて正式化された。この形式はGGJTの全体的なレイアウトを継承するが、そのフラットなハイパーパラメータリストを構造化されたキーと値のメタデータシステムに置き換え、アーキテクチャの詳細、トークナイザの語彙、トレーニングパラメータなどの新しいフィールドを、ローダーを変更したり古いモデルを壊したりせずに追加できるようにした。
形式自体は3つの内部バージョンを経ている。バージョン1は基本構造を確立し、バージョン2はメモリマッピングをサポートするための明示的なアライメントパディングを追加し、現在のバージョンであるバージョン3はオプションのビッグエンディアンサポートを追加した。
設計
GGUFは、モデルの重みの精度を下げる行為である量子化に焦点を当てている。これにより、モデルの精度が低下する代わりに、メモリ使用量の削減と速度の向上が可能になる。この形式は次のように設計されている：
- 自己完結型 - 単一のファイルにテンソル、トークナイザ、モデルの読み込みと実行に必要なすべてのメタデータが保持され、付随する設定ファイルが不要になる。
- メモリマッピング可能 - テンソルデータは（デフォルトで32バイト境界に）アラインされ、ファイル全体をRAMに読み込むことなくポインタを介して重みに直接アクセスでき、利用可能なメモリよりも大きいモデルをオペレーティングシステムのページングを通じて提供できる。
- 拡張可能 - キーと値のメタデータブロックにより、古いリーダーとの互換性を壊さずに新しいフィールドを追加できる。
GGUFは、2ビットから8ビットの量子化整数型、float32、float16、bfloat16などの一般的な浮動小数点データ形式、および1.58ビット量子化をサポートする。いくつかの「K-quant」バリアント（Q4_K、Q5_K、Q6_Kなど）は、スーパーブロックごとに個別のスケールと最小値を持つブロックベースのスキームを使用し、一般にQ4_0やQ8_0などの単純なレガシー量子化よりも、特定のビット幅でより良い品質を提供する。GGUFには、トークナイザの語彙、コンテキスト長、テンソル情報、その他の属性など、GPTのような言語モデルを実行するために必要な情報が含まれている。
ファイル構造
GGUFファイルは、固定サイズのヘッダ、キーと値のメタデータブロック、テンソル情報ブロック、テンソルデータ自体の4つの連続したセクションで構成される。
バイトレベルの構造（リトルエンディアン）
バージョン3より前は、ファイルは暗黙的にリトルエンディアンだった。バージョン3はビッグエンディアンストレージを許可するが、エンディアンを示すフラグは含まれないため、コンテキストから推測する必要がある。
#### メタデータブロック
メタデータブロックは、型付きキーと値のペアのシーケンスである。キーは名前空間付きの文字列（例：general.*、tokenizer.*、またはllama.*などのアーキテクチャ固有のプレフィックス）であり、値はスカラー、文字列、または多次元配列を含む配列にすることができる。
#### テンソル情報ブロック
各テンソルについて、情報ブロックはその名前、次元数、形状、データ型、および後続のtensor_data[]領域内のバイトオフセットを格納する。命名スキームはアーキテクチャ間で標準化されており（例：blk.0.ffn_gate.weight）、ローダーはソースフレームワークに関係なく重みを特定できる。
#### テンソルデータ
テンソルデータは情報ブロックに続き、次のアライメント境界から始まる。アライメント値自体はメタデータのgeneral.alignmentキーの下に格納され、存在しない場合はデフォルトで32バイトになる。このようにデータをアラインすることで、ファイルを直接メモリマッピングできる。テンソルの重みは追加のコピーなしでポインタを介して読み取ることができ、これはSIMD操作、GPU DMA転送、CPUキャッシュ効率にとって重要である。
ツール
他のフレームワークで保存されたモデルは、通常、llama.cppにバンドルされているconvert_hf_to_gguf.pyスクリプトを使用してGGUFに変換される。このスクリプトはHugging Faceのチェックポイント（一般的にはsafetensors形式）を読み取り、f16やbf16などの選択された基本精度でGGUFファイルを出力する。結果のファイルは、llama-quantizeユーティリティを使用してGGUF整数形式のいずれかに再量子化でき、非常に大きなモデルはllama-gguf-splitで複数のファイルにシャーディングできる。
llama.cppプロジェクトはまた、GGUFファイルをプログラムで読み書きするためのC/C++ API（ggml/include/gguf.hで宣言）とPythonパッケージgguf-pyを公開している。
採用
GGUFは、llama.cppおよび推論バックエンドとしてllama.cppを使用するOllamaのネイティブモデル形式である。Ollamaレジストリから取得されたモデルは内部的にGGUFファイルであり、Hugging Faceの任意のGGUFファイルはhf.co/{user}/{repo}として参照することで読み込むことができる。GGUFを直接消費する他の推論アプリケーションには、LM Studio、GPT4All、Jan、koboldcppが含まれる。
Hugging Faceは、モデルハブでこの形式をファーストクラスの市民としてサポートしており、GGUFメタデータビューア、ggufタグによるフィルタリング、推論エンドポイント統合、およびコミュニティがアップロードしたGGUFチェックポイントの大規模なコレクションを提供している。