GGUF、safetensors：フォーマットを理解する モデル

#なぜこのようなフォーマットが存在するのか

学習を終えたLLMは、膨大な数値の集まりにすぎません。それが重み（weights）、つまりモデルが「知っていること」を符号化した数十億のパラメータです。ファイル形式とは、単にこれらの数値をディスク上にどう並べて保存するかということです。数値をどう保存し、どう高速に読み出すか、そしてどの付随情報（語彙、アーキテクチャ、設定）を一緒に格納するかを決める必要があります。

以前は、これらの重みはPyTorchの.bin形式（Pythonのpickle）で保存されていました。便利な形式ですが、読み込みが遅く、何より危険です。pickleファイルは、開いた際に任意のコードを実行する可能性があります。異なる問題を解決するために、2つの形式が定着しました。safetensorsは研究者やプラットフォームのニーズに応え、安全かつ高速に保存でき、元の精度を保つ形式です。GGUFはローカル推論のニーズに応え、コンパクトで量子化済みの単一ファイルとして、CPUや一般消費者向けGPUでそのまま実行できる形式です。

#safetensors：Hugging Face形式

safetensorsは、Hugging Faceエコシステムの標準形式です。PyTorchのpickleに代わるものとして作られ、その最大の特長は名前が示すとおり、安全性です。ファイルに含まれるのはデータ（重みのテンソル）と、その形状や型を記述する小さなJSONヘッダーだけです。実行可能なコードがないため、細工されたファイルを開くリスクもありません。さらに、メモリマッピングによって、先に重みをすべてRAMにコピーせずにディスクから直接読み込めるので、読み込みも高速です。

設計上、安全である

実行可能なコードは含まれていません。過去の .bin/.pt ファイルの pickle 形式とは異なり、safetensors ファイルをダウンロードしてもコードの実行に懸念はありません。

フル精度

重みは通常、FP16またはBF16（16ビット）、場合によってはFP32で保存されます。これは学習時の数値精度であり、基準となる精度です。

加工・変換を前提とした形式

ファインチューニング、モデルの融合（merge）、量子化、または他のフォーマットへの変換のための初期フォーマットです。

分割されていることが多い

大規模なモデルは、複数のファイル（シャード）に分割され、JSONインデックスが付属します。数十GBにもなる単一のファイルでは、扱いきれないためです。

逆に、safetensors形式のFP16ファイルは非常に大きいです。7Bモデルは約14GB（パラメータあたり2バイト）、70Bモデルは約140GBです。サーバーGPUでのトレーニングや研究には最適ですが、自宅のマシン上でモデルを実行するには通常重すぎるため、量子化やGGUFの活用が重要です。

#GGUF：ローカル推論用のフォーマット

GGUF（GPT-Generated Unified Format）は、CPUでもGPUでもLLMを効率的に実行する推論エンジンであるllama.cppプロジェクトから生まれた形式です。2023年に旧形式のGGMLを置き換えました。その核となるアイデアは、すべてを単一のファイルにまとめることです。重み、トークナイザの語彙、アーキテクチャのメタデータ（層数、コンテキストサイズ）、チャットテンプレート——すべてがパッケージ化されています。ファイルをダウンロードして実行するだけで動作します。

単一ファイルで自己完結型

重み、トークナイザー、メタデータを一つの.ggufファイルに格納。設定用のフォルダを組み立てる必要も、Pythonの依存パッケージをインストールする必要もありません。

量子化済み

圧縮された重み（4、5、6、8ビット）を格納できるように設計されています。これにより、大規模モデルを一般消費者向けのハードウェアでも利用できます。

CPU + GPU + オフロード

llama.cpp は、GPUとシステムRAMの間でレイヤーを分散できます。VRAMを超える大きなモデルを実行できますが、若干の速度低下が発生します。

ポータブル

同じ.ggufファイルを、Windows、macOS（Metal）、Linux上で、Ollama、LM Studio、Jan、またはllama.cppを直接使って実行できます。

量子化が本題の核心です。これは、各重みをより少ないビット数で保存すること（例えば16ビットではなく4ビット）を指し、適切に選択すれば品質の低下は最小限に抑えられながら、サイズを3分の1から4分の1に削減できます。これにより、7Bモデルが14 GBではなく約5 GBのVRAMに収まるようになります。一般的に見られるレベルは、Q4_K_M（最もバランスが良く、デフォルトで推奨）、Q5_K_M（品質が一段階上）、Q8_0（ほぼ無損失、より重い）、そしてFP16（非量子化、基準）です。

#OllamaとLM StudioがなぜGGUFを必要としているのか

OllamaとLM Studioはllama.cpp（または同等のエンジン）を基盤として構築されており、llama.cppはGGUFに標準で対応しています。これは単なる気まぐれではなく、これらのツールを使いやすくしている理由です。GGUFにはトークナイザー、アーキテクチャ、チャットテンプレートがすでに含まれているため、ツールが何かを推測する必要はありません。ファイルを読み込み、メモリを確保して、応答を返します。Python環境も、依存関係の解決も、設定の記述も不要です。

