Hugging Faceのmodelを固定revisionで保存する入門

先に結論

Hugging Face Hubのmodelをあとから同じ状態で使いたいなら、mainのような動く名前ではなく、full commit hashをrevisionへ渡してsnapshotを保存します。保存後にrevisionと必要fileを確認し、local_files_only=Trueで読み込めれば、ネットワークに依存しない再実行の入口ができます。

おすすめ読者: Hugging Faceから初めてmodelを取得する人、同じmodelを別の環境や後日の検証で使い直したい人。

確認日時: 2026年8月21日 18:33（Asia/Tokyo）
対象仕様: huggingface_hub 1.27.0のdownload／cache仕様、Transformers 5.15.1のAuto classesとinstallation guide（2026年8月21日確認）。
検証区分: 公式ドキュメントを照合した机上調査です。この制作環境ではmodel download、cache作成、offline読み込み、生成を実行していません。
未確認: 対象repoのlicense、gated条件、modelのサイズ、対応hardware、実際の通信時間とmemory使用量はrepoと環境ごとに確認が必要です。

始める前に知っておくこと

revisionは、Hub上のどの版を使うかを指定する値です。branchやtagも指定できますが、branchは先端commitが変わり、tagも運用次第で付け替えられます。公式download guideは、commit hashを使う場合は7文字の短縮値ではなくfull-length hashを渡すよう説明しています。この記事では、公式ドキュメントに登場する公開modelとcommitを例にします。

snapshotは、あるrevisionに含まれるfileのまとまりです。snapshot_download()はrepository全体を取得します。local_dirを省略した場合はHubのmain cacheへ保存しますが、指定した場合はmain cacheを使わず、対象directoryへ元のfile構造と.cache/huggingface/ metadataを作ります。どちらも外部へ持ち運ぶためのmanifestやlicense確認を自動で済ませる仕組みではありません。公開条件、license、利用規約は対象repoのmodel cardで別に確認します。

保存先には、Hubが管理するcacheと、明示したdirectoryへfileを置くlocal_dirがあります。初めての確認では、記事の手順専用directoryを作り、どのrevisionとfileを保存したかを記録すると、共有cacheを誤って削除せずに済みます。

以下はPython 3.10以上、huggingface_hub 1.27.0、Transformers 5.15.1を前提にします。Transformersの公式installation guideはPyTorch 2.5以上を検証対象としているため、別のvirtual environmentで導入し、実際に解決されたPyTorchのversionも記録します。

最短手順

0. 専用環境を作り、versionを確認する

python -m venv .venv
source .venv/bin/activate
python -m pip install "huggingface_hub==1.27.0" "transformers[torch]==5.15.1"

python -c "import huggingface_hub, transformers, torch; print(huggingface_hub.__version__, transformers.__version__, torch.__version__)"

先頭2つが1.27.0と5.15.1で、PyTorchが2.5以上なら次へ進みます。Windowsではactivate commandが異なるため、Transformers公式installation guideの自分のshell向け手順を使ってください。導入に失敗した場合は既存の共有環境を上書きせず、この.venvを作り直します。

1. 固定revisionでsnapshotを保存する

次の例は、公式docsのcache path例に登場するopenai-community/gpt2と、そこに示されているfull commit hashを使います。対象repoが大きい場合は、先にdiskの空きを確認してください。実行前に対象repoのlicenseとfile一覧も読みます。

from pathlib import Path
from huggingface_hub import snapshot_download

REPO_ID = "openai-community/gpt2"
REVISION = "11c5a3d5811f50298f278a704980280950aedb10"
TARGET = Path("models/gpt2-snapshot")

snapshot_path = snapshot_download(
    repo_id=REPO_ID,
    revision=REVISION,
    local_dir=TARGET,
)

print(f"snapshot: {snapshot_path}")
print(f"revision: {REVISION}")

ここで表示されるpathとrevisionを、実行記録へ保存します。snapshot_download()はfileを並列に取得しますが、並列数が大きいほど速いと決めつけず、通信制限、disk、対象repoの規模を見てください。fileの内容をcache内部で直接編集すると、以後の再利用を壊す可能性があります。

2. 保存されたfileを確認する

