Hugging Face cacheとrevision固定の運用設計

先に結論

Hugging Face Hubの再現性は、commitを固定するだけでは完成しません。revisionの解決、cacheの再利用、取得対象のfilter、snapshotの完全性、model frameworkの読み込みを別の判定に分け、同じmanifestへ記録する必要があります。特にoffline時の部分snapshotを「取得成功」と扱わない設計が境界になります。

判断: まずfull commit hashとfile manifestを基準にし、cacheは速度のための共有層、local_dirは受け渡し用の作業treeとして使い分けます。

確認日時: 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日確認）。
検証区分: 公式仕様から組み立てた机上の検証設計です。download、cache verify、offline load、性能測定、実機rollbackは未実施です。
固定条件: 例示対象はopenai-community/gpt2、full commit 11c5a3d5811f50298f278a704980280950aedb10。API例はPython 3.10以上、huggingface_hub 1.27.0、Transformers 5.15.1を基準にし、PyTorch 2.5以上の解決versionもmanifestへ記録します。実運用では対象repo、license、package lock、hardwareを同時に固定します。

前提と検証条件

比較の最初に、同じrepoについてbranch、tag、full commitを別のrevisionとして扱います。branchやtagは「どの名前を指定したか」の記録にはなりますが、将来の解決先が同じとは限りません。full commitは取得対象を固定する中心値ですが、Hub上のrepo削除、アクセス権、license、依存libraryの変更まで固定するものではありません。

層	固定する値	混ぜてはいけない判定
source	repo ID、repo type、full commit、license、取得日時	branch名だけで同一artifactとみなす
artifact	filename、Hubのfile metadata、filter、SHA-256、manifest	directoryが存在することを完全性とみなす
cache	cache_dir、refs、blobs、snapshots、共有範囲	cache再利用をoffline読み込み成功とみなす
runtime	Python 3.10以上、huggingface_hub 1.27.0、Transformers 5.15.1、PyTorch 2.5以上の解決version、device、dtype	同じmodel IDだけで出力や速度を保証する

Hugging Face公式cache guideは、file listをcommitごとに保存し、snapshotの不足fileをoffline時に検出する仕組みを説明しています。このtree cacheとIncompleteSnapshotErrorはhuggingface_hub 1.22.0で導入されました。判定できるのはtree listingがあるsnapshotであり、古いcacheや単一file取得だけのdirectoryまで完全と証明するものではありません。filterで除外したfileは不足として数えられないため、「完全なrepo snapshot」と「用途に必要なsubset snapshot」をmanifestのscopeで分けます。

実装・比較方法

1. download計画と実取得を分ける

dry_run=Trueは、対象file、commit hash、file size、cache済みかどうか、download予定を確認するための入口です。dry-runの結果は実取得の成功ではないため、計画manifestと実体manifestを別名で保存します。

from huggingface_hub import snapshot_download

REPO_ID = "openai-community/gpt2"
REVISION = "11c5a3d5811f50298f278a704980280950aedb10"

plan = snapshot_download(
    repo_id=REPO_ID,
    revision=REVISION,
    allow_patterns=["*.json", "*.safetensors", "*.txt"],
    dry_run=True,
)

for item in plan:
    print(item)

allow_patternsとignore_patternsは容量と転送量を抑えますが、対象frameworkが必要とするfileまで除外すれば読み込みは成立しません。filterを追加した比較では、対象fileの目的、除外理由、除外後のoffline load結果を一つのrunに結び付けます。

2. cacheとlocal directoryの責務を分ける

公式guideでは、cache_dirやHF_HOMEでcache位置を変更できます。cacheはrevision間で同じblobを再利用しやすい共有層です。一方、local_dirは指定directoryへ元のfile構造を置き、rootに.cache/huggingface/ metadataを作る経路です。受け渡しやartifact packagingではlocal_dirを専用treeへ向け、共有cacheの内部構造をそのまま配布物にしません。

比較では、次の4条件を同じrepo・同じrevisionで分けます。