`ollama pull llama3.2` を実行すると、Ollamaは実際には自身のレジストリからGGUFファイルをダウンロードし、モデルストアに保存します。ファイル自体を目にすることはありませんが、内部では確かにGGUFが使われています。一方、LM Studioはダウンロード時に、利用可能なGGUFファイルとそれぞれの量子化形式を明示的に表示します。

# Ollama récupère un GGUF depuis sa registry et le sert sur localhost:11434
ollama pull llama3.2
ollama run llama3.2

# Vérifier que le daemon répond
curl http://localhost:11434/api/tags

#ファイル名を正しく読み取る

Hugging FaceのGGUFファイル名は、記号の意味が分かれば読み解ける命名規則に従っています。典型的な例として、`Qwen2.5-7B-Instruct-Q4_K_M.gguf`を見てみましょう。それぞれの部分が情報を表しています。

Qwen2.5

モデルのファミリとバージョン

7B

パラメータ数：70億。これは必要なVRAMの最初の指標です。

Instruct

指示に従い、対話するように学習されたバリエーションです（未調整で、チャット向けのアラインメントが行われていない-baseとは異なります）。

Q4_K_M

量子化：4 ビット、K_M（medium）バリアント。品質とサイズのバランスを取る、デフォルトの推奨設定です。

.gguf

フォーマットについて。Ollama、LM Studio、またはllama.cppで動作します。変換なしで使用可能です。

量子化のサフィックスは最も重要な部分です。数字は重みあたりのビット数を示し、K_S / K_M / K_L は（Small, Medium, Large）のバリエーションを表し、感度の高い層に対する保護の程度が異なります。数字が大きいほど、ファイルサイズが大きく、忠実度も高くなります。

Q4_K_M

~4ビット、中程度。デフォルトの選択肢：ほとんどのケースでサイズと品質のバランスが最適です。

Q5_K_M

約5ビット。品質が一段階上がり、ファイルサイズもやや大きくなります。VRAM容量に余裕があれば、よい選択肢です。

Q8_0

8ビット。非量子化版とほぼ区別がつきませんが、Q4の2倍の容量を必要とします。品質にこだわる方や要求水準の高いタスク向けです。

Q2_K / Q3_K

2〜3ビット。非常にコンパクトですが、品質の低下がはっきり分かります。メモリ容量が本当に厳しい場合に限って使用すること。

FP16 / F16

量子化なし、16ビットのフル精度。比較の基準となりますが、容量が大きいため、この場合はsafetensorsのまま使うほうがよいでしょう。

#ツールに応じてダウンロードするもの

実用的な問題は、どのツールを使用するかという点に帰着します。フォーマットはその答えから導かれます。逆は成り立ちません。

Ollama、LM Studio、Jan、llama.cpp

→ GGUF。これらのツールはこれに適しています。VRAMに応じて量子化を選択してください（デフォルトはQ4_K_Mです）。

vLLM、TGI、Transformers（Python）

→ safetensors。これらのサーバー用エンジンは、Hugging Faceのネイティブ形式を、多くの場合FP16または各エンジン独自の量子化方式（AWQ、GPTQ）で読み込みます。

ファインチューニング、マージ、自分で行う量子化

→ safetensors。これは作業用の形式です。モデルを変換する際は、フル精度のモデルを出発点にします。

まだわかりません

→ 自分のマシンでローカルに使うなら、量子化済みのGGUFを選びましょう。最も簡単で、リソース消費も最も少ない選択肢です。

適切な量子化を選ぶには、VRAM容量に合わせてください。Q4での目安は、3Bモデルが約2 GB、7Bが約5 GB、14Bが約9 GB、32Bが約19 GB、70Bが約40 GBに収まります。RTX 3060 12 GBなら、Q4の7B～14Bモデルを快適に動かせます。RTX 4090 24 GBでは32Bが目安です。70Bを使うには、大容量VRAMを搭載したグラフィックカードか、ユニファイドメモリを搭載したMac（M4 Pro 24～48 GB）を検討する必要があります。

#safetensorsをGGUFに変換

モデルがsafetensors形式でのみ公開されることがあります（リリース当日によくあります）。そのモデルをOllamaで実行したい場合は、GGUFに変換し、必要に応じて量子化する必要があります。標準的なツールは、llama.cppが提供する`convert_hf_to_gguf.py`スクリプトです。処理は二段階で行います。まず全精度のGGUFに変換し、次に`llama-quantize`ツールで量子化します。

1. 01
   llama.cpp およびその依存関係を取得する

   llama.cpp リポジトリをクローンし、変換スクリプトに必要な Python の依存パッケージをインストールしてください。convert_hf_to_gguf.py は、このリポジトリに含まれています。
