GGUF形式：ローカルLLM推論の完全ガイド

GGUFとは？

GGUF（GGML Unified Format）は、モデルの重み、トークナイザーのデータ、アーキテクチャのメタデータ、量子化情報を、GGML系のランタイム、特にllama.cppでの推論向けに単一で持ち運べるファイルへまとめるバイナリ形式です。

GGUFはLLMのデプロイ課題を解決します。多くのモデル形式では、モデルの重み、トークナイザーのファイル、設定ファイル、アーキテクチャ固有の読み込みコードなど、複数のファイルをまとめて扱う必要があります。GGUFはモデルファイル自体を大きく自己記述的にすることで、これを簡素化します。

典型的なGGUFファイルには次が含まれます。

• モデルのテンソル
• 量子化済みまたは非量子化の重み
• トークナイザーの語彙
• トークナイザー設定
• モデルアーキテクチャのメタデータ
• コンテキスト長の設定
• 埋め込み次元
• アテンションヘッド数
• RoPEの設定
• テンソル名、形状、データ型

重要な考え方は、ファイルが自らを記述していることです。ランタイムはメタデータを読み取り、アーキテクチャを理解し、トークナイザーを読み込み、別のconfig.jsonやトークナイザーフォルダに依存せずにテンソルを割り当てられます。

とはいえ、すべてのGGUFファイルが永遠にすべてのランタイムと互換というわけではありません。ランタイム側が、ファイルで使われているモデルアーキテクチャやテンソル型をサポートする必要はあります。しかし、ファイル自体がより構造化された情報を多く持つため、旧形式に比べ互換性の確保がはるかに容易になっています。

GGUFを特徴づける4つのポイントは次のとおりです。

1. 単一ファイルでのデプロイ
2. 効率的な読み込みのためのメモリマッピング対応
3. 拡張可能な型付きキー・バリューメタデータ
4. 低ビットから高精度まで多様な量子化タイプのサポート

GGUFは2023年、llama.cppとGGMLのエコシステムの一部として導入されました。現在はHugging Face上で量子化ローカルLLMを配布する主流形式です。

GGUFとGGMLの違い

GGML（Georgi Gerganov Machine Learning）形式はGGUFの前身です。初期のローカル推論を可能にした重要な形式でしたが、エコシステムがオリジナルのLLaMAモデル以外へ拡大するにつれて実用上の制約がありました。

GGMLでよくあった課題は次のとおりです。

• 柔軟性に欠けるメタデータ処理
• アーキテクチャ固有の読み込み前提が多い
• 自己完結性の低いトークナイザーと設定の扱い
• 新しいモデルファミリーの登場に伴う拡張の難しさ

GGUFはより構造化された形式にすることで、これらの制約を解決しました。型付きメタデータ、より良いトークナイザーの埋め込み、明確なファイルレイアウトを導入し、llama.cppや関連ツールが読み込みパイプラインを頻繁に再設計せずとも、より多くのアーキテクチャをサポートしやすくしました。

ユーザーにとって重要な違いはシンプルです。GGUFが現代的な形式だということ。いまモデルをダウンロードするなら、古いGGMLではなく、ほぼ常にGGUFを選ぶべきです。

GGUF vs. GPTQ / AWQ

ファイル形式を調べると、GGUF、GPTQ（Generative Post-Training Quantization）、AWQ（Activation-Aware Weight Quantization）に行き当たるはずです。いずれもLLM推論を効率化するために使われるため、一緒に語られることが多いですが、同じカテゴリではありません。

GGUFは主にファイル形式であり、デプロイ用コンテナです。多様な量子化タイプをサポートし、llama.cpp流のローカル推論と密接に結びついています。

GPTQとAWQは量子化手法およびそのエコシステムで、特にTransformers、ExLlama、AutoGPTQ、vLLM互換のワークフローなどを通じて、NVIDIAハードウェア上のGPU最適化推論で一般的です。

ノートPC、デスクトップ、Apple Silicon、混在ハードウェア間で最大限の互換性を目指すなら、通常はGGUFが安全な選択です。

