はじめに
Hugging Face のモデルを使う際、Hub からダウンロードしたモデルフォルダには多くのファイルが含まれています。しかし、初めてこれらを眺めたとき、「どのファイルが重要なのか？」「どれがモデル動作に必須なのか？」と悩んだ経験はありませんか？
この記事では、Hugging Face のモデルファイルについて、モデル動作に必須なファイルと、具体的な用途や重要な情報が載っているファイルに分けて解説してみます。
🐣 私は最初、わけがわからなすぎて脳内から消してました…
Hugging Face モデルファイルの全体像
Hugging Face Hub からダウンロードしたモデルフォルダには、以下のようなファイルが含まれることが一般的です：
config.json
pytorch_model.bin / model.safetensors
tokenizer.json
vocab.txt / spiece.model
special_tokens_map.json
tokenizer_config.json
generation_config.json
README.md
初めてモデルを動かしたときは、これらのファイルについて深く考える余裕がないかもしれません。しかし、タスクに応じてモデルをカスタマイズしようとすると、これらのファイルを理解し活用することが避けられなくなります。
ファイルがたくさんありすぎて混乱するかもしれませんが、必須な設定ファイルと、重要な情報を含む補助的なファイルに分けると理解しやすくなると思います。
というわけで、必須な設定ファイルと、重要な情報を含む補助的なファイルそれぞれについて解説します。
モデルに必須な設定ファイル
まずは、モデルをロードして動作させるために必須な設定ファイルについて説明します。
config.json
モデルのアーキテクチャや設定情報を保存した JSON ファイルです。このファイルは、Hugging Face の from_pretrained メソッドでモデルをロードする際に参照されます。
設定の例 (BERT)
{
"model_type": "bert",
"hidden_size": 768,
"num_attention_heads": 12,
"num_hidden_layers": 12,
"vocab_size": 30522
}
この設定から、以下の特徴を持つ BERT モデルであることが分かります。
- 隠れ層次元数: 768
- マルチヘッド注意機構のヘッド数: 12
- 隠れ層の数: 12
- 語彙サイズ（トークン数）: 30,522
設定の例 (ViT)
{
"model_type": "vit",
"hidden_size": 768,
"num_hidden_layers": 12,
"num_attention_heads": 12,
"image_size": 224,
"patch_size": 16
}
この設定から、以下の特徴を持つ Vision Transformer (ViT) モデルであることが分かります。
- 隠れ層次元数: 768
- 隠れ層の数: 12
- マルチヘッド注意機構のヘッド数: 12
- 入力画像サイズ: 224 × 224 ピクセル
- パッチサイズ: 16 × 16 ピクセル
設定の例 (QLoRA)
{
"model_type": "bert",
"lora_r": 16,
"lora_alpha": 32,
"quantization_bits": 4,
"target_modules": ["query", "value"]
}
この設定から、以下の特徴を持つ QLoRA モデルであることが分かります。
- LoRA のランク（$r$）: 16
- $r$ は低い値にすることで効率化が可能。
- LoRA のスケール係数（$\alpha$）: 32
- モデルの学習時のスケール調整に使用。
- 量子化ビット数: 4
- モデルのパラメータを 4-bit に量子化して軽量化。
- LoRA 適用対象のモジュール:
query,value- 適用する層として注意機構の Query と Value に LoRA を組み込む。
以上の例は一部抜粋しているためシンプルですが、実際の設定ファイルは 100 行を越すことも珍しくありません。
- 役割：モデルの構造（層の数や種類、隠れ層のサイズなど）を定義します。
- 必須な理由：モデルの重みを正しく復元するために必要です。
ファイルを変更した場合に必要な対応：
- config.json を変更すると、モデルの構造と保存された重みが一致しなくなり、モデルが正しくロードできなくなる可能性があります。その場合、新しい構造に基づいて重みを再学習する必要があります。
🐣 モデルを読み込むとき、モデルの構造を意識してなかったわ。config.jsonのおかげだったのかー
pytorch_model.bin または model.safetensors
モデルの学習済みパラメータ（重み）を保存したファイルです。これがないと、モデルは動作しません。
-
pytorch_model.bin：PyTorch 形式で保存されたモデルの重み。 -
model.safetensors：安全で効率的なSafetensorsフォーマットで保存されたモデルの重み。
これらのどちらかが必須となります。最近では、安全性の高い model.safetensors 形式が推奨されています。
重みファイルは通常、学習や再学習プロセスによって生成されます。人間が直接編集することはありませんが、config.json の構造と一致していない場合、モデルのロード時にエラーが発生します。構造変更が必要な場合は、再学習を通じて新しい重みを作成する必要があります。
- 役割：モデルの重みを保存し、推論やファインチューニングで利用します。
- 必須な理由：学習済みの重みがなければ、モデルは推論やタスクの実行ができないため。
ファイルを変更した場合に必要な対応：
- 重みファイルは学習済みのパラメータが保存されたもので、人間が直接編集することは推奨されません。また、このファイルは対応する config.json の設定と一致していないとモデルを正しくロードできません。構造変更が必要な場合は、必ず新しい重みを学習して保存してください。
Tokenizer 関連ファイル（tokenizer.json, vocab.txt, spiece.model）
テキストをトークンに変換するための情報が保存されています。以下のいずれかが含まれることが一般的です：
-
tokenizer.json：Tokenizer 全体の設定やトークン ID マッピングを JSON 形式で保存。 -
vocab.txt：トークンと ID の対応表をシンプルなテキスト形式で保存。 -
spiece.model：SentencePieceTokenizer が使用するバイナリ形式のモデルファイル。 -
役割：テキストをモデルが処理できるトークン ID に変換します。
-
必須な理由：テキストをモデルが理解できる形式に変換するために必要不可欠です。
ファイルを変更した場合に必要な対応：
- 特殊トークンを追加・変更する場合、対応する語彙サイズを更新する必要があります。また、モデルの embedding 層をリサイズし、新しいトークンに対応した重みを学習するためにファインチューニングを行う必要があります。
モデル利用時に注目すべきファイル（補助的な情報）
必須ではないものの、モデルの挙動や生成プロセスを深く理解・カスタマイズするために重要なファイルを紹介します。
generation_config.json
生成タスクを行うモデルで使用される、生成パラメータのデフォルト設定を保存したファイルです。
含まれる情報の例
{
"max_length": 128,
"temperature": 1.0,
"top_k": 50,
"top_p": 0.9
}
- 用途：生成タスクのパラメータをカスタマイズする際に参照。
-
重要な理由：
max_lengthやtemperatureなど、モデルの推論時の挙動をコントロールできます。
ファイルを変更した場合に必要な対応：
- 再学習の必要はなく、推論時に即座に反映されます。
special_tokens_map.json
特殊トークン（例：[CLS], [SEP] など）の設定を保存したファイルです。
含まれる情報の例
{
"cls_token": "[CLS]",
"sep_token": "[SEP]",
"pad_token": "[PAD]",
"unk_token": "[UNK]",
"mask_token": "[MASK]"
}
- 用途：Tokenizer やモデルが特殊トークンを正しく処理するために使用。
- 重要な理由：設定が誤っているとモデルが期待通りに動作しない可能性があります。
ファイルを変更した場合に必要な対応：
- 語彙サイズを変更する場合、Tokenizer の更新とファインチューニングが必要です。
🐣 この特殊トークンの設定が違うモデルを使うのはめちゃくちゃ大変…
tokenizer_config.json
トークナイザーの設定を保存したファイルです。トークナイザーの種類や動作モード（小文字化の有無、最大長など）が記載されています。
含まれる情報の例
{
"do_lower_case": true,
"model_max_length": 512,
"padding_side": "right"
}
-
用途：トークナイザーの細かい挙動を制御するために使用します。たとえば、
do_lower_caseをtrueに設定することで、すべての入力テキストを小文字化して処理することができます。 - 重要な理由：データ処理の前段階でトークナイザーが正しく動作するように設定が保存されています。この設定がモデルやトークナイザーの挙動と一致していない場合、推論や学習で予期せぬエラーが発生する可能性があります。
モデルファイル一覧と必須度
| ファイル名 | 必須 | 役割 / 含まれる情報 |
|---|---|---|
config.json |
✅ | モデルのアーキテクチャ設定（層数、隠れ層のサイズ、アテンションヘッド数など）を定義 |
pytorch_model.bin / model.safetensors
|
✅ | 学習済みモデルの重みパラメータ（.safetensors はセキュアな新フォーマット） |
tokenizer_files |
✅ | 以下のいずれかが必須： - tokenizer.json（標準的なトークナイザー設定）- vocab.txt（BERT系のWordPiece用語彙）- spiece.model（SentencePiece用モデル） |
generation_config.json |
❌ | テキスト生成のデフォルト設定（max_length、temperature、top_p など）。主に生成モデルで使用 |
special_tokens_map.json |
△ | 特殊トークン（[CLS]、[SEP]、[PAD]、[MASK] など）とその定義のマッピング |
tokenizer_config.json |
△ | トークナイザーの詳細設定（小文字化、空白の扱い、最大長など）。明示的な設定が必要な場合に使用 |
README.md |
❌ | モデルのメタ情報（学習データ、用途、ライセンス、性能評価など）。モデルカードとも呼ばれ、モデルの概要や使用方法を記載 |
✅: 必須 △:奨励 ❌:なくても良い
△のファイルはデフォルト値で一応動作しますが、特殊トークンやトークナイザーの設定の違いはモデルの動作に重大な影響を与えるため、実質必須と考えた方が無難でしょう。
Hugging Face モデル設定をカスタマイズしてみよう
Hugging Face のモデル設定ファイルはシンプルな JSON 構造で記述されているので簡単に編集できますが、直接変更しただけでは反映されないパラメータもたくさんあります。特に、config.json に以下のような変更を加えた場合、モデルの再学習（Fine-tuning または Pre-training）が必要になることを覚えておきましょう。
-
隠れ層の次元数の変更:
$768 → 512などにすると、既存のモデル重みが適用できなくなり、新たに重みを学習する必要があります。 -
マルチヘッド注意機構のヘッド数調整:
$12 → 8にすると、Attention 機構が異なる動作をするため、再学習が必要です。 -
語彙サイズの拡張:
特殊トークンを追加して語彙サイズを$30522 → 35000に増やすと、埋め込み層のサイズが変わり、元の重みをそのまま使えなくなります。
モデル設定を変更することで、自分用のタスクに最適化したり、リソースに応じた軽量化を図ることができます。ぜひ、お手元の config.json を編集し、新しいモデル設計に挑戦してみてください。
🐣 いうまでもありませんが元ファイルのバックアップを忘れずに！
おわりに
Hugging Face のモデルファイルは、モデルを動作させるために必須なものと、モデルの挙動を調整する補助的なものに分けられます。それぞれの役割を理解し、必要に応じてファイルを変更することで、モデルを柔軟にカスタマイズできます。
ぜひ、この知識を活用してモデルを自分のタスクに合わせてカスタマイズしてみてください！