# インストール

Transformers は [PyTorch](https://pytorch.org/get-started/locally/) と連携して動作します。Python 3.11 以降および PyTorch 2.6 以降での動作が確認されています。

## 仮想環境

[uv](https://docs.astral.sh/uv/)は、Rust製の非常に高速なPythonパッケージおよびプロジェクトマネージャーであり、デフォルトで[仮想環境](https://docs.astral.sh/uv/pip/environments/)を使用して異なるプロジェクトを管理し、依存関係間の互換性問題を回避します。

[pip](https://pip.pypa.io/en/stable/)のドロップインリプレースメントとして使用できますが、pipの使用を優先する場合は、以下のコマンドから`uv`を削除してください。

> [!TIP]
> uvのインストールについては、uvの[インストール](https://docs.astral.sh/uv/guides/install-python/)ドキュメントを参照してください。

Transformers をインストールするための仮想環境を作成します。

```bash
uv venv .env
source .env/bin/activate
```

## Python

次のコマンドでTransformersをインストールします。

[uv](https://docs.astral.sh/uv/)は、Rust製の高速なPythonパッケージおよびプロジェクトマネージャーです。

NVIDIA GPU (CUDA) 向けに PyTorch とともに Transformers をインストールするには、[PyTorch](https://pytorch.org/get-started/locally) に適した CUDA ドライバーをインストールしてください。

以下のコマンドを実行して、システムがNVIDIA GPUを検出できるか確認してください。

```bash
nvidia-smi
```

```bash
uv pip install "transformers[torch]"
```

NVIDIA Spark デバイス（RTX Spark ラップトップなど）上で ARM64 を実行している環境に、PyTorch とともに Transformers をインストールするには、NVIDIA PyPI インデックスから PyTorch をインストールしてください。これらのデバイスには、NVIDIA による PyTorch の ARM64 ビルドが必要ですが、これらはデフォルトの PyPI インデックスや標準的な PyTorch ウィール インデックスでは利用できません。

以下のコマンドを実行して、システムがNVIDIA GPUを検出できるか確認してください。

```bash
nvidia-smi
```

NVIDIA PyPI インデックスから PyTorch をインストールし、その後 Transformers をインストールします。

```bash
uv pip install torch --index-url https://pypi.nvidia.com
uv pip install transformers
```

CPU のみのバージョンの Transformers をインストールするには、以下のコマンドを実行してください。

```bash
uv pip install torch --index-url https://download.pytorch.org/whl/cpu
uv pip install transformers
```

Intel GPU (XPU) 向けに PyTorch とともに Transformers をインストールするには、適切な [Intel GPU (XPU) 用の PyTorch ドライバー](https://www.intel.com/content/www/us/en/developer/articles/tool/pytorch-prerequisites-for-intel-gpu/2-13.html) をインストールし、Intel GPU (XPU) 用の PyTorch インデックス URL を追加してください。

ドライバをインストールした後、以下のコマンドを実行して、[システムがIntel GPUを検出しているか確認](https://dgpu-docs.intel.com/driver/verification.html)してください。

```bash
xpu-smi
```

```bash
uv pip install "transformers[torch]" --extra-index-url https://download.pytorch.org/whl/xpu
```

以下のコマンドを実行して、インストールが成功したことを確認してください。提供されたテキストに対して、ラベルとスコアが返されるはずです。

```bash
python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))"
[{'label': 'POSITIVE', 'score': 0.9998704791069031}]
```

### ソースからのインストール

ソースからインストールすると、ライブラリの*最新*バージョンがインストールされ、*安定版*ではありません。これにより、Transformersの最新の変更が反映され、最新の機能の実験や、安定版ではまだ正式にリリースされていないバグの修正を行う際に役立ちます。

デメリットとして、最新バージョンが常に安定しているとは限りません。問題が発生した場合は、[GitHub Issue](https://github.com/huggingface/transformers/issues)を作成していただければ、できるだけ早く修正いたします。

次のコマンドでソースからインストールします。

```bash
uv pip install git+https://github.com/huggingface/transformers
```

以下のコマンドを実行して、インストールが正常に行われたことを確認してください。提供されたテキストに対して、ラベルとスコアが返されるはずです。

```bash
python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))"
[{'label': 'POSITIVE', 'score': 0.9998704791069031}]
```

### 編集可能なインストール

[editable install](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs)は、Transformersをローカルで開発する場合に便利です。ファイルをコピーするのではなく、TransformersのローカルコピーをTransformersの[リポジトリ](https://github.com/huggingface/transformers)にリンクします。ファイルはPythonのimportパスに追加されます。

```bash
git clone https://github.com/huggingface/transformers.git
cd transformers
uv pip install -e .
```

> [!WARNING]
> 引き続き使用するには、ローカルの Transformers フォルダを保持する必要があります。

以下のコマンドを実行して、Transformersのローカルバージョンをメインリポジトリの最新の変更内容に更新してください。

```bash
cd ~/transformers/
git pull
```

## conda

[conda](https://docs.conda.io/projects/conda/en/stable/#)は言語非依存のパッケージマネージャーです。新しく作成した仮想環境で、[conda-forge](https://anaconda.org/conda-forge/transformers)チャンネルからTransformersをインストールしてください。

```bash
conda install conda-forge::transformers
```

## セットアップ

インストール後、Transformers のキャッシュの保存先を設定したり、ライブラリをオフライン使用に設定したりできます。

### キャッシュディレクトリ

[from_pretrained()](/docs/transformers/v5.23.0/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained)で事前学習済みモデルを読み込むと、モデルはHubからダウンロードされ、ローカルにキャッシュされます。

コミットハッシュを渡すと、Transformers はそのコミットのファイルに対してローカルキャッシュを使用し、Hub に対して各ファイル（既知の欠落ファイルを含む）を再チェックしません。これは、リビジョンが指定されていない場合のデフォルトの動作です。

ブランチまたはタグを渡した場合、Transformers は読み込みの開始時に Hub に一度だけ連絡してコミットを選択し、その後、そのコミットのファイルに対して同じ方法でキャッシュを使用します。

シェル環境変数 `HF_HUB_CACHE` で指定されるデフォルトのディレクトリは `~/.cache/huggingface/hub` です。Windows では、デフォルトのディレクトリは `C:\Users\username\.cache\huggingface\hub` です。

以下のシェル環境変数（優先度順にリストアップ）のパスを変更して、モデルを別のディレクトリにキャッシュします。

1. [HF_HUB_CACHE](https://hf.co/docs/huggingface_hub/package_reference/environment_variables#hfhubcache)（デフォルト）
2. [HF_HOME](https://hf.co/docs/huggingface_hub/package_reference/environment_variables#hfhome)
3. `HF_HOME` が設定されていない場合のみ、[XDG_CACHE_HOME](https://hf.co/docs/huggingface_hub/package_reference/environment_variables#xdgcachehome) + `/huggingface`

### オフラインモード

オフライン環境やファイアウォールが設定された環境で Transformers を使用するには、事前にダウンロードしてキャッシュされたファイルが必要です。[snapshot_download](https://huggingface.co/docs/huggingface_hub/v2.4.0/en/package_reference/file_download#huggingface_hub.snapshot_download) メソッドを使用して、Hub からモデルリポジトリをダウンロードしてください。

> [!TIP]
> Hub からファイルをダウンロードするその他のオプションについては、[Hub からファイルをダウンロードする](https://hf.co/docs/huggingface_hub/guides/download)ガイドを参照してください。特定のリビジョンからファイルをダウンロードしたり、CLI からダウンロードしたり、リポジトリからダウンロードするファイルをフィルタリングしたりすることもできます。

```py
from huggingface_hub import snapshot_download

snapshot_download(repo_id="meta-llama/Llama-2-7b-hf", repo_type="model")
```

モデルの読み込み時に Hub への HTTP 呼び出しを防ぐには、環境変数 `HF_HUB_OFFLINE=1` を設定してください。

キャッシュされたファイルのみを読み込むための別の方法として、[from_pretrained()](/docs/transformers/v5.23.0/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) で `local_files_only=True` を設定することです。

```py
from transformers import LlamaForCausalLM

model = LlamaForCausalLM.from_pretrained("./path/to/local/directory", local_files_only=True)
```

オフラインモード（または`local_files_only=True`）でも、以前のオンライン読み込みでそのマッピングがキャッシュに保存されている場合、ブランチやタグをコミットに変換できます。マッピングが一度も保存されていない場合、Transformers は指定されたブランチまたはタグをそのまま保持し、通常のオフライン読み込みを続行します。通常のオフライン読み込みと同様に、キャッシュヒットやファイル欠如エラーが発生します。