Hub Python Library documentation

Hubからファイルをダウンロード

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v2.4.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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/11c5a3d5811f50298f278a704980280950aedb10

hf:// 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/fleurs

CLIダウンロードコマンドの詳細については、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 を使用してください。

Update on GitHub