2. 02
   safetensorsモデルをダウンロード

   Hugging Faceからモデルのフォルダ一式を取得してください（.safetensors形式の重み、config.json、トークナイザーのファイル）。重みだけでなく、すべてが揃っている必要があります。
3. 03
   GGUF FP16に変換

   モデルのフォルダを対象に convert_hf_to_gguf.py を実行してください。フル精度（16ビット）の .gguf ファイルが得られます。サイズは大きくなりますが、元のモデルに忠実です。
4. 04
   Q4_K_Mで量子化

   GGUF FP16 を llama-quantize で量子化し、望むレベル（デフォルトは Q4_K_M）を選択してください。最終ファイルは 3 〜 4 倍軽くなります。
5. 05
   Ollamaにインポートする

   量子化された .gguf ファイルを参照するModelfileを作成し、ollama create でモデルを作成してください。その後は、ほかのOllamaモデルと同じように利用できます。

# 1. Cloner llama.cpp et installer les dépendances de conversion
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
pip install -r requirements.txt

# 2. Convertir le dossier safetensors en GGUF pleine précision
python convert_hf_to_gguf.py ./mon-modele-hf --outfile mon-modele-f16.gguf --outtype f16

# 3. Quantifier en Q4_K_M (compromis recommandé)
./llama-quantize mon-modele-f16.gguf mon-modele-Q4_K_M.gguf Q4_K_M

# Créer un Modelfile minimal
printf 'FROM ./mon-modele-Q4_K_M.gguf\n' > Modelfile

# Enregistrer le modèle dans Ollama
ollama create mon-modele -f Modelfile
ollama run mon-modele

#ほかにも見かけるフォーマット

GGUFとsafetensorsで主要な形式はほぼ網羅されていますが、モデルをダウンロードしていると、ほかの形式名もいくつか見かけます。それらを知っておけば、思わぬトラブルを避けられます。

.bin / .pt (pickle)

従来のPyTorch形式です。動作はしますが、安全ではありません（コードを実行する可能性があります）。徐々にsafetensorsに置き換えられています。代替形式がある場合は避けてください。

GPTQ / AWQ

vLLM と Transformers 向けの GPU 用量子化形式で、safetensors 形式で保存されます。NVIDIA GPU では高速ですが、Ollama/llama.cpp では読み込めません。

MLX

MLXフレームワーク向けのAppleフォーマットは、Appleシリコンチップ向けに最適化されています。Mac用の一部のネイティブアプリで使用されており、GGUFとは異なります。

ONNX

複数のフレームワーク間でやり取りするための形式で、主に産業用途やエッジ環境へのデプロイで使われます。一般ユーザーがLLMをローカルで使う場合には、あまり見られません。

GGML

GGUFの前身（同じプロジェクト）。現在は廃止された形式なので、.ggmlファイルを見かけたら、対応する.gguf版を探してください。

#よくある質問

GGUFとsafetensors、どちらが良いですか？

どちらかが絶対的に優れているわけではありません。それぞれ用途が異なります。GGUFはモデルのローカル実行（Ollama、LM Studio）向け、safetensorsはHugging Faceのエコシステム、ファインチューニング、サーバー用の推論エンジン向けです。「最適」な形式は、使うツールによって異なります。

GGUF は safetensors に比べて劣るのですか？

量子化されたGGUFは、元のFP16のsafetensorsと比べて若干の精度を失います。Q4_K_MまたはQ5_K_Mでは差は極めて小さく、実際の使用においてほとんど感じられません。Q2またはQ3ではその差が目立つようになります。

Ollamaで直接safetensorsを使用できますか？

ほとんどの場合、そのままでは使用できません。OllamaはGGUF形式を必要とするため、あらかじめllama.cppでsafetensorsをGGUFに変換する必要があります。一部の比較的新しいバージョンではsafetensorsのインポートに対応していますが、GGUFが依然として確実な方法です。

Hugging Faceのページになぜ多くのファイルがあるのですか？

モデルは複数のシャード（safetensorsまたはGGUF）に分割されていることが多く、そのほかに設定ファイルとトークナイザーのファイルがあります。GGUFの場合、通常必要なのは量子化の種類ごとに1つのファイルです（分割されている場合は、その一式すべて）。

#さらに詳しく

フォーマットについて理解できたところで、関連するこちらのガイドでさらに学びを深められます。

量子化の選択（Q4、Q5、Q8、FP16）

GGUFの量子化レベルを、VRAMと品質要件に応じて選ぶための詳細ガイド。

Ollama とは何か、どのように動作するか

GGUFをダウンロードしてローカルで提供するツールを、基本コマンドとともに理解する。

コンテキストウィンドウを理解する

メモリ使用量に影響を与えるもう一つのパラメータは、トークンとコンテキストであり、量子化の選択と組み合わせて考慮する必要があります。