GGUFとは何ですか？

GGUFはローカルLLMで使われるモデルファイル形式です。LM Studio、Ollama、llama.cppなどで扱われることが多く、初心者はLM Studioで使うモデルファイルの形式と考えると分かりやすいです。

GGUFはアプリですか？

いいえ。GGUFはアプリではなく、AIモデルのデータファイルです。LM StudioのようなアプリでGGUFファイルを読み込んで使います。

LM StudioではGGUFを選べばいいですか？

LM Studioでローカルチャットをしたい初心者なら、まずGGUF版のモデルを探すのが分かりやすいです。ツールによって対応形式は違うため、使うアプリの対応形式も確認してください。

Q4_K_MとQ5_K_Mはどちらがいいですか？

迷ったらQ4_K_Mがおすすめです。Q5_K_Mは少し品質寄りですが、ファイルサイズやメモリ消費も増えやすいです。

メモリ16GBならどのGGUFが現実的ですか？

7B〜8BクラスのQ4_K_Mが現実的な出発点です。14B以上やQ8_0は重くなりやすいため、最初は避けるのが無難です。

GPUなしでもGGUFモデルは動きますか？

動く場合はありますが、CPU動作になりやすく速度は遅くなる可能性があります。GPUなしなら小さめモデルとQ4系から試すのがおすすめです。

safetensorsとGGUFは何が違いますか？

safetensorsは学習やTransformers系でよく見る形式です。GGUFはllama.cpp系のローカル実行、LM Studioなどでよく見る形式です。

大きいモデルほど賢いですか？

大きいモデルは性能が上がりやすい傾向がありますが、常に体感品質が上がるとは限りません。速度、量子化、会話向け調整、日本語性能も影響します。

Hugging Faceではどのファイルを見ればいいですか？

LM Studio向けならGGUF版のリポジトリを探し、ファイル名にQ4_K_M、Q5_K_M、Q8_0などが入った.ggufファイルを確認します。会話用途ならInstruct、Chat、ITなどの表記も見ます。

deep guide / metadata

GGUFのメタデータ項目｜general/architecture/tokenizer/chat templateを読み解く

GGUFファイルには、モデルの構成を記述する「メタデータ（key-value ペア）」が含まれています。このページでは、主要な項目の意味と、「ファイル名だけでは分からないこと」を初心者向けに解説します。 Inspector ツールと併せて使うと、ご自身のファイルを実際に確認できます。

読了後に分かること：GGUFの構造（header→metadata→tensor）、general/architecture/tokenizer の各キー、コンテキスト長と実際のロード上限の違い、MoEの total/active expert、量子化メタデータの限界、chat template の意味、 metadata だけでは分からないこと、Inspector での確認手順。

metadata とは

GGUFは、モデルの重み（テンソル）と、その重みをどう解釈するかの設定値（メタデータ）を 1つのファイルにまとめた形式です。メタデータは key = value の形で記録され、例えば「このモデルのアーキテクチャは llama である」「コンテキスト長は 4096 である」といった情報を持ちます。

なぜ重要か：同じ .gguf ファイルでも、メタデータが異なればランタイムの扱いが変わります。「ファイル名だけ」では不十分で、実際のメタデータを確認するのが確実です。

ファイル構造

GGUFは大きく3つの領域で構成されます：

[Header]
  magic "GGUF"
  version (uint32)
  tensor_count (uint64)
  metadata_kv_count (uint64)
  alignment (uint32, v2+)
        ↓
[Metadata KV]
  key (string)
  value_type (uint8)
  value (型ごとに可変長)
        ↓
[Tensor info]
  name (string)
  n_dims (uint32)
  dims (uint64[])
  ggml_type (uint32)
  offset (uint64)
        ↓
[Tensor data]
  重み（バイナリ）

概念図。実際のバイト配置はリトルエンディアンで、alignment に従ってパディングされる。

Inspector は、テンソル本体（重みデータ）を読まず、header と metadata 領域だけを解析します。そのため巨大なモデルでも、メモリを逼迫せず安全に確認できます。

general keys

