BroadRouter
始める

GGUF

更新日

GGUF とは、llama.cpp など GGML ベースのランタイムで推論するための言語モデルのバイナリファイル形式です。1 ファイルに重み(多くは量子化済み)と、トークナイザーやアーキテクチャなど読み込みに必要なメタデータが入り、メモリマップで高速に読み込めます。

別名: GGUF ファイル、GGUF 形式、GGUF モデル、GGUF 量子化、llama.cpp 形式、GGUF file、GGUF format、llama.cpp format

ノートパソコンで動かすためにモデルをダウンロードしたことがあるなら、それはおそらく .gguf で終わるファイルだったはずです。

仕組み

ggml の仕様は、GGUF を GGML および GGML ベースの実行環境で推論するためにモデルを保存するバイナリ形式と説明しており、高速な読み込みと保存を目指して設計されています。以前の GGML、GGMF、GGJT 形式を置き換えるものです。掲げられている目標は次のとおりです。

  • 単一ファイル。 追加のファイルなしでモデルを共有し、読み込めます。
  • mmap 対応。 ランタイムは重みをコピーせず、メモリマップできます。
  • 拡張可能。 古いモデルを壊さずに新しいメタデータを追加できます。
  • 情報が完結している。 モデルの読み込みに必要なものはすべてファイルに入っています。

GGUF ファイルは、ヘッダー(マジックナンバー、形式のバージョン、テンソル数とメタデータ数)、型付きのメタデータのキーと値のペア、テンソルの名前・形状・型・オフセットの表、アラインメント境界までのパディング(デフォルトは 32 バイト)、そしてテンソルデータの順に並んでいます。

ファイル名には命名規則があります。仕様の例 Mixtral-8x7B-v0.1-KQ2.gguf は、ベース名、サイズラベル(7B のエキスパートが 8 つ。混合エキスパートを参照)、バージョン、エンコーディングに分解できます。

GGUF ファイルの多くは量子化されています。Hugging Face の表に載っている主な種類は次のとおりです。

種類 重みあたりのビット数 備考
Q8_0 8 従来型の最近接丸め、32 重みのブロック
Q6_K 6.5625 k-quant のスーパーブロック
Q5_K 5.5 k-quant のスーパーブロック
Q4_K 4.5 k-quant のスーパーブロック
IQ4_XS 4.25 重要度行列を使用
Q2_K 2.625 k-quant のスーパーブロック

なぜ重要か

  • ローカルやエッジでの利用。 Hugging Face は、GGUF を使うツールとして llama.cpp、LM Studio、GPT4All、Ollama を挙げています。CPU、Mac、コンシューマー向け GPU 1 枚でオープンウェイトモデルを動かすときの定番の手段です。
  • トークナイザーが重みと一緒に運ばれる。 メタデータがファイルに入っているため、変換時にチャットテンプレートやトークナイザーの設定が間違っていたり欠けていたりすると、出力の品質が変わることがあります。
  • 品質は量子化の種類で決まる。 同じモデルでも、Q2 のファイルと Q8 のファイルは実用上は別物です。同じ条件同士で比べてください。
  • GPU 提供向けの形式とは別物。 vLLM などのサーバーエンジンも対応形式に GGUF を挙げていますが、本番の GPU 提供では AWQ や FP8 などの形式のほうがよく使われます。

BroadNet Inference では

BroadNet の API は HTTP でモデルを提供しており、GGUF ファイルは配布していません。ユーザーが自分で重みを読み込むこともありません。BroadNet のカタログによると、BroadNet はラボで Qwen3.8 27B を GGUF Q4_K_M として、ビジョンプロジェクターとマルチトークン予測のドラフターを付けて llama.cpp で動かし、あわせて AMD ROCm 上の vLLM で AWQ INT4 ビルドも動かしています。公開 API がどの形式で提供されているかは書かれていません。ローカルの GGUF 環境と API を比べているなら、セルフホストと API のコスト比較とオープンウェイトとクローズドモデルの比較でトレードオフを解説しています。

よくある質問

Q4_K のような名前は何を意味しますか?

量子化の種類です。Hugging Face の表では、Q4_K は 32 個の重みからなるブロック 8 つをまとめたスーパーブロック単位の 4 ビット量子化で、重みあたり約 4.5 ビットと説明されています。ビット数が少ないほどメモリは減り、たいてい品質も下がります。

GGUF モデルを OpenAI API 形式で呼び出せますか?

ファイルそのものはできません。llama.cpp のサーバー、Ollama、LM Studio などのランタイムに読み込み、そのランタイムが提供します。公開される API は、ランタイムのドキュメントで確認してください。

GGUF と safetensors は同じですか?

いいえ。Hugging Face は safetensors をテンソルだけの形式と説明しています。一方 GGUF は、テンソルと標準化されたメタデータの両方を 1 つのファイルに収めています。

Markdown で読むChatGPT に聞くClaude に聞くPerplexity に聞く