モデルファイル形式の基本

形式が違うと、何が違うのか

第2章で見たように、モデルは「重み・設定・トークナイザ」の3点セットです。形式によって、このうちどこまでを1つのファイルに入れるかが違います。

pickle形式（.bin / .pt）：便利だけど危ない

PyTorchの torch.save() は、テンソルやPythonのオブジェクトをpickleで保存します。Hugging Faceの古いモデルにある pytorch_model.bin がその代表です。pickleはデータそのものではなく「オブジェクトを組み立てる命令の列」なので、その命令に「このコマンドを実行せよ」を紛れ込ませることができます。

対策も進んでいます。PyTorch 2.6からは torch.load() の既定が weights_only=True になり、テンソルや基本的な型以外は読み込まないよう制限されました。Hugging Face Hubもアップロードされたpickleファイルをスキャンしています。それでも「知らない人のpickleは開かない」のが基本です。

safetensors：いまの標準

safetensors はHugging Faceが作った、重みを保存するためだけのシンプルな形式です。中身はたった3つの部分でできています。

flowchart TD
  A["先頭 8バイト
ヘッダーの長さ N"] --> B["N バイトの JSON ヘッダー
テンソル名・型・形・位置"]
  B --> C["残り全部
テンソルの生データ"]

実際に Qwen/Qwen3.5-0.8B のファイルの先頭だけを読んでみると、ヘッダーは約60KBで、こんな項目が並んでいます（1項目だけ抜粋）。

{
  "model.language_model.embed_tokens.weight": {
    "dtype": "BF16",
    "shape": [248320, 1024],
    "data_offsets": [10368, 508569728]
  },
  ...
}

語彙248,320 × 幅1,024 × 2バイト ＝ 508,559,360バイト。data_offsets の差とぴったり一致します。

「どのテンソルが、どの型で、どの形で、データ部分の何バイト目から何バイト目にあるか」が書いてあるだけです。コードを実行する余地がないので安全で、さらに次のような利点があります。

• 部分読み込み（lazy loading）— ヘッダーを見れば位置が分かるので、必要なテンソルだけを読める。複数GPUに分けて載せるときに便利。
• 速い読み込み — データ部分をそのままメモリに対応づけられる（mmap）。CPUではほぼコピーなしで読める場合もある。
• BF16やFP8などの型を素直に扱える。

safetensorsは2026年4月にHugging FaceからPyTorch Foundation（Linux Foundation傘下）に移管され、特定企業に依存しない標準として運営されることになりました。transformers v5では保存形式がsafetensorsに一本化され、pickleで保存するオプションは削除されています2026年10月時点。

分割ファイル（シャーディング）の読み方

大きなモデルは、重みが複数のファイルに分けて配布されます。これをシャーディング（sharding）と呼びます。ファイル名はこんな形です。

model-00001-of-00004.safetensors
model-00002-of-00004.safetensors
model-00003-of-00004.safetensors
model-00004-of-00004.safetensors
model.safetensors.index.json   ← どのテンソルがどのファイルにあるかの目次

「00002-of-00004」は「4分割のうち2番目」という意味です。全部そろわないと読み込めないので、ダウンロードはフォルダごと行いましょう。index.json の中身は「テンソル名 → ファイル名」の対応表です。

分割の大きさの既定は、transformers v5で5GBから50GBに引き上げられました。HubのストレージがXetになり、大きなファイルを効率よく配れるようになったためです。そのため、最近のモデルはファイル数が少なめです。たとえば Qwen/Qwen3.5-0.8B は約1.75GBの1ファイル（…-00001-of-00001.safetensors）になっています2026年10月時点。

GGUF：ローカル実行のための「全部入り」

GGUF は、llama.cppとその土台のggmlのために作られた形式です。重みに加えて、アーキテクチャの設定、トークナイザの語彙、チャットテンプレートまでを1つのファイルに入れられます。量子化された重みを入れることが多く、ローカルでLLMを動かすツールの多く（llama.cpp、Ollama、LM Studioなど）が使っています。

Hugging Faceでは、リポジトリ名の末尾が -GGUF になっているものが目印です。Qwen3.5-0.8B-Q4_0.gguf のように、ファイル名に量子化の種類が入ります。構造や量子化の種類は第5章でじっくり扱います。

ONNX と MLX

ONNX

ONNX（Open Neural Network Exchange）は、重みだけでなく「どんな順番で何の計算をするか」という計算グラフも一緒に保存する形式です。グラフが入っているので、PyTorchがない環境でも、ONNX Runtimeなどの実行エンジンがあれば動きます。WindowsやスマートフォンやWebブラウザなど、さまざまな場所で動かしたいときに使われます。

ONNXファイルの本体はProtocol Buffersという形式で、2GBを超える大きなモデルは重みを外部ファイルに分けて保存します。たとえば onnx-community/Qwen3.5-0.8B-ONNX には、decoder_model_merged.onnx と decoder_model_merged.onnx_data の組が、FP16版・4bit版などいくつも並んでいます。このリポジトリはブラウザで動く Transformers.js でも使えます。LLM向けには、生成のループやKVキャッシュの管理まで面倒を見る ONNX Runtime GenAI もあります。

MLX

MLXは、AppleがApple シリコン向けに作った機械学習フレームワークです。LLM用の mlx-lm で使うモデルは、Hugging Faceの mlx-community などで配布されています。中身を見ると、実はsafetensorsと config.json の組み合わせです。たとえば mlx-community/Qwen3.5-0.8B-4bit の config.json には、4bit・グループサイズ64という量子化の設定が書かれています。

# Hugging Face のモデルを MLX 形式に変換し、4bit 量子化する
mlx_lm.convert --model Qwen/Qwen3.5-0.8B -q

つまり「MLX形式」は箱の規格というより、「MLXで読める並びと量子化にしたsafetensors」と考えると分かりやすいです。なおMLX自体はGGUFの読み書きにも対応しています。

どれを選べばいい？

形式選びは「どのソフトで動かすか」でほぼ決まります。

• GPUサーバーやPython（transformers、vLLMなど）→ safetensors
• 手元のPC（llama.cpp、Ollama、LM Studioなど）→ GGUF
• MacでMLX（mlx-lm）→ MLX用のsafetensors
• ブラウザやWindowsアプリ（Transformers.js、ONNX Runtime）→ ONNX

どの形式を選ぶにしても、pickle形式は信頼できる出どころのものだけにしましょう。同じモデルにsafetensors版があるなら、そちらを選ぶのが基本です。実行エンジンの違いは第6章以降で扱います。