1. cold取得: cacheもlocal directoryも空。
2. cache再利用: 同じcache_dirから再度取得。
3. local directory再利用: 取得済みtreeとmetadataを残して再実行。
4. offline判定: networkを使わず、local_files_only=Trueで必要fileを解決。

観測値は、download bytes、file count、disk使用量、startup時間、読み込み成否、失敗例を別々に保存します。速度やmemoryはこの制作環境で測っていないため、方式間の優劣を数値で断定しません。

3. 完全性とrollbackを検査する

tree listingを保存済みのsnapshotでoffline時に必要fileが欠ける場合、IncompleteSnapshotErrorが返されます。huggingface_hub 1.23.0以降では例外のsnapshot_pathを記録して調査対象を特定できます。tree listingがないcacheを例外が出ないという理由だけで合格にせず、networkを切る前に公式CLIで対象revisionとlocal directoryを検査します。

hf cache verify openai-community/gpt2 \
  --revision 11c5a3d5811f50298f278a704980280950aedb10 \
  --local-dir models/gpt2-snapshot \
  --fail-on-missing-files \
  --fail-on-extra-files

hf cache verifyはHub上のchecksumとの照合なので、offline試験の前段で実行します。欠けたfileを別revisionから手でコピーするとrevision固定の意味が崩れるため、同じcommitへ戻って再取得します。

from pathlib import Path
from huggingface_hub import snapshot_download

REPO_ID = "openai-community/gpt2"
REVISION = "11c5a3d5811f50298f278a704980280950aedb10"

try:
    path = snapshot_download(
        repo_id=REPO_ID,
        revision=REVISION,
        local_files_only=True,
    )
    print("offline snapshot:", Path(path))
except Exception as exc:
    # IncompleteSnapshotErrorを含む失敗を、部分成功に変換しない。
    print(type(exc).__name__, str(exc))
    raise

rollbackの単位は、model IDではなくmanifestです。旧revisionのfile hash、依存library、tokenizer、起動設定が揃っていることを確認してから、runtimeを旧manifestへ戻します。Hubのcache cleanupは、共有blobやrefsの関係を確認できる公式CLIのdry-runを先に使い、直接snapshotsやblobsを削除しません。

結果とトレードオフ

選択	得られるもの	コスト・リスク
full commit	同じrevisionを再指定しやすい	repoの公開状態、license、依存versionまでは固定しない
cache中心	同一machineの再取得とblob共有	共有範囲が広く、削除や権限を誤ると別jobへ影響する
local_dir中心	artifactの受け渡しと構造確認	metadataとfileの保管、容量重複、削除手順が必要
filterあり	転送量と保存量を抑えられる	必要fileの除外を完全性の失敗として扱う設計が必要

「cacheがあるからofflineで動く」とは限りません。対象revision、必要file、frameworkの読み込み条件が一致したときだけ、offline loadを合格にします。TransformersのAuto classesは保存directoryから対応クラスを組み立てますが、custom code、特殊architecture、tokenizerの追加fileを一般化しないでください。

未検証範囲と判断基準

この分析で確認したのは、公式docsに記載されたAPIとcacheの境界です。特定modelのdownload時間、並列数による速度差、cache hit率、disk回収量、Windowsのsymlink差、gated repoの認証、各hardwareのmemoryは未検証です。とくにdry_runのfile sizeを、そのまま実際の圧縮・転送時間へ置き換えません。

導入判断は、次の条件が揃ったときに進めます。

• repo ID、full commit、license、必要file、file hashをmanifestへ保存できる。
• cold、cache再利用、local directory、offlineを別runとして再実行できる。
• 不足fileは失敗として止まり、別revisionのfileを混ぜずに再取得できる。
• 旧manifestのruntimeとartifactを保持し、削除前にrollbackを確認できる。

入門記事

初めてsnapshotを保存する場合は、Hugging Faceのmodelを固定revisionで保存する入門から、固定commit、file確認、offline loadの順に確認してください。

参考資料

• 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.23.0（2026年8月21日確認）
• huggingface_hub公式release v1.27.0（2026年8月21日確認）
• Transformers公式release v5.15.1（2026年8月21日確認）