インストール

Transformers は PyTorch と連携して動作します。Python 3.11 以降および PyTorch 2.6 以降での動作が確認されています。

仮想環境

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

pipのドロップインリプレースメントとして使用できますが、pipの使用を優先する場合は、以下のコマンドからuvを削除してください。

uvのインストールについては、uvのインストールドキュメントを参照してください。

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

uv venv .env
source .env/bin/activate

Python

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

uvは、Rust製の高速なPythonパッケージおよびプロジェクトマネージャーです。

CUDA

NVIDIA Spark (ARM64)

CPU

Intel GPU (XPU)

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

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

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

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

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

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

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

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

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

編集可能なインストール

editable installは、Transformersをローカルで開発する場合に便利です。ファイルをコピーするのではなく、TransformersのローカルコピーをTransformersのリポジトリにリンクします。ファイルはPythonのインポートパスに追加されます。

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

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

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

cd ~/transformers/
git pull

conda

condaは言語非依存のパッケージマネージャーです。新しく作成した仮想環境で、conda-forgeチャンネルからTransformersをインストールしてください。

conda install conda-forge::transformers

セットアップ

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

キャッシュディレクトリ

from_pretrained()で事前学習済みモデルを読み込むと、モデルはHubからダウンロードされ、ローカルにキャッシュされます。

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

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

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

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

HF_HUB_CACHE（デフォルト）
HF_HOME
HF_HOME が設定されていない場合のみ、XDG_CACHE_HOME + /huggingface

オフラインモード

オフライン環境やファイアウォールが設定された環境で Transformers を使用するには、事前にダウンロードしてキャッシュされたファイルが必要です。snapshot_download メソッドを使用して、Hub からモデルリポジトリをダウンロードしてください。

Hub からファイルをダウンロードするその他のオプションについては、Hub からファイルをダウンロードするガイドを参照してください。特定のリビジョンからファイルをダウンロードしたり、CLI からダウンロードしたり、リポジトリからダウンロードするファイルをフィルタリングしたりすることもできます。

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() で local_files_only=True を設定することです。

from transformers import LlamaForCausalLM

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

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

Update on GitHub