専用のNVIDIA推論サーバーで最大スループットを狙うなら、GPTQ、AWQ、FP8などGPU最適化のサービング形式のほうが適している場合があります。

なぜGGUFを使うのか

GGUFが人気になったのは、実運用上のデプロイ課題を解決するからです。ローカルにデプロイする際の面倒なセットアップなしで扱える点も非常に便利です。

かつてローカルLLMの実行は、分断されたツール群、巨大な非圧縮の重み、互換性のないモデル形式、複雑なセットアップ手順を伴っていました。いまはGGUFにより、その多くを標準化できます。

複数のファイルや読み込みスクリプトを気にする代わりに、適切なモデルの選択、量子化レベルの決定、推論の実行に集中できます。

ローカルでモデルを実行

GGUFを使えば、自分のマシンでLLMを実行できます。つまり次のような利点があります。

• トークンごとのAPI費用が不要
• ホスト型推論プロバイダへの依存なし
• プロンプトを外部APIへ送信する必要なし
• モデルをダウンロード後はオフライン推論も可能

これはプライバシー重視のワークフローで特に有用です。開発者は、専有コード、社内文書、顧客データ、機密プロンプトを外部APIに送信したくない場合があります。

ローカル推論自体が自動的に安全になるわけではありません。マシン、ログ、アプリケーション、アクセス制御は適切に管理する必要があります。ただし、GGUFによりプライベートなローカルデプロイがはるかに手軽になります。

ローカルでの実行を実践したい場合は、SGLangでMistral Medium 3.5を提供、DeepSeek V4 Flashをローカルで実行、古いノートPCで効率的なBonsai 1-bitモデルを実行、MiniMax M2をローカルで動かしてコーディング支援の各チュートリアルをご覧ください。

ハードウェアの柔軟性

GGUFは多様なハードウェア構成で動作するため、有用です。

ランタイムやバックエンドにより、GGUFモデルは次の環境で動作します。

• CPUのみのマシン
• CUDA経由のNVIDIA GPU
• Metal経由のApple Silicon
• HIPやVulkan経由のAMD GPU
• SYCLやVulkan経由のIntel GPU
• 一部のARMやモバイル環境

この柔軟性はllama.cppが影響力を持った大きな理由です。ハイエンドのサーバーGPU専用ではなく、幅広いハードウェアでローカル推論を可能にすることを目的に設計されています。

たとえばMacユーザーはMetalによるアクセラレーション、LinuxデスクトップユーザーはCUDAやVulkanを使うかもしれません。CPUのみのユーザーでも、生成速度は遅くなりますが、より小さな量子化モデルを実行できます。

広いエコシステムの支援

GGUFは多くのローカル推論ツールでサポートされています。例：

• コマンドライン／サーバー推論用のllama.cpp
• CLI中心のモデル管理とAPIアクセスを提供するOllama
• デスクトップGUIのLM Studio
• プライバシー重視のローカルチャット用GPT4All
• ロールプレイやテキスト生成ワークフロー向けKoboldCpp
• ローカルAIインターフェースのJanやOpen WebUI

ユーザーが特定のインターフェースに縛られない点が重要です。同じ一般的なモデル形式を異なるワークフローで利用できます。

開発者は、llama.cppでベンチマークし、LM Studioでチャットし、Ollamaで提供し、Open WebUI経由でブラウザUIに接続する、といった使い分けが可能です。

Hugging Faceでの配布

Hugging FaceはGGUFモデルの主要な配布拠点になっています。

出典：Hugging Face

多くの人気オープンウェイトモデルは、リリース後まもなくコミュニティによってGGUF版がアップロードされます。これらのリポジトリには複数の量子化オプションが含まれることが多く、ユーザーは自分のハードウェアに合うものを選べます。

一般的なアップロードの例：

• Q4_K_M
• Q5_K_M
• Q6_K
• Q8_0
• IQ4_XS
• IQ3_M
• IQ2_XXS

つまり、手動変換は不要な場合が多いということです。人気モデルなら、一般的な量子化レベルのGGUFファイルをすでに誰かが用意していることがほとんどです。

粒度の高いサイズと品質の制御

