Hugging Face's logo

Hub Python Library documentation

ファイルのダウンロード

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

ファイルのダウンロード

単一のファイルをダウンロード

hf_hub_download

huggingface_hub.hf_hub_download

< >

( repo_id: strfilename: strsubfolder: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonelibrary_name: str | None = Nonelibrary_version: str | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_dir: str | pathlib.Path | None = Noneuser_agent: dict | str | None = Noneforce_download: bool = Falseetag_timeout: float = 10token: bool | str | None = Nonelocal_files_only: bool = Falseheaders: dict[str, str] | None = Noneendpoint: str | None = Nonetqdm_class: type[tqdm.std.tqdm] | None = Nonedry_run: bool = False ) → str or DryRunFileInfo

パラメータ

  • repo_id (str) — / で区切られたユーザー名または組織名とリポジトリ名。
  • filename (str) — リポジトリ内のファイル名です。
  • subfolder (str, 省略可) — モデルリポジトリ内のフォルダーに対応する省略可能な値。
  • repo_type (str, 任意) — データセット、スペース、またはカーネルのリポジトリからダウンロードする場合は "dataset"、"space"、または "kernel" を設定し、モデルからダウンロードする場合は None または "model" を設定します。デフォルトは None です。
  • revision (str, 省略可) — ブランチ名、タグ、またはコミットハッシュである、任意の Git リビジョン ID。
  • library_name (str, 省略可) — オブジェクトが対応するライブラリの名前です。
  • library_version (str, 省略可) — ライブラリのバージョンです。
  • cache_dir (str, Path, 省略可) — キャッシュされたファイルを保存するフォルダへのパス。
  • local_dir (str または Path、任意) — 指定された場合、ダウンロードされたファイルはこのディレクトリ以下に配置されます。
  • user_agent (dict、str、省略可) — 辞書または文字列形式のユーザーエージェント情報。
  • force_download (bool、任意、デフォルトはFalse) — ローカルキャッシュに既に存在する場合でも、ファイルをダウンロードするかどうか。
  • etag_timeout (float, 任意、デフォルトは 10) — ETag を取得する際、サーバーからデータを受信するのを何秒待ってから諦めるかを指定します。この値は httpx2.request に渡されます。
  • token (str, bool, 省略可能) — ダウンロードに使用するトークン。
    • Trueの場合、トークンはHuggingFaceのconfigフォルダから読み取られます。
    • 文字列の場合、認証トークンとして使用されます。
  • local_files_only (bool、任意、デフォルトは False) — True の場合、ファイルのダウンロードを回避し、ローカルにキャッシュされたファイルが存在する場合はそのパスを返します。
  • headers (dict, 省略可) — リクエストに付随して送信する追加のヘッダー。
  • endpoint (str, 省略可) — リクエストを送信する Hub のエンドポイントです。デフォルトでは HF_ENDPOINT の値が使用されます。
  • tqdm_class (tqdm、任意) — 指定された場合、プログレスバーのデフォルトの動作を上書きします。渡される引数はtqdm.auto.tqdmを継承するか、少なくともその動作を模倣している必要があります。デフォルトでは、HF_HUB_DISABLE_PROGRESS_BARS環境変数を設定することで無効化できる、HF独自のプログレスバーが使用されます。
  • dry_run (bool、省略可、デフォルトはFalse) — Trueの場合、ファイルをダウンロードせずにドライランを実行します。ダウンロードされる内容に関する情報を含むDryRunFileInfoオブジェクトを返します。

戻り値

str または DryRunFileInfo

  • dry_run=Falseの場合: ファイルのローカルパス、またはネットワークがオフの場合はディスクにキャッシュされたファイルの最終バージョン。
  • dry_run=Trueの場合: ダウンロード情報を含むDryRunFileInfoオブジェクト。

例外

RepositoryNotFoundError または RevisionNotFoundError または ~utils.RemoteEntryNotFoundError または LocalEntryNotFoundError または EnvironmentError または OSError または ValueError

  • RepositoryNotFoundError — ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、privateに設定されておりアクセス権限がないことが原因です。
  • RevisionNotFoundError — ダウンロード元のリビジョンが見つからない場合。
  • ~utils.RemoteEntryNotFoundError — ダウンロード対象のファイルが見つからない場合。
  • LocalEntryNotFoundError — ネットワークが無効または利用不可で、ファイルがキャッシュに見つからない場合。
  • EnvironmentError — token=True であるが、トークンが見つからない場合。
  • OSError — ETag を決定できない場合。
  • ValueError — パラメータの値が無効な場合。

