HuggingFace Transformersのキャッシュ問題完全解決｜モデルダウンロード・保存先変更・削除方法【Python実装付き】

HuggingFace Transformersのキャッシュ問題とは

HuggingFace Transformersを使用する際、以下のような問題に直面することが多くあります。

• モデルがダウンロードできない
• ディスク容量が急速に減少する
• キャッシュが破損してモデルを読み込めなくなる
• デフォルトのキャッシュ保存先（ホームディレクトリ）がいっぱいになる
• 同じモデルを何度もダウンロードしてしまう

これらの問題は、Transformersのモデルキャッシュ仕組みを理解し、適切に管理することで解決できます。

Transformersのデフォルトキャッシュ保存先

HuggingFace Transformersは、ダウンロードしたモデルを特定のディレクトリに保存します。デフォルトの保存先は以下の通りです。

Linux/Mac:

~/.cache/huggingface/hub/

Windows:

C:\Users\<ユーザー名>\.cache\huggingface\hub\

このディレクトリ配下に、モデルIDごとのフォルダが作成され、モデルファイルが保存されます。たとえば、bert-base-uncasedというモデルをダウンロードした場合、以下のようなパス構造になります。

~/.cache/huggingface/hub/models--bert-base-uncased/
├── snapshots/
│   └── <revision_id>/
│       ├── config.json
│       ├── pytorch_model.bin
│       ├── tokenizer.json
│       └── ...
└── refs/
    └── main

複数のモデルをダウンロードするとこのディレクトリのサイズが膨大になり、ホームディレクトリの容量不足を招くことがあります。

キャッシュ保存先の変更方法

方法1: 環境変数で変更

最も簡単な方法は、環境変数 HF_HOME を設定することです。

Linuxの場合:

export HF_HOME=/path/to/your/cache

Windowsの場合（コマンドプロンプト）:

set HF_HOME=D:\huggingface_cache

Windowsの場合（PowerShell）:

$env:HF_HOME="D:\huggingface_cache"

環境変数を永続的に設定するには、システム環境変数として登録する必要があります。

Linuxの場合は、.bashrc または .zshrc に以下を追加してください。

export HF_HOME=/path/to/your/cache

その後、以下を実行して設定を反映させます。

source ~/.bashrc

方法2: Pythonコード内で変更

Pythonスクリプト内でキャッシュ保存先を変更する場合は、以下のようにコードを記述します。

import os
from transformers import AutoTokenizer, AutoModel

# キャッシュ保存先を変更
os.environ['HF_HOME'] = '/path/to/your/cache'

# この行以降、モデルはカスタムパスにダウンロードされます
tokenizer = AutoTokenizer.from_pretrained('bert-base-uncased')
model = AutoModel.from_pretrained('bert-base-uncased')

重要: 環境変数の設定は、Transformersライブラリをインポートする前に行う必要があります。

方法3: キャッシュディレクトリを完全に無効化

一時的にキャッシュを使用しない場合は、以下のように設定します。

import os
from transformers import AutoTokenizer

# キャッシュを無効化
os.environ['HF_DATASETS_OFFLINE'] = '1'
os.environ['TRANSFORMERS_OFFLINE'] = '1'

# この場合、モデルはメモリにのみ読み込まれます
# ただし、事前にモデルがダウンロードされていない場合はエラーが発生します

モデルのダウンロードと保存

基本的なダウンロード方法

最もシンプルなダウンロード方法は、from_pretrained() メソッドを使うことです。

from transformers import AutoTokenizer, AutoModel

# トークナイザーをダウンロード
tokenizer = AutoTokenizer.from_pretrained('bert-base-uncased')

# モデルをダウンロード
model = AutoModel.from_pretrained('bert-base-uncased')

初回実行時、モデルはデフォルトのキャッシュディレクトリにダウンロードされます。2回目以降は、キャッシュされたモデルが使用されます。

カスタム保存先にダウンロード

特定のディレクトリにモデルを保存したい場合は、cache_dir パラメータを使用します。

from transformers import AutoTokenizer, AutoModel

custom_cache = '/path/to/your/custom/cache'

# トークナイザーをダウンロード
tokenizer = AutoTokenizer.from_pretrained(
    'bert-base-uncased',
    cache_dir=custom_cache
)

# モデルをダウンロード
model = AutoModel.from_pretrained(
    'bert-base-uncased',
    cache_dir=custom_cache
)

オフラインモードでのモデル読み込み

インターネット接続がない環境でも、事前にダウンロードされたモデルを読み込むことができます。

from transformers import AutoTokenizer, AutoModel

# モデルをオフラインモードで読み込む
tokenizer = AutoTokenizer.from_pretrained(
    'bert-base-uncased',
    local_files_only=True,  # ローカルのみから読み込む
    cache_dir='/path/to/your/cache'
)