GGUFでは、サイズと品質のトレードオフをきめ細かく制御できます。次のように選べます。

• 低メモリ環境向けの小さな量子化
• 日常利用にバランスの良い中間的な量子化
• コーディング、推論、構造化出力向けの高ビット量子化
• メモリ制約がない場合の完全または準高精度

この柔軟性は、形式としての大きな強みです。単一の固定デプロイ先に合わせるのではなく、同一モデルファミリーを多様なハードウェア層に適応できます。

GGUFの仕組み

GGUFファイルは大きく3つの部分で構成されています。

1. ヘッダ
2. メタデータとテンソル情報
3. テンソルデータ

正確な構造はGGUF仕様で定義されています。重要なのは、生のテンソルデータの前にメタデータとテンソル情報が現れ、ランタイムがこれから読み込むものを理解できる点です。

ヘッダ

ヘッダはファイルがGGUFであることを示し、ランタイムに残りの解析方法を伝えます。含まれる情報は次のとおりです。

• GGUFのマジックナンバー
• フォーマットバージョン
• テンソル数
• メタデータのキー・バリュー数

現在のGGUFファイルは、一般にバージョン3を使用しています。

推論エンジンはまずマジックナンバーを確認します。ファイルが期待されるGGUF識別子で始まっていなければ、テンソルの解析やメモリ割り当てを試みる前に拒否できます。

これは単純ですが重要な安全性と信頼性のための手順です。無関係なバイナリファイルを誤ってモデルとして扱うことを防ぎます。

メタデータのキー・バリューペア

GGUFのメタデータは型付きのキー・バリューストアです。次のような記述が可能です。

• 一般的なモデル情報
• アーキテクチャファミリー
• コンテキスト長
• 埋め込みサイズ
• レイヤー数
• アテンションヘッド数
• RoPEパラメータ
• トークナイザーの語彙
• 特別トークン
• 量子化情報

キーは通常、名前空間が付けられます。例：

• general.architecture
• general.alignment
• llama.context_length
• tokenizer.ggml.tokens

名前空間は、GGUFがファイル形式全体を変えずに多様なアーキテクチャをサポートするために重要です。LLaMA系モデルはllama.*のキーを使い、他のモデルファミリーはそれぞれ固有のメタデータを使えます。

これは、Qwen、Mistral、Gemma、DeepSeek、Phiなど、オリジナルのLLaMA以外のアーキテクチャにもGGUFがうまく適応できた理由のひとつです。

テンソル情報とテンソルデータ

メタデータの後に、テンソル情報とテンソルデータが格納されます。

テンソル情報には次が含まれます。

• テンソル名
• 形状
• データ型
• テンソルデータセクションへのオフセット

テンソルデータセクションには、実際のモデル重みが入ります。これらの重みはフル精度、またはGGUFでサポートされる量子化テンソル型のいずれかで保存されます。

GGUFはメタデータで定義されるアライメント値（一般にgeneral.alignment）を使用します。多くのGGUFファイルは32バイトアライメントを用いますが、重要なのは、アライメントが固定ではなくメタデータで制御されるという点です。

アライメントは、ランタイムがテンソルブロックへ効率的にアクセスできるようにするため重要です。

メモリマッピング

GGUFの実用的な利点のひとつがメモリマッピング（mmap）です。

メモリマッピングでは、OSがモデルファイルを仮想メモリにマップし、ランタイムがファイル全体を事前にRAMへコピーすることを強制しません。

これにより、特にSSD環境ではモデルの起動が体感的に速くなります。また、OSが必要に応じてモデルデータのページングを行えます。

ただし、メモリマッピングは魔法ではありません。モデルがうまく動作するには、実効的なメモリ帯域や十分なRAM／VRAMが必要です。ディスクからのページングが頻発すると、推論は遅くなり得ます。

mmapは次のように捉えるとよいでしょう。

• 読み込み効率を高める
• 不要なコピーを減らす
• OSにページング管理を任せる
• 推論に必要なメモリ要件を消し去るわけではない

GGUFの量子化タイプの理解

量子化は、モデルの重みを低精度表現へ圧縮します。