ローカルキャッシュに存在しない場合、指定されたファイルをダウンロードします。

新しいキャッシュファイルのレイアウトは以下のようになります:

  • cache ディレクトリには、repo_id ごとに1つのサブフォルダが含まれます（リポジトリタイプで名前空間が区切られています）。
  • 各リポジトリフォルダ内には以下が含まれます:
    • refs は、最新既知の revision => commit_hash のペアのリストです
    • blobsには、実際のファイルのブロブが含まれています（LFSファイルかどうかによって、git-shaまたはsha256で識別されます）。
    • snapshotsにはコミットごとに1つのサブフォルダが含まれており、各「コミット」には、その特定のコミット時点で解決されたファイルのサブセットが含まれます。各ファイル名は、その特定のコミット時点のblobへのシンボリックリンクです。
[  96]  .
└── [ 160]  models--julien-c--EsperBERTo-small
    ├── [ 160]  blobs
    │   ├── [321M]  403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
    │   ├── [ 398]  7cb18dc9bafbfcf74629a4b760af1b160957a83e
    │   └── [1.4K]  d7edf6bd2a681fb0175f7735299831ee1b22b812
    ├── [  96]  refs
    │   └── [  40]  main
    └── [ 128]  snapshots
        ├── [ 128]  2439f60ef33a0d46d85da5001d52aeda5b00ce9f
        │   ├── [  52]  README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
        │   └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
        └── [ 128]  bbc77c8132af1cc5cf678da3f1ddf2de43606d48
            ├── [  52]  README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
            └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd

local_dir が指定されている場合、リポジトリのファイル構造がこの場所に複製されます。このオプションを使用すると、cache_dir は使用されず、local_dir のルートに .cache/huggingface/ フォルダが作成され、ダウンロードされたファイルに関連する一部のメタデータが保存されます。この仕組みはメインのキャッシュシステムほど堅牢ではありませんが、リポジトリの最新バージョンを定期的に取得するために最適化されています。

hf_hub_url

huggingface_hub.hf_hub_url

< >

( repo_id: strfilename: strsubfolder: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Noneendpoint: str | None = None )

パラメータ

  • repo_id (str) — / で区切られた、名前空間(ユーザーまたは組織)名とリポジトリ名。
  • filename (str) — リポジトリ内のファイル名です。
  • subfolder (str、省略可) — リポジトリ内のフォルダーに対応する省略可能な値。
  • repo_type (str, 任意) — データセット、スペース、またはカーネルのリポジトリからダウンロードする場合は "dataset"、"space"、または "kernel" を設定し、モデルからダウンロードする場合は None または "model" を設定します。デフォルトは None です。
  • revision (str, 省略可) — ブランチ名、タグ、またはコミットハッシュである、任意の Git リビジョン ID。
  • endpoint (str, 省略可) — リクエストを送信する Hub のエンドポイントです。デフォルトでは HF_ENDPOINT の値が使用されます。

与えられた情報からファイルのURLを構築します。

解決されたアドレスは、huggingface.coでホストされているURLであるか、数MBを超える大きなファイル用のCloudfront（コンテンツ配信ネットワーク、CDN）へのリンクのいずれかです。

例:

>>> from huggingface_hub import hf_hub_url

>>> hf_hub_url(
...     repo_id="julien-c/EsperBERTo-small", filename="pytorch_model.bin"
... )
'https://huggingface.co/julien-c/EsperBERTo-small/resolve/main/pytorch_model.bin'

注:

Cloudfrontは世界中にレプリカが展開されているため、エンドユーザーからのダウンロード速度が大幅に向上します（また、帯域幅コストの削減にもつながります）。

Cloudfront はデフォルトでファイルを積極的にキャッシュします（デフォルトの TTL は 24 時間）が、huggingface.co では git ベースのバージョン管理システムを実装しているため、ここでは問題になりません。つまり、S3/Cloudfront 上のファイルはコンテンツアドレス方式で保存されており（ファイル名がそのハッシュ値である）、コンテンツアドレス方式のファイル名を使用することで、キャッシュが古くなることは決してありません。

このライブラリにおけるクライアントサイドのキャッシュについて、キャッシュはオブジェクトのエンティティタグ（ETag）に基づいています。ETagは、リソースの特定のバージョンを識別する識別子です[1]_。オブジェクトのETagは、gitに保存されている場合はそのgit-sha1、git-lfsに保存されている場合はそのsha256です。

参考文献:

リポジトリのスナップショットをダウンロード

huggingface_hub.snapshot_download

< >

( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_dir: str | pathlib.Path | None = Nonelibrary_name: str | None = Nonelibrary_version: str | None = Noneuser_agent: dict | str | None = Noneetag_timeout: float = 10force_download: bool = Falsetoken: bool | str | None = Nonelocal_files_only: bool = Falseallow_patterns: list[str] | str | None = Noneignore_patterns: list[str] | str | None = Nonemax_workers: int = 8tqdm_class: type[tqdm.asyncio.tqdm_asyncio] | None = Noneheaders: dict[str, str] | None = Noneendpoint: str | None = Nonedry_run: bool = False ) → str or list of DryRunFileInfo

パラメータ

  • repo_id (str) — / で区切られたユーザー名または組織名とリポジトリ名。
  • repo_type (str, 任意) — データセット、スペース、またはカーネルのリポジトリからダウンロードする場合は "dataset"、"space"、または "kernel" を設定し、モデルからダウンロードする場合は None または "model" を設定します。デフォルトは None です。
  • revision (str, 省略可) — 任意の Git リビジョン ID。ブランチ名、タグ、またはコミットハッシュを指定できます。
  • cache_dir (str, Path, 省略可) — キャッシュされたファイルを保存するフォルダへのパス。
  • local_dir (str または Path、省略可能) — 指定された場合、ダウンロードされたファイルはこのディレクトリ以下に配置されます。
  • library_name (str, 省略可) — オブジェクトが対応するライブラリの名前です。
  • library_version (str, 省略可) — ライブラリのバージョンです。
  • user_agent (str, dict, 省略可) — 辞書または文字列形式のユーザーエージェント情報。
  • etag_timeout (float, 任意、デフォルトは 10) — ETag を取得する際、サーバーからデータを受信するのを何秒待ってから諦めるかを指定します。この値は httpx2.request に渡されます。
  • force_download (bool、省略可、デフォルトはFalse) — ローカルキャッシュに既に存在する場合でも、ファイルをダウンロードするかどうか。
  • token (str, bool, 省略可能) — ダウンロードに使用するトークン。
    • Trueの場合、トークンはHuggingFaceのconfigフォルダから読み取られます。
    • 文字列の場合、認証トークンとして使用されます。
  • headers (dict, 任意) — リクエストに含める追加のヘッダーです。これらのヘッダーは、他のヘッダーよりも優先されます。
  • endpoint (str, 省略可) — リクエストを送信する Hub のエンドポイントです。デフォルトでは HF_ENDPOINT の値が使用されます。
  • local_files_only (bool、省略可、デフォルトはFalse) — Trueの場合、cache_dirまたはlocal_dirに存在しない場合でも、ファイルをダウンロードしません。
  • allow_patterns (list[str] または str、省略可) — 指定された場合、少なくとも1つのパターンに一致するファイルのみがダウンロードされます。
  • ignore_patterns (list[str] または str、省略可) — 指定された場合、これらのパターンのいずれかに一致するファイルはダウンロードされません。
  • max_workers (int, 任意) — ファイルをダウンロードするための同時実行スレッド数（1スレッド = 1ファイルのダウンロード）です。 デフォルト値は 8 です。
  • tqdm_class (tqdm、任意) — 指定された場合、プログレスバーのデフォルトの動作を上書きします。渡される引数はtqdm.auto.tqdmを継承するか、少なくともその動作を模倣している必要があります。なお、tqdm_classは個々のダウンロードには渡されません。デフォルトでは、HF_HUB_DISABLE_PROGRESS_BARS環境変数を設定することで無効化できる、HF独自のプログレスバーが使用されます。
  • dry_run (bool、省略可、デフォルトは False) — True の場合、ファイルをダウンロードせずにドライランを実行します。ダウンロードされる内容に関する情報が含まれる DryRunFileInfo オブジェクトのリストを返します。

戻り値

str または DryRunFileInfo のリスト

  • dry_run=Falseの場合: ローカルスナップショットのパス。
  • dry_run=Trueの場合: ダウンロード情報を含むDryRunFileInfoオブジェクトのリスト。

例外

RepositoryNotFoundError または RevisionNotFoundError または IncompleteSnapshotError または EnvironmentError または OSError または ValueError

  • RepositoryNotFoundError — ダウンロード元のリポジトリが見つからない場合に発生します。リポジトリが存在しないか、privateに設定されておりアクセス権限がないことが原因である可能性があります。
  • RevisionNotFoundError — ダウンロード元のリビジョンが見つからない場合。
  • IncompleteSnapshotError — Hub に接続できない場合（オフライン、接続の問題、または local_files_only=True）で、キャッシュされたスナップショットに要求されたファイルの一部が欠けている場合に発生します。
  • EnvironmentError — token=Trueが設定されている場合で、トークンが見つからない場合に発生します。
  • OSError — ETag を決定できない場合。
  • ValueError — パラメータの値が無効な場合。

