GGUF
GGUFは、llama.cppがLLMの重み、トークナイザー、メタデータを保存するために使う単一ファイル形式であり、ローカルハードウェア向けに4~8ビットへ量子化されることがよくあります。
GGUFは、llama.cppを支えるC言語のテンソルライブラリであるGGMLと、その上に構築されたツールで実行するモデルを保存するためのバイナリファイル形式です。1つのGGUFファイルには、大規模言語モデル (LLM)の実行に必要なすべての要素、すなわちアーキテクチャとハイパーパラメーター、トークナイザーの語彙、チャットテンプレート、モデルの重みが格納されます。重みは通常、モデル量子化によって1つあたり2~8ビットに圧縮されます。llama.cppプロジェクトは、それ以前のGGML、GGMF、GGJT形式に代わる形式として、2023年8月にGGUFを導入しました。現在では、ノートPCのCPU、Apple Silicon搭載Mac、または一般向けGPUでのローカル推論向けに、オープンウェイトモデルを共有する標準的な方法となっており、Hugging Faceには数千のGGUFリポジトリがあります。
GGUFファイルの内部構造#
GGUF仕様では、4つの構成要素が順番に定義されています。ヘッダーにはマジックバイトGGUF、フォーマットのバージョン(現在は3)、テンソルとメタデータ項目の数が含まれます。続いて、general.architecture、llama.context_length、tokenizer.ggml.tokens、tokenizer.chat_templateなどの型付きキーと値のメタデータが並び、モデルのトークン化とプロンプト形式がファイル自体に埋め込まれます。次に、各テンソルの名前、形状、データ型、オフセットを記したテーブルがあり、最後にテンソルデータが続きます。実行環境がファイルをメモリマップしてほぼ瞬時に読み込めるよう、テンソルデータはデフォルトで32バイト境界にパディングされます。読み込み側はキーでメタデータを検索するため、古いファイルを壊すことなく、新しいアーキテクチャやフィールドを追加できます。
各テンソルはそれぞれの型を持つため、1つのファイル内で精度を混在させられます。llama.cppリポジトリで保守されているPythonパッケージggufは、この形式の読み書きと複数の量子化タイプに対応しています。
import numpy as np
from gguf import GGMLQuantizationType, GGUFReader, GGUFWriter
from gguf.quants import dequantize, quantize
weights = np.random.default_rng(0).standard_normal((1024, 1024)).astype(np.float32)
# A GGUF file holds metadata key-value pairs plus named tensors, each with its own type
writer = GGUFWriter("tiny.gguf", arch="llama")
writer.add_context_length(4096)
for qtype in [GGMLQuantizationType.F16, GGMLQuantizationType.Q8_0, GGMLQuantizationType.Q4_0]:
writer.add_tensor(f"weight.{qtype.name}", quantize(weights, qtype), raw_dtype=qtype)
writer.write_header_to_file()
writer.write_kv_data_to_file()
writer.write_tensors_to_file()
writer.close()
# Read the file back: metadata keys, then each tensor's bits per weight and rounding error
reader = GGUFReader("tiny.gguf")
print([name for name in reader.fields if not name.startswith("GGUF.")])
for tensor in reader.tensors:
error = np.abs(dequantize(tensor.data, tensor.tensor_type).reshape(weights.shape) - weights).mean()
print(f"{tensor.tensor_type.name}: {8 * tensor.n_bytes / weights.size:.1f} bits per weight, mean error {error:.4f}")この例では、2つのメタデータキーgeneral.architectureとllama.context_lengthを列挙した後、F16については重みあたり16.0ビット、平均誤差0.0001、Q8_0については8.5ビット、0.0045、Q4_0については4.5ビット、0.0719と報告します。Q8_0とQ4_0は32個の重みを1ブロックとして保存し、ブロックごとにFP16のスケールを1つ使います。これが追加の0.5ビットの由来です。
量子化タイプ#
GGUFの量子化タイプは3世代に分かれます。Q4_0やQ8_0などの初期ブロック形式では、32個の重みに対してスケールを1つ使います。Q4_KやQ6_KなどのK量子化では、量子化されたスケールを使い、256個の重みをスーパーブロックにまとめます。Q4_K_Mなどのファイル名は、特に影響の大きいテンソルを高精度に保つ混合形式を示します。IQ2_XXSやIQ4_XSなどのI量子化では、通常、llama-imatrixがサンプルテキストから計算する重要度行列を使い、影響の大きい重みほど高精度を保ちながら、重みあたり約2~4ビットを実現します。新しい形式には、OpenAIがgpt-ossのリリースに使用した4ビット浮動小数点形式MXFP4もあります。公開されているGGUFファイルの大半は、同じ変換経路から生成されています。
GGUFと他のモデル形式の比較#
- GGML、GGMF、GGJT: llama.cppの旧形式では、ハイパーパラメーターが型のないリストとして保存され、アーキテクチャフィールドもなかったため、パラメーターを追加すると既存のファイルが壊れていました。
- Safetensors: Hugging Faceの形式で、生のテンソルを通常は全精度または半精度で安全に保存します。設定とトークナイザーは別ファイルに格納します。
- ONNX: 重みとともに計算グラフ全体を保存するため、ONNX互換のランタイムであれば、アーキテクチャ固有のコードなしでモデルを実行できます。
GGUFモデルの実行#
llama.cppは、コマンドラインから、またはOpenAI互換APIを公開するllama-serverとしてGGUFファイルを実行できます。任意の数のレイヤーをGPUにオフロードし、残りをCPUで実行できるため、GPUメモリより大きなモデルも動かせます。OllamaとLM Studioでは、モデルライブラリとチャットインターフェースを介してGGUFモデルを実行できます。また、Hugging Face Hubでは、各GGUFファイルのメタデータとテンソル型をブラウザーで確認できます。ローカル推論ではプロンプトをマシン上に保持できるため、データプライバシーやオフラインのエッジAI用途で重要です。Ultralytics LLMインターフェースは、llama-serverまたはOllamaが提供するGGUFモデルを、OpenAI互換のChat Completionsエンドポイント経由で呼び出せます。そのため、YOLO26のパイプラインは、データをクラウドAPIに送信せず、ローカルモデルに検出結果の説明を依頼できます。この形式は言語モデル以外にも広がっており、ComfyUI-GGUFのカスタムノードは、FLUX.1などの量子化された拡散モデルをGGUFファイルから読み込み、一般向けGPUのメモリに収まるようにします。










