Hugging Face キャッシュディレクトリの変更方法

問題点

Hugging Face Transformersを使用する際、デフォルトのキャッシュディレクトリ（通常は ~/.cache/huggingface）にディスク容量が不足する場合があります。大規模な事前学習済みモデルやデータセットをキャッシュするためには、より大きなストレージ容量を持つ別のディレクトリへの変更が必要です。

解決策

環境変数による設定（推奨）

最も包括的な解決策は HF_HOME 環境変数を設定する方法です：

Linux/macOS

export HF_HOME=/path/to/cache/directory

Windows

set HF_HOME=E:\huggingface_cache

Pythonコード内

import os
os.environ['HF_HOME'] = '/path/to/cache/directory'

TIP

HF_HOME は Transformersだけでなく、Hugging Face Datasetsやその他のHugging Faceライブラリも統一的に管理できます

永続的な環境変数の設定

シェルの起動時に自動的に設定されるようにするには：

1. .bashrc（または使用しているシェルの設定ファイル）を編集
2. 以下の行を追加：

   export HF_HOME="/path/to/cache/directory"

3. シェルを再起動するか、source ~/.bashrc を実行

ライブラリごとに個別に設定

特定のライブラリのみ個別のキャッシュパスを設定することも可能です：

export HF_HOME=/my_drive/hf/misc
export HF_DATASETS_CACHE=/my_drive/hf/datasets
export TRANSFORMERS_CACHE=/my_drive/hf/models

互換性について

Transformers v4.0.0より前は TRANSFORMERS_CACHE を使用していましたが、v5.0.0以降では非推奨となります。新しいコードでは HF_HOME の使用を推奨します。

コード内での指定

環境変数を設定せずに、直接コード内でキャッシュディレクトリを指定することもできます：

from transformers import AutoTokenizer, AutoModel

# トークナイザーとモデルのキャッシュディレクトリを個別に指定
tokenizer = AutoTokenizer.from_pretrained(
    "roberta-base", 
    cache_dir="/path/to/cache/directory"
)

model = AutoModel.from_pretrained(
    "roberta-base", 
    cache_dir="/path/to/cache/directory"
)

シンボリックリンクによる解決

既存のキャッシュディレクトリを移動し、シンボリックリンクを作成する方法：

# 既存のキャッシュを新しい場所に移動
mv ~/.cache/huggingface /path/to/cache/directory

# シンボリックリンクを作成
ln -s /path/to/cache/directory ~/.cache/huggingface

Docker環境での設定

Dockerコンテナ内で使用する場合：

# ホストマシンのディレクトリをコンテナにマウント
docker run -v ~/my_cache:/app/cache -e HF_HOME="/app/cache" <image_name>

キャッシュ構造の理解

Hugging Faceのキャッシュシステムは以下の優先順位でディレクトリを決定します：

1. HUGGINGFACE_HUB_CACHE または TRANSFORMERS_CACHE（非推奨）
2. HF_HOME
3. XDG_CACHE_HOME/huggingface（デフォルト: ~/.cache/huggingface）

アクセストークンの保存場所

HF_HOME を変更すると、Hugging Face Hubのアクセストークンも新しい場所に保存されます。別途保存したい場合は：

export HF_TOKEN_PATH=$HOME/.huggingface_token

ベストプラクティス

• 大容量ストレージの利用: モデルキャッシュ用に十分な空き容量があるドライブを選択
• 定期的なクリーンアップ: 不要なモデルバージョンやデータセットを定期的に削除
• バックアップ計画: 重要なキャッシュデータはバックアップを検討
• プロジェクトごとの分離: 大規模なプロジェクトではキャッシュディレクトリを分離

これらの方法を活用することで、ディスク容量の問題を解決し、Hugging Faceライブラリを効率的に利用できます。