Hub Python Library documentation
Hubからファイルをダウンロード
Hubからファイルをダウンロード
huggingface_hub ライブラリは、Hub に保存されているリポジトリからファイルをダウンロードする関数を提供します。これらの関数は単独で使用することも、ご自身のライブラリに組み込むこともでき、ユーザーが Hub とやり取りする際の利便性を高めることができます。このガイドでは、以下の方法について説明します。
- 単一のファイルをダウンロードしてキャッシュします。
- リポジトリ全体をダウンロードしてキャッシュします。
- ファイルをローカルフォルダーにダウンロードします。
単一のファイルをダウンロード
hf_hub_download()関数は、Hubからファイルをダウンロードするためのメイン関数です。 リモートファイルをダウンロードし、ディスク上にキャッシュ（バージョンを認識した方法で）し、ローカルファイルパスを返します。
返されるファイルパスは、HF ローカルキャッシュへのポインタです。そのため、キャッシュが破損しないように、ファイルを修正しないことが重要です。ファイルのキャッシュ方法について詳しく知りたい場合は、キャッシュガイドを参照してください。
最新バージョンから
repo_id、repo_type、filenameパラメータを使用して、ダウンロードするファイルを選択します。デフォルトでは、そのファイルはmodelリポジトリの一部であるとみなされます。
>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json")
'/root/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json'
# Download from a dataset
>>> hf_hub_download(repo_id="google/fleurs", filename="fleurs.py", repo_type="dataset")
'/root/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34/fleurs.py'特定のバージョンから
デフォルトでは、mainブランチの最新バージョンがダウンロードされます。ただし、特定のバージョン（特定のブランチ、PR、タグ、コミットハッシュなど）のファイルをダウンロードしたい場合があります。その場合は、revisionパラメータを使用します。
# Download from the `v1.0` tag
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0")
# Download from the `test-branch` branch
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch")
# Download from Pull Request #3
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="refs/pr/3")
# Download from a specific commit hash
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="877b84a8f93f2d619faa2a6e514a32beef88ab0a")注: コミットハッシュを使用する場合は、7文字の短縮形ではなく、完全な長さのハッシュを使用する必要があります。
ダウンロードURLを構築する
リポジトリからファイルをダウンロードするために使用されるURLを構築したい場合は、URLを返すhf_hub_url()を使用できます。 これは内部でhf_hub_download()によって使用されています。
リポジトリ全体をダウンロード
snapshot_download() は、指定されたリビジョンのリポジトリ全体をダウンロードします。内部では hf_hub_download() を使用しているため、ダウンロードされたファイルはすべてローカルディスクにキャッシュされます。処理を高速化するために、ダウンロードは並行して実行されます。
リポジトリ全体をダウンロードするには、repo_idとrepo_typeを渡すだけです:
>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp")
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade'
# Or from a dataset
>>> snapshot_download(repo_id="google/fleurs", repo_type="dataset")
'/home/lysandre/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34'snapshot_download() はデフォルトで最新のリビジョンをダウンロードします。特定のリポジトリのリビジョンを指定する場合は、revision パラメータを使用します。
>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1")ダウンロードするファイルの絞り込み
snapshot_download() は、リポジトリをダウンロードする簡単な方法を提供します。ただし、リポジトリのすべてのコンテンツをダウンロードしたいとは限りません。例えば、.safetensors の重みしか使用しないことがわかっている場合、すべての .bin ファイルのダウンロードを防止したい場合があります。allow_patterns と ignore_patterns パラメータを使用して、これを行うことができます。
これらのパラメータは、単一のパターンまたはパターンのリストを受け取ります。パターンは、こちらにドキュメント化されている標準ワイルドカード（globbingパターン）です。パターンマッチングはfnmatchに基づいています。
例えば、allow_patterns を使用して JSON 設定ファイルのみをダウンロードできます:
>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", allow_patterns="*.json")一方、ignore_patterns を使用すると、ダウンロード対象から特定のファイルを除外できます。
次の例では、.msgpack と .h5 のファイル拡張子を無視しています。
>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", ignore_patterns=["*.msgpack", "*.h5"])最後に、両方を組み合わせることで、ダウンロードを正確にフィルタリングできます。ここでは、vocab.jsonを除くすべてのjsonファイルとmarkdownファイルをダウンロードする例を示します。
>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json")ファイルをローカルフォルダーにダウンロード
デフォルトでは、Hub からファイルをダウンロードするためにキャッシュシステムの使用を推奨します。hf_hub_download()およびsnapshot_download()のcache_dirパラメータでカスタムのキャッシュ場所を指定するか、HF_HOME環境変数を設定することで指定できます。
ただし、特定のフォルダにファイルをダウンロードする必要がある場合は、ダウンロード関数にlocal_dirパラメータを渡すことができます。これにより、gitコマンドが提供するワークフローに近い形に近づけることができます。ダウンロードされたファイルは、指定されたフォルダ内で元のファイル構造を維持します。例えば、filename="data/train.csv"かつlocal_dir="path/to/folder"の場合、結果のファイルパスは"path/to/folder/data/train.csv"になります。
ローカルディレクトリのルートに、ダウンロードされたファイルに関するメタデータを含む.cache/huggingface/フォルダが作成されます。これにより、ファイルがすでに最新である場合の再ダウンロードを防ぎます。メタデータに変更がある場合、新しいファイルバージョンがダウンロードされます。これにより、local_dirは最新の変更のみを取得するように最適化されます。
ダウンロードが完了したら、不要であれば.cache/huggingface/フォルダを安全に削除できます。ただし、このフォルダを削除した状態でスクリプトを再実行すると、メタデータが失われるため、復旧に時間がかかる可能性があります。ローカルデータはそのまま保持され、影響を受けませんのでご安心ください。
Hubに変更をコミットする際は、
.cache/huggingface/フォルダについては気にする必要はありません。このフォルダは、gitとupload_folder()の両方によって自動的に無視されます。
CLIからダウンロード
ターミナルからhf downloadコマンドを使用すると、Hubからファイルを直接ダウンロードできます。
内部では、上記で説明したhf_hub_download()およびsnapshot_download()ヘルパーを同じように使用し、返されたパスをターミナルに出力します。
>>> hf download gpt2 config.json
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json複数のファイルを一度にダウンロードすると、進捗バーが表示され、ファイルが保存されているスナップショットパスが返されます:
>>> hf download gpt2 config.json model.safetensors
Fetching 2 files: 100%|████████████████████████████████████████████| 2/2 [00:00<00:00, 23831.27it/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10hf:// URI を 1 つ指定して、リポジトリ（および任意のリビジョンとファイル）を指すこともできます。URI は hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] という文法に従います（完全な構文については HF URIs リファレンス を参照してください）。この URI は --repo-type および --revision オプションに置き換わります。これらは同時に設定できません。
# Download a single file from a dataset at a given revision
>>> hf download hf://datasets/google/fleurs@refs/pr/1/fleurs.py
# Download a subfolder (note the trailing slash)
>>> hf download hf://datasets/google/fleurs/data/
# Download an entire repo
>>> hf download hf://datasets/google/fleursCLIダウンロードコマンドの詳細については、CLIガイドを参照してください。
ドライランモード
一部のケースでは、実際にダウンロードする前に、どのファイルがダウンロードされるかを確認したい場合があります。--dry-run パラメータを使用して、これを確認できます。このオプションは、リポジトリに存在するダウンロード対象のすべてのファイルをリスト表示し、それらがすでにダウンロード済みかどうかをチェックします。これにより、ダウンロードが必要なファイルの数やそのサイズを把握できます。
単一のファイルで確認する例を以下に示します。
>>> hf download openai-community/gpt2 onnx/decoder_model_merged.onnx --dry-run
[dry-run] Will download 1 files (out of 1) totalling 655.2M
File Bytes to download
------------------------------ -----------------
onnx/decoder_model_merged.onnx 655.2Mファイルがすでにキャッシュされている場合:
>>> hf download openai-community/gpt2 onnx/decoder_model_merged.onnx --dry-run
[dry-run] Will download 0 files (out of 1) totalling 0.0.
File Bytes to download
------------------------------ -----------------
onnx/decoder_model_merged.onnx -リポジトリ全体でドライランを実行することもできます:
>>> hf download openai-community/gpt2 --dry-run
[dry-run] Fetching 26 files: 100%|█████████████| 26/26 [00:04<00:00, 6.26it/s]
[dry-run] Will download 11 files (out of 26) totalling 5.6G.
File Bytes to download
--------------------------------- -----------------
.gitattributes -
64-8bits.tflite 125.2M
64-fp16.tflite 248.3M
64.tflite 495.8M
README.md -
config.json -
flax_model.msgpack 497.8M
generation_config.json -
merges.txt -
model.safetensors 548.1M
onnx/config.json -
onnx/decoder_model.onnx 653.7M
onnx/decoder_model_merged.onnx 655.2M
onnx/decoder_with_past_model.onnx 653.7M
onnx/generation_config.json -
onnx/merges.txt -
onnx/special_tokens_map.json -
onnx/tokenizer.json -
onnx/tokenizer_config.json -
onnx/vocab.json -
pytorch_model.bin 548.1M
rust_model.ot 702.5M
tf_model.h5 497.9M
tokenizer.json -
tokenizer_config.json -
vocab.json -ファイルのフィルタリングを使用すると:
>>> hf download openai-community/gpt2 --include "*.json" --dry-run
[dry-run] Fetching 11 files: 100%|█████████████| 11/11 [00:00<00:00, 80518.92it/s]
[dry-run] Will download 0 files (out of 11) totalling 0.0.
File Bytes to download
---------------------------- -----------------
config.json -
generation_config.json -
onnx/config.json -
onnx/generation_config.json -
onnx/special_tokens_map.json -
onnx/tokenizer.json -
onnx/tokenizer_config.json -
onnx/vocab.json -
tokenizer.json -
tokenizer_config.json -
vocab.json -最後に、hf_hub_download() と snapshot_download() に dry_run=True を渡すことで、プログラム的にもドライランを実行できます。これにより、各ファイルについて、コミットハッシュ、ファイル名、ファイルサイズ、ファイルがキャッシュされているかどうか、ダウンロードされるかどうかを示す DryRunFileInfo（それぞれ DryRunFileInfo のリスト）が返されます。実際には、ファイルがキャッシュされていない場合、または force_download=True が渡された場合に、ファイルがダウンロードされます。
より高速なダウンロード
hf_xet を活用して、より高速なダウンロードを実現しましょう。hf_xet は、チャンクベースの重複排除によりダウンロードとアップロードを高速化する xet-core ライブラリの Python バインディングです。hf_xet は huggingface_hub とシームレスに統合されますが、LFS の代わりに Rust 製の xet-core ライブラリと Xet ストレージを使用します。
hf_xet は、ファイルを不変のチャンクに分割し、これらのチャンクのコレクション（ブロックまたは xorb と呼ばれる）をリモートに保存し、要求時にそれらを取得してファイルを再構築する Xet ストレージシステムを使用します。ダウンロード時、ユーザーがファイルにアクセスする権限を持っていることを確認した後、hf_xet は、このファイルの LFS SHA256 ハッシュで Xet のコンテンツアドレス可能サービス（CAS）にクエリを実行し、これらのファイルをアセンブルするための再構築メタデータ（xorb 内の範囲）と、xorb を直接ダウンロードするためのプレサイン URL を取得します。その後、hf_xet は必要な xorb の範囲を効率的にダウンロードし、ディスクにファイルを出力します。
有効にするには、huggingface_hubの最新バージョンをインストールするだけです:
pip install -U "huggingface_hub"huggingface_hub 0.32.0 以降、hf_xet もインストールされます。
その他のすべてのhuggingface_hub APIは、変更なしで引き続き動作します。Xetストレージとhf_xetの利点について詳しく知るには、このセクションを参照してください。
注: hf_transfer は以前 LFS ストレージバックエンドで使用されていましたが、現在は非推奨です。代わりに hf_xet を使用してください。