すべての重みを16ビット浮動小数点で保存する代わりに、量子化モデルはより少ないビットで近似値を保持します。これにより、ディスクサイズ、RAM／VRAM使用量、メモリ帯域の負荷が軽減します。

多くのニューラルネットワークの重みは、推論時に完全な浮動小数点精度を必要としないというのが鍵です。注意深く量子化すれば、元モデルの挙動を大きく保ちながら、劇的にサイズを小さくできます。

GGUFの量子化命名

GGUFの量子化名は通常、次のパターンに従います。

• Qは量子化（Quantized）を意味する
• 数字はおおよその重みあたりビット数を示す
• Kはk-quantファミリーを指す
• S、M、Lは通常、小・中・大のバリアント

例：

• Q4_K_M
• Q5_K_M
• Q6_K
• Q8_0

名称は有用な指標ですが、実際のファイルサイズを正確に表すとは限りません。実サイズは、テンソル構成、アーキテクチャ、メタデータ、トークナイザーのサイズ、一部テンソルが高精度のままかどうかなどに依存します。

一般的なGGUFの量子化タイプ

これらの数値は7B級の密モデルに対する概算です。新しいアーキテクチャ、Mixture-of-Expertsモデル、より大きなトークナイザー、異なるテンソルレイアウトにより、実サイズは変わり得ます。

実際、Q4_K_Mはサイズと品質のバランスが良いため、一般的なデフォルトとして普及しました。多くのユーザーは、汎用チャット、要約、書き換え、ローカルAIの探索的作業に十分だと感じています。

コーディングや複数ステップの指示追従など、より要求の厳しいワークロードには、Q5_K_MやQ6_Kが選ばれることが多いです。

理由は単純で、これらのタスクは小さな品質低下の影響を受けやすいからです。

K-quantとI-quantの比較

K-quantは、Q4_K_M、Q5_K_M、Q6_Kのような形式の背景にある広く使われる量子化ファミリーです。

スケーリング情報を備えたグループ化量子化手法を用い、メモリ要件を下げつつモデル挙動の保持を助けます。信頼性が高く、広くサポートされ、コミュニティのGGUFリリースで見つけやすい点が人気の理由です。

I-quantは、しばしばIQ形式と書かれ、次のような新しい量子化タイプです。

• IQ4_XS
• IQ3_M
• IQ2_XXS
• IQ1_S

I-quantは、非常に小さなサイズでより良い品質を達成することを狙っています。重要度認識の量子化や非線形の量子化コードブックなどの手法を使うことができます。ワークフローによっては、重要度行列（imatrixと呼ばれることが多い）を用いて、重要な重みをより保持するように量子化を行います。

トレードオフは複雑さです。I-quantは特に超低ビットレートで優れたサイズ・品質を実現できますが、より注意深い量子化ワークフローとランタイム対応を要する場合があります。

多くの初心者にとっては、依然としてK-quantが最も取り組みやすい出発点です。

ハードウェアに合わせた量子化レベルの選択

以下の表は実践的な出発点です。あくまで経験則であり、厳密な保証ではありません。コンテキスト長、OSのオーバーヘッド、GPUオフロード、KVキャッシュサイズ、特定のモデルアーキテクチャなどで必要メモリは変わります。

一般的な指針：

• ローカル推論ではQ4_K_Mを安全なデフォルトとする。
• 数GBの節約より品質を重視する場合はQ5_K_M。
• メモリに余裕があり忠実性を高めたいならQ6_KやQ8_0。
• 極端なメモリ制約の実験でない限り、真剣な用途でQ2_Kは避ける。
• 特に長いコンテキストウィンドウを使う場合は、KVキャッシュ分のメモリを確保する。

KVキャッシュは見落とされがちです。短いコンテキスト長ではRAMに収まるモデルでも、シーケンス長が伸びてキャッシュが増大すると、失敗したり遅くなったりします。

GGUFエコシステム

GGUFの普及は、形式そのものと同じくらいツール群に支えられています。

形式が本当に有用になるのは、ユーザーが簡単にモデルをダウンロード、実行、検査、変換、配信できるときです。GGUFは、コマンドラインツール、デスクトップアプリ、API、ホスト型モデルリポジトリにまたがる強力なエコシステムの恩恵を受けています。