リポジトリのファイルをダウンロードします。

指定されたリビジョンのリポジトリのファイルのスナップショット全体をダウンロードします。事前にどのファイルが必要かがわからない場合、リポジトリのすべてのファイルが必要になる場合に便利です。すべてのファイルは、そのフォルダに対するパスとファイル名を保持するために、フォルダ内にネストされます。allow_patternsとignore_patternsを使用して、ダウンロードするファイルをフィルタリングすることもできます。

local_dir が指定されている場合、リポジトリのファイル構造がこの場所に複製されます。このオプションを使用すると、cache_dir は使用されず、local_dir のルートに .cache/huggingface/ フォルダが作成され、ダウンロードされたファイルに関連する一部のメタデータが保存されます。この仕組みはメインのキャッシュシステムほど堅牢ではありませんが、リポジトリの最新バージョンを定期的に取得する用途に最適化されています。

代替案としてリポジトリをクローンする方法がありますが、これにはgitとgit-lfsがインストールされ、正しく設定されている必要があります。また、gitを使用してリポジトリをクローンする際、ダウンロードするファイルをフィルタリングすることはできません。

キャッシュされたリポジトリツリーを読み取る

huggingface_hub.get_cached_repo_tree

< >

( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_dir: str | pathlib.Path | None = None ) → list[RepoFile]

パラメータ

  • repo_id (str) — / で区切られたユーザー名または組織名とリポジトリ名。
  • repo_type (str, 省略可) — データセット、スペース、またはカーネルのリポジトリから一覧を取得する場合は "dataset"、"space"、または "kernel" を設定し、モデルから一覧を取得する場合は None または "model" を設定します。デフォルトは None です。
  • revision (str, 省略可) — 任意の Git リビジョン ID。ブランチ名、タグ、またはコミットハッシュを指定できます。デフォルトでは、デフォルトブランチが使用されます。ブランチ名/タグ名は、ローカルキャッシュ (refs/) を使用してコミットハッシュに解決されます。
  • cache_dir (str, Path, 省略可) — キャッシュされたファイルを保存するフォルダへのパスです。デフォルトではHF_HUB_CACHEの値が使用されます。
  • local_dir (str または Path、省略可) — 指定された場合、メインのキャッシュではなく、local_dir によるダウンロードでキャッシュされたツリー一覧（local_dir/.cache/huggingface/ から）を読み込みます。ブランチやタグのリビジョンは、引き続きメインのキャッシュ（cache_dir）を使用してコミットハッシュに解決されます。

戻り値

list[RepoFile]

このリビジョン用にキャッシュされたRepoFileオブジェクトのリスト。

例外

CachedRepoTreeNotFoundError

  • CachedRepoTreeNotFoundError — 要求されたリビジョンのツリー一覧がキャッシュされていない場合（例：そのリビジョンでリポジトリが一度もダウンロードされていない場合）。

指定されたリビジョンのリポジトリのキャッシュされたツリー一覧を、ネットワーク呼び出しなしで返します。

ツリー一覧は、リポジトリの特定のコミット時点のファイルセット（ダウンロードメタデータ付き）です。snapshot_download() の実行時にディスク上に副次的に生成されます（trees/<commit_hash>.json キャッシュファイルをご参照ください）。以降のダウンロード時にネットワーク呼び出しをスキップするために使用されます。この関数は、そのキャッシュを直接公開します。

Hub上のリポジトリの現在のツリー一覧が必要な場合は、代わりにlist_repo_tree()を使用してください。

例:

>>> from huggingface_hub import get_cached_repo_tree
>>> files = get_cached_repo_tree("openai-community/gpt2")
>>> [f.path for f in files]
['.gitattributes', 'config.json', 'model.safetensors', ...]

リビジョンを解決

ブランチ名またはタグ名を一度だけコミットハッシュに解決し、その結果を渡すことで、すべてのダウンロードを同じコミットに固定します。HfApi.resolve_revision()およびキャッシュシステムのガイドを参照してください。

ResolvedRevision

クラス huggingface_hub.ResolvedRevision

< >

( resolved: strinitial: str | None = Nonerepo_id: str | None = Nonerepo_type: str | None = None )

パラメータ

  • initial (str または None) — ユーザーが最初に要求したリビジョンです。None の場合、文字列の値はデフォルトで "main" になります。
  • resolved (str) — initial が解決されるコミットハッシュです。

