# モデルの読み込み

Transformers は、1 行のコードで利用可能な多くの事前学習済みモデルを提供しています。これには、モデルクラスと [from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドが必要です。

Hugging Face [Hub](https://hf.co/models)に保存されているモデルの重みと設定をダウンロードして読み込むには、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained)を呼び出します。

> [!TIP]
> The [from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) method loads weights stored in the [safetensors](https://hf.co/docs/safetensors/index) file format if they're available. Traditionally, PyTorch model weights are serialized with the [pickle](https://docs.python.org/3/library/pickle.html) utility which is known to be insecure. Safetensor files are more secure and faster to load.

```py
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-2-7b-hf", device_map="auto")
```

このガイドでは、モデルの読み込み方法、モデルを読み込むためのさまざまな方法、非常に大きなモデルにおけるメモリ問題の解決策、およびカスタムモデルの読み込み方法について説明します。

## モデルと設定

すべてのモデルには、隠れ層の数、語彙サイズ、活性化関数などの特定の属性を持つ`configuration.py`ファイルがあります。また、各層内で実行される層と数学的演算を定義する`modeling.py`ファイルも見つけることができます。`modeling.py`ファイルは、`configuration.py`内のモデル属性を受け取り、それに基づいてモデルを構築します。この時点で、あなたは意味のある結果を出力するために学習が必要な、ランダムな重みを持つモデルを持っています。

> [!TIP]
> *アーキテクチャ*とはモデルの骨格を指し、*チェックポイント*とは特定のアーキテクチャに対するモデルの重みを指します。例えば、[BERT](./model_doc/bert)はアーキテクチャであり、[google-bert/bert-base-uncased](https://huggingface.co/google-bert/bert-base-uncased)はチェックポイントです。*モデル*という用語は、アーキテクチャとチェックポイントを指すために混在して使用されます。

読み込めるモデルには、主に2つのタイプがあります。

1. [AutoModel](/docs/transformers/main/ja/model_doc/auto#transformers.AutoModel)や[LlamaModel](/docs/transformers/main/ja/model_doc/llama2#transformers.LlamaModel)のように、隠れ状態を出力する最小構成のモデル。
2. *head* が付与されたモデル。例えば [AutoModelForCausalLM](/docs/transformers/main/ja/model_doc/auto#transformers.AutoModelForCausalLM) や [LlamaForCausalLM](/docs/transformers/main/ja/model_doc/llama2#transformers.LlamaForCausalLM) など、特定のタスクを実行するために使用されます。

## モデルクラス

事前学習済みモデルを取得するには、重みをモデルに読み込む必要があります。これは、Hugging Face Hubまたはローカルディレクトリからの重みを引数として受け取る[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained)を呼び出すことで行います。

モデルクラスには2種類あり、[AutoModel](./model_doc/auto)クラスと、モデル固有のクラスがあります。

[AutoModel](./model_doc/auto) クラスは、利用可能なモデルが多数あるため、正確なモデルクラス名を知らなくてもアーキテクチャを読み込むのに便利な方法です。設定ファイルに基づいて正しいモデルクラスを自動的に選択します。使用するタスクとチェックポイントさえわかれば問題ありません。

アーキテクチャが特定のタスクでサポートされている限り、モデルやタスクを簡単に切り替えることができます。

例えば、同じモデルを異なるタスクに使用できます。

```py
from transformers import AutoModelForCausalLM, AutoModelForSequenceClassification, AutoModelForQuestionAnswering

# use the same API for 3 different tasks
model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-2-7b-hf")
model = AutoModelForSequenceClassification.from_pretrained("meta-llama/Llama-2-7b-hf")
model = AutoModelForQuestionAnswering.from_pretrained("meta-llama/Llama-2-7b-hf")
```

その他のケースでは、タスクに対して複数の異なるモデルを素早く試してみたい場合があります。

```py
from transformers import AutoModelForCausalLM

# use the same API to load 3 different models
model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-2-7b-hf")
model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
model = AutoModelForCausalLM.from_pretrained("google/gemma-7b")
```

[AutoModel](./model_doc/auto) クラスは、モデル固有のクラスを基盤として構築されています。特定のタスクをサポートするすべてのモデルクラスは、それぞれに対応する `AutoModelFor` タスククラスにマッピングされます。

使用するモデルクラスがすでに決まっている場合は、そのモデル固有のクラスを直接使用できます。

```py
from transformers import LlamaModel, LlamaForCausalLM

model = LlamaForCausalLM.from_pretrained("meta-llama/Llama-2-7b-hf")
```

## 大規模モデル

大規模な事前学習済みモデルを読み込むには、大量のメモリが必要です。読み込みプロセスには以下が含まれます。

1. ランダムな重みでモデルを作成する
2. 事前学習済み重みの読み込み
3. モデルに事前学習済み重みを配置すること

モデルの重み（ランダム初期化と事前学習済み）の2コピーを保持するのに十分なメモリが必要ですが、ハードウェアによってはこれが不可能な場合があります。分散学習環境では、各プロセスが事前学習済みモデルを読み込むため、さらに困難になります。

Transformers は、高速な初期化、シャード化されたチェックポイント、Accelerate の [Big Model Inference](https://hf.co/docs/accelerate/usage_guides/big_modeling) 機能、および低ビット幅データ型へのサポートにより、これらのメモリ関連の課題を軽減します。

### シャード化されたチェックポイント

[save_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.save_pretrained) は、50GB を超えるチェックポイントを自動的にシャード化します。これにより、大規模モデルにおけるシャード数を抑え、ファイル管理を簡素化できます。

パラメータは並列で読み込まれ、ピークメモリはモデルサイズにのみ依存します。シャーディングを行う前のチェックポイントの最大サイズを設定するには、[save_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.save_pretrained) で `max_shard_size` を使用します。

> [!NOTE]
> 動的ウェイト変換を必要とするモデルのメモリ使用量は、モデルサイズと、1回の変換における最大のパラメータサイズに依存します。これは通常、mixture-of-experts (MoE) モデルに当てはまり、メモリ使用量はモデルサイズに1レイヤーあたりのエキスパート数を加えたものになります。モデルの読み込み方法の詳細については、[動的ウェイトローダー](./weightconverter#fast-and-efficient-model-loading)のガイドを参照してください。

[save_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.save_pretrained) は、パラメータ名をそれぞれのシャードファイルにマッピングするインデックスファイルも作成します。このインデックスには、`metadata` と `weight_map` という2つのキーが含まれます。

```py
import json
import os
import tempfile

with tempfile.TemporaryDirectory() as tmp_dir:
    model.save_pretrained(tmp_dir, max_shard_size="50GB")
    with open(os.path.join(tmp_dir, "model.safetensors.index.json"), "r") as f:
        index = json.load(f)

print(index.keys())
```

`metadata`には、モデルの総サイズが保存されます。

```py
index["metadata"]
{'total_size': 28966928384}
```

`weight_map` は、各パラメータを対応するシャードファイルにマッピングします。

```py
index["weight_map"]
{'lm_head.weight': 'model-00006-of-00006.safetensors',
 'model.embed_tokens.weight': 'model-00001-of-00006.safetensors',
 'model.layers.0.input_layernorm.weight': 'model-00001-of-00006.safetensors',
 'model.layers.0.mlp.down_proj.weight': 'model-00001-of-00006.safetensors',
 ...
}
```

### 大規模モデルの推論

> [!TIP]
> この機能を使用するには、Accelerate v0.9.0 と PyTorch v1.9.0 以降がインストールされていることを確認してください！

[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) is supercharged with Accelerate's [Big Model Inference](https://hf.co/docs/accelerate/usage_guides/big_modeling) feature.

Big Model Inference は、PyTorch の [meta](https://pytorch.org/docs/main/meta.html) デバイス上に *モデルのスケルトン* を作成します。meta デバイスは実際のデータを保存せず、メタデータのみを保持します。

事前学習済み重みの読み込み時にのみ、ランダム初期化された重みが作成されます。これにより、メモリ上にモデルのコピーを2つ同時に保持することを回避できます。最大メモリ使用量は、モデルのサイズのみです。

> [!TIP]
> [デバイスマップの設計](https://hf.co/docs/accelerate/v0.33.0/en/concept_guides/big_model_inference#designing-a-device-map)で、デバイスの配置について詳しく学んでください。

Big Model Inferenceの2つ目の機能は、モデルのスケルトンにおける重みの読み込みとディスパッチの仕組みに関係しています。モデルの重みは利用可能なすべてのデバイスにディスパッチされ、まず最も高速なデバイス（通常はGPU）から開始し、残りの重みはより低速なデバイス（CPUやハードドライブ）へオフロードされます。

これらの2つの機能を組み合わせることで、大規模な事前学習済みモデルのメモリ使用量と読み込み時間を削減できます。

Big Model Inference を有効にするには、[device_map](https://github.com/huggingface/transformers/blob/026a173a64372e9602a16523b8fae9de4b0ff428/src/transformers/modeling_utils.py#L3061) を `"auto"` に設定してください。

```py
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("google/gemma-7b", device_map="auto")
```

`device_map`でレイヤーをデバイスに手動で割り当てることもできます。モデルのパラメータをすべてデバイスにマッピングする必要がありますが、レイヤー全体が同じデバイスにある場合、そのレイヤーのすべてのサブモジュールがどこに配置されるかを詳細に指定する必要はありません。

`hf_device_map` 属性にアクセスして、モデルがデバイス間でどのように分散されているかを確認できます。

```py
device_map = {"model.layers.1": 0, "model.layers.14": 1, "model.layers.31": "cpu", "lm_head": "disk"}
model.hf_device_map
```

### ディスクオフロード

モデルが GPU と CPU RAM の合計容量を超えている場合、Big Model Inference は残りの重みをディスクにオフロードします。`"disk"` にマッピングされる重みが存在する場合は、`offload_folder` をディレクトリに設定してください。Transformers はオフロードされた重みをこのディレクトリに保存するためです。

```py
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "google/gemma-7b",
    device_map="auto",
    offload_folder="./offload",
)
```

`max_memory` を使用して、各デバイスが保持する容量の上限を設定します。Transformers はデバイスを速度の順に埋め、収まらない分はディスクに送信します。以下の例では、GPU を 10GB、CPU を 30GB に制限しているため、残りの重みは `offload_folder` に保持されます。

```py
model = AutoModelForCausalLM.from_pretrained(
    "google/gemma-7b",
    device_map="auto",
    max_memory={0: "10GB", "cpu": "30GB"},
    offload_folder="./offload",
)
```

`max_memory={}` を設定すると、GPU メモリおよび CPU メモリが利用できないことを指定し、モデル全体をディスクにオフロードするよう強制できます。

```py
model = AutoModelForCausalLM.from_pretrained(
    "google/gemma-7b",
    device_map="auto",
    max_memory={},
    offload_folder="./offload",
)
```

> [!NOTE]
> ディスクオフロードは、メモリを速度と引き換えにします。フォワードパスのたびにディスクから重みを読み込むのは、CPUメモリやGPUメモリから読み込むよりも遅くなります。完全なディスクオフロードには`accelerate>1.14.0`が必要です。

### モデルのデータ型

`dtype` 引数は、モデルの重みをインスタンス化するために使用される PyTorch の [dtype](https://pytorch.org/docs/stable/tensor_attributes.html#torch.dtype) を制御します。デフォルトでは、Transformers は `config.json` の `dtype` またはレガシーの `torch_dtype` の値で重みを読み込みます。`config.json` にこれらの値のいずれも含まれていない場合、Transformers はチェックポイント内の最初の浮動小数点重みの dtype を使用します。

特定のdtypeを渡すことで、デフォルトをオーバーライドできます。

```py
import torch
from transformers import AutoModelForCausalLM

# specific dtype
model = AutoModelForCausalLM.from_pretrained("google/gemma-3-1b-it", dtype=torch.float16)
```

[AutoConfig](/docs/transformers/main/ja/model_doc/auto#transformers.AutoConfig) は、ゼロからインスタンス化されるモデルに対して `dtype` を受け取ります。

```py
import torch
from transformers import AutoConfig, AutoModel

my_config = AutoConfig.from_pretrained("google/gemma-2b", dtype=torch.float16)
model = AutoModel.from_config(my_config)
```

## カスタムモデル

カスタムモデルは、Transformers の設定クラスとモデリングクラスを基盤として構築され、`AutoClass` API をサポートし、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) で読み込まれます。違いは、モデリングコードが Transformers 由来で*ない*点です。

カスタムモデルを読み込む際は、特に注意を払ってください。Hubではすべてのリポジトリに対して[マルウェアスキャン](https://hf.co/docs/hub/security-malware#malware-scanning)が実施されていますが、悪意のあるコードを誤って実行しないよう、引き続き注意が必要です。

カスタムモデルを読み込むには、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) で `trust_remote_code=True` を設定してください。

```py
from transformers import AutoModelForImageClassification

model = AutoModelForImageClassification.from_pretrained("sgugger/custom-resnet50d", trust_remote_code=True)
```

セキュリティをさらに強化するため、変更された可能性のあるモデルコードを読み込まないよう、特定のrevisionからカスタムモデルを読み込みます。commitハッシュは、モデルの[commit履歴](https://hf.co/sgugger/custom-resnet50d/commits/main)からコピーできます。

```py
commit_hash = "ed94a7c6247d8aedce4647f00f20de6875b5b292"
model = AutoModelForImageClassification.from_pretrained(
    "sgugger/custom-resnet50d", trust_remote_code=True, revision=commit_hash
)
```

詳細については、[モデルのカスタマイズ](./custom_models)ガイドを参照してください。