1. llama.cpp

llama.cppは、元祖かつ最も重要なGGUFランタイムです。Georgi Gerganov氏が作成し、GGMLコミュニティがメンテナンスする軽量なC/C++推論エンジンで、主要目的は、最小限のセットアップで多様なハードウェア上で効率的にLLM推論を可能にすることです。

最新のllama.cppは次のようなバックエンドをサポートします。

• CPU
• NVIDIA GPU向けCUDA
• Appleデバイス向けMetal
• Vulkan
• ROCm経由のAMD GPU向けHIP
• Intel GPU向けSYCL
• 一部環境でのOpenCL
• プラットフォーム対応に応じてCANN、OpenVINO、WebGPUなどの専用バックエンド

また、変換、量子化、サービング、ベンチマーク、コマンドライン推論のツールも含みます。代表的なツール：

• convert_hf_to_gguf.py
• llama-quantize
• llama-cli
• llama-server
• llama-bench

基本的なCPU向けCMakeビルドのコマンドは次のとおりです。

cmake -B build
cmake --build build --config Release

一部の構成では、最初のコマンドに特定のフラグを追加する必要があります。

• macOSでApple Metalを無効化（デフォルトは有効）：-DGGML_METAL=OFF
• Vulkanビルド：-DGGML_VULKAN=1
• NVIDIA GPU向けCUDAビルド：-DGGML_CUDA=ON

現在のビルドでは、GGML_CUDA、GGML_VULKAN、GGML_HIPなどGGML_*のCMakeオプションを使用する点に注意してください。

2. Ollama

Ollamaはローカルモデルを実行する最も簡単な方法のひとつです。次の機能を提供します。

• シンプルなCLI
• モデルの取得と管理
• ローカルREST API
• 公式のPython／JavaScriptライブラリ
• 多数のローカルAIフロントエンドとの連携

Ollamaはモデルの保存と管理を担うため、ユーザーは通常.ggufファイルを直接扱いません。ただし、Ollamaはllama.cpp互換のローカル推論を中核としており、Modelfileのワークフローを通じてGGUFファイルをインポートできます。

Ollamaは次のローカルAPIを公開しています。

http://localhost:11434/api

よく使われるエンドポイントは次の2つです。

• /api/generate（プロンプト補完）
• /api/chat（チャット形式のメッセージ）

初心者には、Ollamaがゼロからローカル推論への最短経路であることが多いです。

3. LM Studio

出典：LM Studio

LM Studioは、ローカルモデルの検索、ダウンロード、チャットを行うデスクトップアプリケーションです。コマンドラインツールではなく、グラフィカルなインターフェースを好むユーザーに向いています。

4. GPT4All

出典：GPT4All

GPT4Allは、プライバシー重視のローカルチャットボットワークフローに特化したクロスプラットフォームのローカルAIアプリケーションです。GGUFモデルをサポートし、初心者でも使いやすいローカル推論環境を提供します。

これらのツールにより、専門家でなくともGGUFが扱いやすくなります。ローカルモデルを試すためにCMakeやテンソルレイアウト、量子化の内部を理解する必要はありません。

GGUFモデルの始め方

実用的な始め方は2通りあります。

1. 最も簡単な体験にはOllamaを使う。
2. より細かな制御にはllama.cppを直接使う。

Ollamaでモデルを実行する

最も簡単なワークフローは、モデルをダウンロードして対話型チャットセッションを開始することです。

ollama pull llama3.3
ollama run llama3.3

REST APIを使ってPythonからモデルを呼び出すには：

import requests

payload = {
    "model": "llama3.3",
    "prompt": "Give me three practical use cases for GGUF.",
    "stream": False
}

response = requests.post(
    "http://localhost:11434/api/generate",
    json=payload
)

print(response.json()["response"])

チャット形式のアプリケーションには/api/chatを使います。

import requests

payload = {
    "model": "llama3.3",
    "messages": [
        {"role": "user", "content": "What is GGUF used for?"}
    ],
    "stream": False
}

