Zenn
🐣

Hugging Face モデルファイルの完全理解

2024/11/12に公開
初心者向け
Hugging Face
モデルファイル
tech

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 メソッドでモデルをロードする際に参照されます。

含まれる情報の例

{
  "model_type": "bert",
  "hidden_size": 768,
  "num_attention_heads": 12,
  "num_hidden_layers": 12,
  "vocab_size": 30522
}

ここから、このモデルが隠れ層 768 次元、12 個のマルチヘッドを持つ 12 層積みの BERT で、語彙サイズ（トークン数）が 30,522 であることが分かります。

  • 役割：モデルの構造（層の数や種類、隠れ層のサイズなど）を定義します。
  • 必須な理由：モデルの重みを正しく復元するために必要です。

ファイルを変更した場合に必要な対応：

  • 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 のモデルファイルは、モデルを動作させるために必須なものと、モデルの挙動を調整する補助的なものに分けられます。それぞれの役割を理解し、必要に応じてファイルを変更することで、モデルを柔軟にカスタマイズできます。

ぜひ、この知識を活用してモデルを自分のタスクに合わせてカスタマイズしてみてください！

Discussion