実践ガイド

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で停止

hf CLIの取得を4状態で比較し、online空cache・online同cache・offline cached hitの3件は成功、offline空cacheは失敗した図

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組にします。

  1. repo ID
  2. branch名ではなく確認したcommit revision
  3. 取得file名とbytes
  4. fileのSHA-256
  5. 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.json 1件だけで、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画面や検証証拠ではありません。

一次情報・出典

  1. Hugging Face Hub:Command Line Interface
  2. Hugging Face Hub:Environment variables
  3. huggingface_hub v2.3.0 release
  4. openai-community/gpt2 model repository