hf CLIの取得を4状態で検証:revision固定とoffline cache

AIに外部ファイルを取得させたとき、URLだけを残しても、後日同じ内容を確認できるとは限りません。そこでhf CLI 2.3.0を使い、公開repoのconfig.json 1件を固定commitへpinして、online/offlineとcache有無を組み合わせた4状態を実機で比べました。
結果は、onlineの空cache、onlineの同一cache、offlineのcached hitはexit 0、offlineの空cacheは期待どおりexit 1でした。receiptにはrepo、40桁revision、file名、665 bytes、SHA-256、4件のexit codeを残しました。
ただし、これは公開ファイル1件の有限検証です。モデル推論、重み、private/gated repo、認証、Windows以外は試していません。offline時にHTTPが発生しないことは公式仕様を確認しましたが、packet captureによる通信観測は行っていません。
公式説明と今回の実測を分ける
公式CLIガイドでは、huggingface_hubにhf CLIが含まれ、uvx hfで一時環境から実行できること、--jsonで構造化出力を得られること、--revisionで特定revisionを選べること、--dry-runで取得前にfileとsizeを確認できることを案内しています。
公式の環境変数資料では、HF_HOMEがtokenとcacheを保存する場所、HF_HUB_CACHEがHub repoのcache場所だと説明しています。HF_HUB_OFFLINE=1ではHTTP callを行わずcached fileだけを参照し、cacheがなければerrorになるという仕様です。同資料は、onlineでは最新fileがcache済みでも新version確認のHTTP requestが発生すると注意しています。
今回の実測は、この説明を任意の環境へ一般化する性能試験ではありません。4状態のexit code、返されたfile、hashが今回の観測値です。
検証条件:tokenを使わず、cacheを隔離する
2026年10月27日、次の条件で実行しました。追加費用、新規account、API key、Hugging Face tokenは使っていません。
| 項目 | 条件 |
|---|---|
| OS/shell | Windows、PowerShell 7.6.9 |
| 実行方法 | uv 0.12.10からhuggingface_hub==2.3.0をuvxで一時実行 |
| CLI | hf 2.3.0。公式v2.3.0 releaseと実行時versionを照合 |
| 対象 | openai-community/gpt2のconfig.jsonだけ。重みは取得しない |
| revision | 607a30d783dfa663caf39e06633721c8d4cfcd7e |
| license表示 | model repoのcard dataでmitを確認 |
| 認証 | HF_HOMEを一時folderへ隔離し、implicit tokenを無効化。既存tokenを参照しない |
| 費用 | 0円。Jobs、Sandbox、Inference、uploadは未実施 |
対象repoの用途適合性や学習dataの権利をlicense値だけで保証したものではありません。ここでは小さい公開fileで取得手順を再現するために使っています。
4状態の結果:3成功、1件は期待した失敗
同じrepo、revision、fileを保ち、cacheとofflineだけを変えました。
| 状態 | 前提 | exit | 結果 |
|---|---|---|---|
| 1. online・空cache | 新しい隔離cache | 0 | 665-byteのconfig.jsonを取得 |
| 2. online・同cache | 状態1のcacheを再利用 | 0 | 同じfile pathとhashを返した |
| 3. offline・cached hit | 状態1のcache + HF_HUB_OFFLINE=1 |
0 | cached fileを取得 |
| 4. offline・空cache | 別の空cache + HF_HUB_OFFLINE=1 |
1 | Local entry not foundで停止 |
4状態の結果を「cacheなら成功」の1行へまとめないことが重要です。状態2はonlineなので、fileがcacheにあっても公式説明上はmetadata確認のHTTPが起こり得ます。状態3はoffline設定下のcached hitです。今回packetを観測して両者の通信量を比較したわけではありません。
取得fileは4状態の成功時に同じcache snapshotを参照し、結果のreceiptへ次を記録しました。
{
"repo_id": "openai-community/gpt2",
"revision": "607a30d783dfa663caf39e06633721c8d4cfcd7e",
"file": "config.json",
"file_bytes": 665,
"file_sha256": "0daed7749b4f02b8f76240d5444551d7b08712dab4d0adb8239c56ba823bb7b4"
}
失敗例:local folderとHub cacheを同じものと考えない
4状態とは別に、--local-dirへfileを取得したあと、そのfolderを指定せず、別の空Hub cacheをofflineで参照しました。onlineのlocal取得はexit 0でしたが、offlineの空Hub cacheはexit 1でした。
これは「同じ--local-dirを指定したoffline再実行が失敗する」という検証ではありません。手元にlocal copyが存在しても、別の空cacheが自動でそのcopyを探すとは限らない、という補助例です。再利用する場所を曖昧にせず、--local-dirを再指定するのか、--cache-dirを固定するのかを決めます。
PowerShellで4状態を再現する
PowerShell、receipt validator、7 tests、実測結果をまとめたZIPを新しいfolderへ展開します。uvとネットワーク接続が必要なのはonline段階です。
pwsh -NoProfile -ExecutionPolicy Bypass -File .\run_experiment.ps1
python .\receipt.py .\results\receipt.json
python -m unittest discover -s tests -p 'test_*.py' -v
scriptはtoken関連のprocess環境変数を外し、HF_HOME、main cache、empty cacheを一時folderへ分離します。対象revisionが記録値と違う場合、またはmodel cardのlicense表示がmitでない場合は結果生成を止めます。raw pathは公開せず、JSONからユーザー名・絶対path・token型文字列を除去します。
標準Pythonの7 testsは、記録receiptの読込、40桁revision、offline missのexit、4状態の欠落、絶対path、token型文字列、実測JSONのsanitizationを検査します。これは取得先の安全性やlicense適合性を証明するtestではありません。
実務への影響:最小receiptは5項目+条件を残す
実務では、URLだけでなく次を1組にします。
- repo ID
- branch名ではなく確認したcommit revision
- 取得file名とbytes
- fileのSHA-256
- case別のonline/offline、cache名、exit code
加えて、CLI version、認証の有無、取得日、失敗messageを残します。token、ユーザー名、local絶対pathはreceiptへ入れません。取得物のlicense、利用条件、内容の安全性はhashとは別に確認します。
この分離は、AIが取得した素材を記事、評価fixture、build入力へ渡すときに効きます。後続工程は「最新らしいfile」ではなく、receiptのrevisionとhashへ一致したfileだけを受け取れます。更新したい場合は同じreceiptを上書きせず、新しいrevisionとhashを別recordとして追加します。逆に、hashが一致しても内容が正しい、licenseに適合する、悪意あるcodeを含まない、という保証にはしません。取得同一性と内容審査を別gateにします。
限界と次の行動
config.json1件だけで、large file、Xet shared blob、並列download、途中再開、破損cacheは未検証です。HF_HUB_OFFLINE=1のHTTP抑止は公式仕様の確認で、packet captureによる独自観測ではありません。uvxのpackage取得自体にはonline接続が必要です。完全に新しい端末をofflineのまま準備できる手順ではありません。- private/gated repo、browser login、token権限、uploadは未実施です。
hf cache verifyによるrepo全体のchecksum検査とは目的が異なり、本稿は取得した1fileのSHA-256とreceiptを検査します。
外部fileを記事やbuildへ使う場合は、まず小さい1fileで4状態を記録し、必要なfileだけへ対象を広げます。公開後HTMLの内部linkを検査したい場合はWindowsで内部リンクを検査する手順、buildとdeployを切り分けたい場合はAstro + Cloudflare Pagesの公開前確認が関連します。Hugging Faceのtokenと接続先を点検する場合は7月の侵害報告を受けた権限点検を参照してください。
表紙はbuilt-in ImageGenで作った概念画像で、実際のCLI画面や検証証拠ではありません。