「directoryが作られた」だけを成功条件にしません。config、tokenizer、weightなど、利用するframeworkが必要とするfileが揃っているかを確認します。file名はmodelの形式で変わるため、次の確認は一覧を読むための最小例です。

from pathlib import Path

TARGET = Path("models/gpt2-snapshot")
required = {"config.json", "tokenizer_config.json"}
present = {path.name for path in TARGET.iterdir() if path.is_file()}

missing = required - present
if missing:
    raise RuntimeError(f"missing required files: {sorted(missing)}")

print("files:", len(present))
print("config and tokenizer metadata are present")

これはmodel全体の完全性を保証するhash検証ではありません。公式cache guideにはrevision単位のfile list、hf cache verify、不完全snapshotを検出する仕組みが説明されています。継続運用や配布前の監査では、玄人向けのcacheとrevision固定の運用設計へ進みます。

3. ネットワークなしの読み込みを確認する

TransformersのAuto classesは、model名または保存済みdirectoryから設定・tokenizer・modelのクラスを選びます。snapshotに必要fileが揃った環境で、local_files_only=Trueを付けて、取得処理と読み込み処理を分けます。

from transformers import AutoConfig, AutoModelForCausalLM, AutoTokenizer

TARGET = "models/gpt2-snapshot"

config = AutoConfig.from_pretrained(TARGET, local_files_only=True)
tokenizer = AutoTokenizer.from_pretrained(TARGET, local_files_only=True)
model = AutoModelForCausalLM.from_pretrained(TARGET, local_files_only=True)

print("model_type:", config.model_type)
print("tokenizer:", tokenizer.__class__.__name__)
print("model:", model.__class__.__name__)

このコードは読み込み成功を確認するだけで、推論品質や速度を測定しません。生成まで進む場合は、prompt、tokenizer、dtype、device、Transformersのversionを別途固定し、出力を「同じmodelだから同じ結果」と一般化しないでください。

つまずきやすい点

branchのまま取得してしまう: 今日のmainと後日のmainは同じとは限りません。取得時に解決されたcommitと、対象repoのrevisionを記録します。すでにbranchで取得した場合は、同じ環境でfull commitを指定して取り直し、2つのmanifestを分けます。
offlineで一部だけ読める: huggingface_hub 1.22.0以降では、snapshot_download()が保存したtree listingで期待fileを判定でき、offlineまたはlocal_files_only=Trueでそのfileが不足するとIncompleteSnapshotErrorが発生します。ただし、古いcacheや単一fileだけの取得などtree listingがない状態まで完全性を保証する例外ではありません。現在versionでsnapshotをonline取得し直すか、隔離前にhf cache verifyで対象revisionを検査してから、networkなしの読み込みへ進みます。途中fileを手で足さないでください。
gated modelを公開modelと同じに扱う: 認証が必要なrepoでは、アクセス権、tokenの保存場所、license同意を確認します。tokenをshell履歴や記事へ直書きせず、取得済みartifactを別の利用者へ再配布できるとは考えません。
versionが違う: dry_run、tree cache、cache管理commandの有無や挙動はreleaseで変わります。TypeErrorや未知のcommandが出たら記事の処理を続けず、version表示を確認し、専用環境を上記の固定versionで作り直します。
cacheを一括削除する: cacheはrevision間でblobを共有することがあります。不要revisionの削除は公式のcache管理コマンドでdry-runを確認し、共有cache全体を直接削除しないでください。元へ戻すには、記録済みrevisionとmanifestから専用directoryへ再取得します。

まとめ

最初の成功は、modelが一度読み込めることではなく、full commit hash、保存先、必要file、offline読み込みの4点を同じ記録へ結び付けることです。小さな公開repoで流れを確認してから、実際に使うmodelへ広げると、cacheの便利さと再現性を混同しにくくなります。

参考資料

Hugging Face Hub公式：Download files from the Hub（2026年8月21日確認）
Hugging Face Hub公式：Understand caching（2026年8月21日確認）
Transformers公式：Auto classes（2026年8月21日確認）
Transformers公式：Installation（2026年8月21日確認）
huggingface_hub公式release v1.22.0（2026年8月21日確認）
huggingface_hub公式release v1.27.0（2026年8月21日確認）
Transformers公式release v5.15.1（2026年8月21日確認）