general.* メタデータ
キー	意味	例
`general.name`	モデル名	"Llama 3.1 8B"
`general.architecture`	アーキテクチャ識別子	"llama", "gemma", "qwen2"
`general.basename`	ベースモデル名	"Llama 3.1"
`general.size_label`	パラメータ規模の目安	"8B", "70B"
`general.finetune`	fine-tune の種類	"instruct", "chat"
`general.file_type`	量子化方式の目安	15 (Q4_K_M 等の内部番号)
`general.quantization_version`	量子化スキームのバージョン	2
`general.license` / `general.authors` / `general.url`	ライセンス・著者・URL	要確認

general.file_type は「量子化方式の内部番号」であり、方式名（Q4_K_M 等）への対応は変換ツール・ランタイムごとに異なります。番号だけで品質を断定しないでください。

architecture keys

general.architecture の値（例: llama）を接頭辞として、 {arch}.block_count, {arch}.embedding_length, {arch}.attention.head_count 等のアーキテクチャ固有キーが続きます。

llama アーキテクチャの主要キー
キー	意味
`llama.block_count`	Transformer ブロック数（層数）
`llama.embedding_length`	埋め込み次元数
`llama.feed_forward_length`	FFN の中間次元数
`llama.attention.head_count`	attention head 数
`llama.attention.head_count_kv`	KV head 数（GQA）
`llama.context_length`	学習時のコンテキスト長
`llama.rope.scaling`	RoPE 拡張設定
`llama.expert_count` / `llama.expert_used_count`	MoE の総/活性 expert 数

アーキテクチャ依存：キー名の接頭辞（llama/gemma/qwen2 等）はモデルごとに異なります。未知のアーキテクチャはランタイムが対応していない可能性があります。

tokenizer keys

トークナイザー関連のメタデータは、テキストの分割と復元に使われます。

tokenizer.ggml.model：トークナイザー種別（llama / gpt2 / sentencepiece 等）
tokenizer.ggml.pre：前処理ルール
tokenizer.ggml.tokens：語彙リスト（巨大配列になるため summary では省略）
tokenizer.ggml.bos_token_id / eos_token_id / pad_token_id
tokenizer.chat_template：チャット形式のテンプレート

語彙の確認：tokens 配列は数万要素になることがあり、Inspector のデフォルト（summary）出力では含めません。必要なら「raw JSON」オプションで出力します（ただし非常に大きくなります）。

chat template

tokenizer.chat_template は、ユーザー・アシスタントの発話をモデルが期待する形式に整形するためのテンプレートです。これが存在しない場合、チャット動作が期待通りにならない（会話の文脈が壊れる等）ことがあります。

確認ポイント：Instruct/Chat モデルを使うなら、chat template の有無を確認してください。ない場合は、ランタイムが独自のフォールバックを使うか、期待通りに動かない可能性があります。

コンテキスト長

{arch}.context_length は、モデルが学習時に想定したコンテキスト長です。しかし実際にロードする際の上限は、ランタイムの設定（LM Studio 等の --context-length 等）で決まります。

metadata ≠ 実際の上限：metadata の値は「モデルの設計上の目安」であり、実際に使える長さはランタイムの設定とメモリに依存します。長い文脈を使う場合は、KVキャッシュのメモリも増える点に注意（KVキャッシュ解説）。

GQA / KV heads

{arch}.attention.head_count_kv（KV head 数）が head_count（attention head 数）より小さい場合、 GQA（Grouped Query Attention） という仕組みが使われています。KV head が少ないほど、 KVキャッシュのメモリ消費を抑えられます。

attention heads: 32
kv heads:        8   (GQA)
  → 各 KV head を 4 つの attention head で共有

KV cache サイズ ∝ kv_heads × layers × dim_per_head × precision

KV heads が小さいほど KV キャッシュが小さくなる（概算）。

MoE keys

MoE（Mixture of Experts）モデルでは、{arch}.expert_count（総 expert 数）と {arch}.expert_used_count（推論時に活性化する expert 数）が異なります。

サイズと計算量が比例しない：MoE は「全パラメータ」が大きくても、実際に使うのは active experts 分だけです。ファイルサイズ（全 expert）と推論コスト（active experts）を混同しないでください。

量子化メタデータ

general.file_type と general.quantization_version が量子化に関する情報です。ただし「方式番号」と「実際の精度」の対応は、変換ツール（llama.cpp 等）の実装に依存します。