model = AutoModel.from_pretrained(
    'bert-base-uncased',
    local_files_only=True,
    cache_dir='/path/to/your/cache'
)

local_files_only=True を設定すると、ネットワークアクセスせずにローカルキャッシュのみを使用します。

キャッシュの削除方法

全キャッシュの削除

デフォルトのキャッシュディレクトリ全体を削除する場合は、以下のコマンドを実行してください。

Linux/Mac:

rm -rf ~/.cache/huggingface/hub/

Windows（コマンドプロンプト）:

rmdir /s /q %USERPROFILE%\.cache\huggingface\hub\

Windows（PowerShell）:

Remove-Item -Recurse -Force $env:USERPROFILE\.cache\huggingface\hub\

特定のモデルのみ削除

特定のモデルのキャッシュのみを削除する場合は、そのモデルのディレクトリを削除します。

# Linuxの場合
rm -rf ~/.cache/huggingface/hub/models--bert-base-uncased/

# または、Pythonで実行
import shutil
import os

model_name = 'bert-base-uncased'
cache_dir = os.path.expanduser('~/.cache/huggingface/hub/')
model_cache_dir = os.path.join(cache_dir, f'models--{model_name}')

if os.path.exists(model_cache_dir):
    shutil.rmtree(model_cache_dir)
    print(f'Deleted cache for {model_name}')
else:
    print(f'No cache found for {model_name}')

Pythonでプログラム的に削除

より安全に削除するために、Pythonコードで実装することをお勧めします。

import os
import shutil
from pathlib import Path

def delete_model_cache(model_name, cache_dir=None):
    """特定のモデルのキャッシュを削除"""
    
    if cache_dir is None:
        cache_dir = os.path.expanduser('~/.cache/huggingface/hub/')
    
    model_cache_dir = os.path.join(cache_dir, f'models--{model_name}')
    
    try:
        if os.path.exists(model_cache_dir):
            shutil.rmtree(model_cache_dir)
            print(f'✓ Deleted cache for {model_name}')
            return True
        else:
            print(f'✗ No cache found for {model_name}')
            return False
    except Exception as e:
        print(f'✗ Error deleting cache: {e}')
        return False

# 使用例
delete_model_cache('bert-base-uncased')

キャッシュの確認と管理

キャッシュディレクトリのサイズ確認

import os
import subprocess

def get_cache_size(cache_dir=None):
    """キャッシュディレクトリの総サイズを確認"""
    
    if cache_dir is None:
        cache_dir = os.path.expanduser('~/.cache/huggingface/hub/')
    
    if not os.path.exists(cache_dir):
        return 0
    
    # Linux/Macの場合
    try:
        result = subprocess.run(
            ['du', '-sh', cache_dir],
            capture_output=True,
            text=True
        )
        size_str = result.stdout.split('\t')[0]
        return size_str
    except:
        # Windowsまたはduコマンドが使えない場合
        total_size = 0
        for dirpath, dirnames, filenames in os.walk(cache_dir):
            for filename in filenames:
                filepath = os.path.join(dirpath, filename)
                total_size += os.path.getsize(filepath)
        
        # バイト数をGB単位に変換
        size_gb = total_size / (1024 ** 3)
        return f'{size_gb:.2f}GB'

size = get_cache_size()
print(f'Cache size: {size}')

キャッシュに含まれるモデル一覧表示

import os
from pathlib import Path

def list_cached_models(cache_dir=None):
    """キャッシュされているモデル一覧を表示"""
    
    if cache_dir is None:
        cache_dir = os.path.expanduser('~/.cache/huggingface/hub/')
    
    if not os.path.exists(cache_dir):
        print('Cache directory not found')
        return []
    
    models = []
    for item in os.listdir(cache_dir):
        if item.startswith('models--'):
            model_name = item.replace('models--', '')
            model_path = os.path.join(cache_dir, item)
            models.append(model_name)
    
    print(f'Cached models ({len(models)}):')
    for model in sorted(models):
        print(f'  - {model}')
    
    return models

list_cached_models()

ローカルディスクからのモデル読み込み

キャッシュ内のモデルをディスクから直接読み込む方法を紹介します。

Snapshot ID（リビジョンID）の確認

キャッシュされたモデルを読み込むには、リビジョンIDが必要になります。

import os
from pathlib import Path