response = requests.post(
    "http://localhost:11434/api/chat",
    json=payload
)

print(response.json()["message"]["content"])

シンプルなスクリプトでは、stream: falseが重要です。これを指定しないと、Ollamaは最終的な単一のJSONではなく、JSONオブジェクトのストリームを返します。

また、Ollama公式のPythonライブラリも利用できます。

from ollama import chat

response = chat(
    model="llama3.3",
    messages=[
        {"role": "user", "content": "Explain GGUF quantization simply."}
    ]
)

print(response.message.content)

llama.cppでGGUFファイルを実行する

すでに.ggufファイルがある場合は、プロジェクトをビルドした後、llama.cppで直接実行できます。

例：

./build/bin/llama-cli \
  -m models/model.Q4_K_M.gguf \
  -p "Explain the difference between GGUF and GPTQ." \
  -n 256

GPU対応が有効なら、レイヤーをGPUにオフロードできます。

./build/bin/llama-cli \
  -m models/model.Q4_K_M.gguf \
  -p "Summarize GGUF in five bullet points." \
  -n 256 \
  -ngl 99

-nglフラグはGPUにオフロードするレイヤー数を制御します。モデルがVRAMに収まる想定で、99のような高い値を使い、可能な限り多くをオフロードするのが一般的です。

APIサービングにはllama-serverを使用します。

./build/bin/llama-server \
  -m models/model.Q4_K_M.gguf \
  -ngl 99 \
  --host 127.0.0.1 \
  --port 8080

これにより、アプリケーションへllama.cppを統合するためのローカルサーバーインターフェースが得られます。

Hugging FaceモデルをGGUFへ変換する

コミュニティ製のGGUFリリースが広く利用できるため、多くのユーザーに手動変換は不要です。

ただし、次のような場合は手動変換が有用です。

• 自分でファインチューニングしたモデルがある
• まだGGUF版が存在しない
• 量子化処理を自分で制御したい
• 特定の量子化タイプが必要

典型的なワークフロー：

1. Hugging Faceのモデルをダウンロード。
2. GGUFへ変換。
3. GGUFファイルを量子化。

例：

huggingface-cli download mistralai/Mistral-7B-Instruct-v0.3 \
  --local-dir mistral-7b

次にGGUFへ変換：

python convert_hf_to_gguf.py mistral-7b \
  --outfile mistral-f16.gguf \
  --outtype f16

次に量子化：

./build/bin/llama-quantize \
  mistral-f16.gguf \
  mistral-q4_k_m.gguf \
  Q4_K_M

現行のllama.cppワークフローでは、convert_hf_to_gguf.pyとllama-quantizeが関連ツールです。古いチュートリアルでは、廃止された変換スクリプトや旧バイナリ名に言及していることがあります。

GGUF形式の利点と制約

GGUFは実用的なローカル推論に最適化されています。すべてのモデル形式やサービングスタックを置き換える万能の解ではありません。

CPU優先、Apple Silicon、混在ハードウェア、プライバシー重視の推論において、GGUFはしばしば優れた選択肢です。

一方、NVIDIAサーバーでの高スループット配信では、モデル、バッチサイズ、量子化手法、サービングフレームワークにより、他の形式やエンジンのほうが高速な場合があります。

まとめ

GGUFは、ランタイムに必要なすべて（重み、トークナイザー、メタデータ、量子化情報）を1つのポータブルファイルにまとめることで、ローカルLLM推論を現実的なものにします。真の強みはそのエコシステムにあり、llama.cpp、Ollama、LM Studio、Hugging FaceがローカルAIデプロイのデフォルト形式として定着させました。

多くのユーザーにとって道筋はシンプルです。Ollamaをインストールし、モデルを取得して実行するだけ。Q4_K_Mは堅実なデフォルトで、推論やコーディング出力をより良くしたい、かつメモリに余裕がある場合はQ5_K_MやQ6_Kへ引き上げてください。

もしLLMのデプロイ、モデル最適化、ローカル推論ワークフローをさらに深掘りしたい場合は、Associate AI Engineer for Data ScientistsまたはAssociate AI Engineer for Developersのキャリアトラックをご覧ください。