Snapshot download

huggingface_hub.snapshot_download は、Hugging Face Hub からリポジトリ全体または一部をローカルにダウンロードするための非常に便利な関数です。特にモデルとトークナイザーを効率的に取得する場合に役立ちます。

以下に主要な引数と、今回のプロジェクトでモデルとトークナイザーをダウンロードする際に役立つ引数を説明します。

snapshot_download の主要な引数¶

repo_id (必須)
- ダウンロードしたいリポジトリのIDです。例えば、"tsmatz/xlm-roberta-ner-japanese" のように指定します。
revision (オプション)
- ダウンロードする特定のブランチ、タグ、またはコミットハッシュを指定します。デフォルトは "main" です。
- 例: revision="v1.0.0", revision="a1b2c3d4e5f6"
cache_dir (オプション)
- Hugging Face キャッシュが保存されるルートディレクトリを指定します。デフォルトは環境変数 HF_HOME (通常 ~/.cache/huggingface/) で指定された場所です。
local_dir (オプション)
- ダウンロードしたファイルをコピーしたいローカルディレクトリのパスを指定します。指定しない場合、ファイルはキャッシュディレクトリにのみ存在し、シンボリックリンクは作成されません。
- この引数を指定すると、キャッシュディレクトリから指定された local_dir にファイルがコピーされます。
local_dir_use_symlinks (オプション)
- local_dir が指定されている場合、キャッシュディレクトリから local_dir へのファイルの扱われ方を定義します。
  - True (デフォルト): キャッシュディレクトリへのシンボリックリンクを作成します。これにより、ディスクスペースを節約できますが、オリジナルファイルはキャッシュに残ります。
  - False: ファイルを local_dir に物理的にコピーします。
  - "auto": デフォルトの動作。可能であればシンボリックリンクを作成し、そうでない場合はコピーします。
allow_patterns (オプション)
- ダウンロードを許可するファイル名またはパスのパターン（ワイルドカード * を含む）のリストです。
- この引数を使用すると、リポジトリ内の特定のファイルのみをダウンロードできます。
- 例: allow_patterns=[".json", ".safetensors"]
ignore_patterns (オプション)
- ダウンロードから除外するファイル名またはパスのパターン（ワイルドカード * を含む）のリストです。
- allow_patterns と組み合わせて使用することで、より細かい制御が可能です。
- 例: ignore_patterns=[".msgpack", ".bin"]
token (オプション)
- プライベートリポジトリからのダウンロードや、レートリミットを回避するために認証トークンを指定します。
- Hugging Face Hubにログイン済みであれば、デフォルトで ~/.cache/huggingface/token に保存されたトークンが使用されます。

モデルとトークナイザーをダウンロードする際の考慮事項¶

tsmatz/xlm-roberta-ner-japanese のようなTransformersモデルの場合、通常以下のファイルが必要です。

モデルファイル: model.safetensors (推奨), pytorch_model.bin など
トークナイザーファイル: tokenizer.json (Fast Tokenizerの場合), sentencepiece.bpe.model (SentencePieceの場合), tokenizer_config.json, special_tokens_map.json など
設定ファイル: config.json

プロジェクトの models/ner_model.py で snapshot_download を利用する場合、以下のように allow_patterns を使うことで、必要なファイルのみを効率的にダウンロードできます。

使用例 (プロジェクトの ner_model.py での想定)

from huggingface_hub import snapshot_download
import os

def download_ner_model_files(repo_id: str, local_path: str):
    """
    指定されたNERモデルのファイル群をダウンロードします。
    必要なファイルのみを選択的にダウンロードするように設定しています。
    """
    # local_path が存在しない場合は作成
    os.makedirs(local_path, exist_ok=True)

    # TokenizerとModelに必要なファイルをallow_patternsで指定
    # `tsmatz/xlm-roberta-ner-japanese` の場合、SentencePieceベースのトークナイザーと
    # safetensors形式のモデルが使われているため、それに合わせてパターンを設定
    allow_list = [
        "config.json",                 # モデルの設定
        "tokenizer.json",              # Fast Tokenizer 用 (もしあれば)
        "sentencepiece.bpe.model",     # SentencePiece モデルファイル
        "tokenizer_config.json",       # トークナイザー設定
        "special_tokens_map.json",     # 特殊トークンマップ
        "model.safetensors",           # モデルの重み (Safetensors形式)
        # "pytorch_model.bin",         # もしsafetensorsがない場合やPytorch形式が必要な場合
        "added_tokens.json",           # 追加トークンがあれば
    ]

    downloaded_path = snapshot_download(
        repo_id=repo_id,
        revision="main",                  # 特定のrevisionがあれば指定
        local_dir=local_path,
        local_dir_use_symlinks=False,     # ファイルを物理的にコピーする
        allow_patterns=allow_list,
        # ignore_patterns=["*.bin", "*.msgpack"], # 不要なファイルを明示的に無視することも可能
    )
    return downloaded_path

# 例: モデルをダウンロードする
# repo_id = "tsmatz/xlm-roberta-ner-japanese"
# output_dir = "./downloaded_model"
# downloaded_dir = download_ner_model_files(repo_id, output_dir)
# print(f"モデルファイルは {downloaded_dir} にダウンロードされました。")

つまづきポイント¶

allow_patterns と ignore_patterns の競合: 両方を指定した場合、allow_patterns で指定されたものの中から ignore_patterns で除外される、という挙動になります。基本的にはどちらか一方を使う方が意図が明確になります。
ファイル名の大文字小文字: Linux 環境ではファイル名は大文字小文字を区別します。Hugging Face Hub上のファイル名を正確に確認してください。
local_dir と local_dir_use_symlinks: local_dir を指定しない場合、ファイルはキャッシュディレクトリにのみ存在し、後続の AutoModel.from_pretrained() などではキャッシュパスを直接参照する必要があります。local_dir を指定して local_dir_use_symlinks=False とすると、指定したディレクトリに物理的にファイルがコピーされるため、キャッシュを意識せずに済みます。