def find_model_revision(model_name, cache_dir=None):
    """モデルのリビジョンID（snapshot ID）を取得"""
    
    if cache_dir is None:
        cache_dir = os.path.expanduser('~/.cache/huggingface/hub/')
    
    model_cache_dir = os.path.join(cache_dir, f'models--{model_name}')
    snapshots_dir = os.path.join(model_cache_dir, 'snapshots')
    
    if not os.path.exists(snapshots_dir):
        print(f'Model {model_name} not found in cache')
        return None
    
    revisions = os.listdir(snapshots_dir)
    if revisions:
        latest_revision = revisions[0]  # 最初のリビジョンを取得
        print(f'Model: {model_name}')
        print(f'Revision: {latest_revision}')
        return latest_revision
    
    return None

revision = find_model_revision('bert-base-uncased')

ローカルパスから直接読み込む

from transformers import AutoTokenizer, AutoModel
import os

# ローカルキャッシュパスを直接指定
cache_dir = os.path.expanduser('~/.cache/huggingface/hub/')
model_name = 'bert-base-uncased'
model_cache_dir = os.path.join(cache_dir, f'models--{model_name}', 'snapshots')

# リビジョンIDを取得（最初のものを使用）
revision = os.listdir(model_cache_dir)[0]
model_path = os.path.join(model_cache_dir, revision)

# ローカルパスから読み込む
tokenizer = AutoTokenizer.from_pretrained(model_path)
model = AutoModel.from_pretrained(model_path)

print('Model loaded from local disk')

トラブルシューティング

問題1: キャッシュが破損している

症状: モデルを読み込もうとするとエラーが発生する

解決策:

from transformers import AutoTokenizer, AutoModel

# 破損したキャッシュをスキップして再ダウンロード
tokenizer = AutoTokenizer.from_pretrained(
    'bert-base-uncased',
    force_download=True  # キャッシュを無視して再ダウンロード
)

model = AutoModel.from_pretrained(
    'bert-base-uncased',
    force_download=True
)

問題2: ディスク容量不足

症状: 新しいモデルをダウンロードできない

解決策: 不要なモデルキャッシュを削除し、キャッシュ保存先を別ドライブに変更する

import os
from transformers import AutoModel

# キャッシュ保存先を別ドライブに変更
os.environ['HF_HOME'] = '/mnt/data/huggingface_cache'

# その後、モデルをダウンロード
model = AutoModel.from_pretrained('bert-base-uncased')

問題3: ネットワークエラーでダウンロードが失敗

症状: タイムアウトやコネクションエラー

解決策: キャッシュ保存先を変更して部分的にダウンロード

from transformers import AutoModel
import os

# キャッシュ保存先を指定
os.environ['HF_HOME'] = '/path/to/large/disk'

# タイムアウト時間を延長
import socket
socket.setdefaulttimeout(30)

try:
    model = AutoModel.from_pretrained('bert-base-uncased')
except Exception as e:
    print(f'Download failed: {e}')
    print('Try again later or use a cached version')

パフォーマンス最適化のベストプラクティス

1. キャッシュ保存先を高速ディスクに配置

ダウンロード速度を向上させるため、キャッシュ保存先をSSDに配置することをお勧めします。

# 高速SSDにキャッシュディレクトリを作成
mkdir -p /mnt/ssd/huggingface_cache

# 環境変数を設定
export HF_HOME=/mnt/ssd/huggingface_cache

2. 複数のモデルを事前にダウンロード

ローカルの計算環境を構築する際、必要なモデルを事前にダウンロードしておきましょう。

from transformers import AutoTokenizer, AutoModel

models = [
    'bert-base-uncased',
    'distilbert-base-uncased',
    'roberta-base'
]

for model_name in models:
    print(f'Downloading {model_name}...')
    tokenizer = AutoTokenizer.from_pretrained(model_name)
    model = AutoModel.from_pretrained(model_name)
    print(f'✓ {model_name} downloaded')

3. キャッシュをバックアップ

重要なモデルキャッシュは定期的にバックアップしておくと安心です。

# キャッシュ全体をバックアップ
tar -czf huggingface_cache_backup.tar.gz ~/.cache/huggingface/

# または圧縮なしでコピー
cp -r ~/.cache/huggingface/ /backup/location/

まとめ

HuggingFace Transformersのキャッシュ問題は、以下のポイントを抑えることで解決できます。

1. デフォルトのキャッシュ保存先を理解する
2. 環境変数でキャッシュ保存先を変更する
3. 不要なモデルキャッシュを定期的に削除する
4. ローカルディスクから直接モデルを読み込む
5. 高速ディスク（SSD）にキャッシュを保存する

これらの方法を組み合わせることで、スムーズで効率的な開発環境を構築できます。

あわせて読みたい

• Claude Codeのトークン消費を98%削減する方法【MCP活用＋コンテキスト最適化】
• PythonでMCPサーバーを作る完全ガイド【2026年版・本番運用コード付き】
• LangChain × ベクトルDB で RAG システムを実装｜5ステップで自社データAIを構築