限界：metadata から「Q4_K_M の実精度はX%」のような数値を出すことはできません。方式名だけで品質を断定せず、実測や既存の評価（量子化の根拠）を参照してください。

split GGUF

大きなモデルは複数のシャードに分割されることがあり、split 関連のメタデータが含まれます：

split.no：分割番号（0から開始）
split.count：全分割数
split.tensors.count：このシャードのテンソル数

全シャードが揃わないとロードできません。詳細は split GGUF 解説。

mmproj / multimodal

画像入力等のマルチモーダルモデルでは、モデル名に vision 等の表記が含まれることがあります。その場合、本体とは別に mmproj（投影ファイル）が必要です。

metadata だけでは「mmproj が同梱されているか」は分からないことが多いです。配布元の説明で確認してください（mmproj 解説）。

metadata から分かること

アーキテクチャとおおよその規模（block_count / embedding_length）
コンテキスト長の設計値
GQA の有無と KV head 数
MoE かどうかと expert 数
量子化方式の目安（file_type）
チャットテンプレートの有無
split の有無と分割数

metadata だけでは分からないこと

品質・安全性は読み取れない

実際の日本語能力・会話品質（実測が必要）
量子化による精度低下の具体値（方式名だけでは不明）
実際のロード上限（ランタイム設定に依存）
セキュリティ上の問題（metadata は善悪を保証しない）
ライセンスの実態（記載されていても要確認）

これらは、実際に動かす・既存の評価を読む・publisher の model card を確認することが必要です。

publisher との照合

metadata の値（名前・量子化・ライセンス等）と、配布元の model card の記述が一致するか確認してください。不一致がある場合は、リポジトリ固有の表記や、古いメタデータの可能性があります。

Inspector で確認する安全な取得の手順

malicious / malformed file

GGUF は信頼しないバイナリとして扱うべきです。以下のような場合は解析を中断・回避します：

magic が GGUF でない（別形式・破損・悪意あるファイル）
バージョンが非対応（実装外の将来形式）
ファイルが途中で切れている（truncated）
メタデータの長さ欄が異常に大きい（メモリ枯渇攻撃の可能性）
未知の値型が含まれる

Inspector の安全方針：長さ欄に上限（cap）を設け、ファイルを信頼せず bounds check を行います。不正なファイルでも、ブラウザがクラッシュしないよう防御しています。

Inspector 手順

GGUF Metadata Inspector を開く。
.gguf ファイルをドラッグ＆ドロップ、または「ファイルを選択」。
ブラウザ内で解析され、サマリーが表示される（外部送信なし）。
必要に応じて JSON / Markdown をダウンロード、または Estimator / Decoder へ値を渡す。

ファイル名に個人情報が含まれる場合があります。レポート共有時はご注意ください。

JSON report の読み方

Inspector が出力する JSON は、次の構造です：

JSON report の主要フィールド
フィールド	意味
`version`	GGUF バージョン
`summary`	主要メタデータの抜粋
`metadata`	全 key-value（type と value を含む）
`_raw`（raw オプション時）	巨大配列を含む完全な解析結果

「raw JSON」オプションを外すと、tokenizer.tokens 等の巨大配列を省略した summary だけになります。

troubleshooting

Inspector のトラブル
症状	原因	対処
「invalid magic」	GGUF でない / 破損	正しい .gguf か確認
「unsupported version」	対応外バージョン	新しいランタイムか別ファイルを試す
「truncated」	ダウンロード不完全	再取得
大きすぎて解析しない	ファイルサイズ上限	メタデータ領域のみの解析を検討

用語集

GGUF: GGML Universal File。llama.cpp 等で使われるモデルファイル形式。
metadata: モデルの構成を記述する key-value ペア。
tensor: モデルの重み（パラメータ）を格納するデータ塊。
GQA: Grouped Query Attention。KV head を共有してメモリを削減する手法。
MoE: Mixture of Experts。複数の専門モデルを状況に応じて使う構成。
mmproj: マルチモーダル用の補助ファイル（投影）。
alignment: データの配置間隔（通常 32 バイト）。

Inspector を使うファイル名デコーダーガイドハブ

更新履歴：2026-07-19 metadata guide 新規（GGUF構造・general/arch/tokenizer/chat/context/GQA/MoE/quant/split/mmproj・Inspector連携・限界・malformed対応）。