すでにコミットハッシュに解決済みのgitリビジョン。

ResolvedRevision は str のサブクラスであるため、revision 引数を受け取る huggingface_hub の任意のメソッドに渡すことができます。その文字列値は、ユーザーが最初に要求したリビジョン（例: "main"、"refs/pr/4"）であり、URL やエラーメッセージの可読性を保ちます。一方、.resolved には、そのリビジョンが指すコミットハッシュが保持されます。

インスタンスは、revision -> commit hash のマッピングもローカルキャッシュ（refs/ フォルダ）にキャッシュする HfApi.resolve_revision() によって構築されます。

コミットハッシュは、解決されたリポジトリに対してのみ意味を持つため、インスタンスはそのリポジトリも記憶します。別のリポジトリに対して再解決することはエラーではありません。最初に要求されたリビジョンが再度解決されます（HfApi.resolve_revision()を参照）。

例:

>>> from huggingface_hub import resolve_revision
>>> revision = resolve_revision("openai-community/gpt2")
>>> revision
ResolvedRevision(initial=None, resolved='607a30d783dfa663caf39e06633721c8d4cfcd7e')
>>> revision == "main"  # it's a string
True
>>> revision.resolved
'607a30d783dfa663caf39e06633721c8d4cfcd7e'

ファイルのメタデータを取得する

get_hf_file_metadata

huggingface_hub.get_hf_file_metadata

< >

( url: strtoken: bool | str | None = Nonetimeout: float | None = 10library_name: str | None = Nonelibrary_version: str | None = Noneuser_agent: dict | str | None = Noneheaders: dict[str, str] | None = Noneendpoint: str | None = Noneretry_on_errors: bool = False )

パラメータ

  • url (str) — ファイルの URL。例えば、hf_hub_url() が返すものなど。
  • token (str または bool, 省略可能) — ダウンロードに使用するトークン。True の場合、HuggingFace の設定フォルダからトークンを読み込みます。False または None の場合、トークンは提供されません。文字列の場合、認証トークンとして使用されます。
    • Trueの場合、トークンはHuggingFaceのconfigフォルダから読み取られます。
    • FalseまたはNoneの場合、トークンは提供されません。
    • 文字列の場合、認証トークンとして使用されます。
  • timeout (float、任意、デフォルト値は 10)— サーバーがメタデータを送信するのを、諦める前に何秒間待つかを指定します。
  • library_name (str, 省略可) — オブジェクトが対応するライブラリの名前です。
  • library_version (str, 省略可) — ライブラリのバージョンです。
  • user_agent (dict、str、省略可) — 辞書または文字列形式のユーザーエージェント情報。
  • headers (dict, 省略可) — リクエストに付随して送信する追加のヘッダー。
  • endpoint (str, 省略可) — Hub のエンドポイントです。デフォルト値は https://huggingface.co です。
  • retry_on_errors (bool、任意、デフォルトはFalse) — エラー（429、5xx、タイムアウト、ネットワークエラー）が発生した際にリトライを行うかどうか。False の場合、ローカルキャッシュへの高速なフォールバックのためにリトライは行われません。

指定されたURLの、Hub上でバージョン管理されているファイルのメタデータを取得します。

HfFileMetadata

クラス huggingface_hub.HfFileMetadata

< >

( commit_hash: str | Noneetag: str | Nonelocation: strsize: int | Nonexet_file_data: huggingface_hub.utils._xet.XetFileData | None )

パラメータ

  • commit_hash (str, 省略可) — ファイルに関連する commit_hash。
  • etag (str, 省略可) — サーバー上のファイルの Etag。
  • location (str) — ファイルをダウンロードする場所。Hub の URL または CDN のいずれかです。
  • size (size) — ファイルのサイズ。LFSファイルの場合、ポインタではなく実際のLFSファイルのサイズが含まれます。
  • xet_file_data (XetFileData、任意) — ファイルの Xet 情報です。ファイルが Xet ストレージで保存されている場合のみ設定されます。

Hubでバージョン管理されているファイルに関する情報を含むデータ構造。

URLに基づいてget_hf_file_metadata()によって返されます。

キャッシュ

上記に表示されているメソッドは、ファイルの再ダウンロードを防ぐキャッシュシステムと連携するように設計されています。このキャッシュシステムは v0.8.0 で更新され、Hub に依存するライブラリ全体で共有される中央キャッシュシステムとなりました。

HFでのキャッシュの詳細な説明については、キャッシュシステムのガイドをお読みください。

Update on GitHub

←CLI ミックスインとシリアライズメソッド→