Hugging Face 的 LOGO

Hub Python 庫文件

下載檔案

Hugging Face's logo
加入 Hugging Face 社群

並獲得增強的文件體驗

開始使用

下載檔案

下載單個檔案

hf_hub_download

huggingface_hub.hf_hub_download

< >

( repo_id: str filename: str subfolder: typing.Optional[str] = None repo_type: typing.Optional[str] = None revision: typing.Optional[str] = None library_name: typing.Optional[str] = None library_version: typing.Optional[str] = None cache_dir: typing.Union[str, pathlib.Path, NoneType] = None local_dir: typing.Union[str, pathlib.Path, NoneType] = None user_agent: typing.Union[dict, str, NoneType] = None force_download: bool = False etag_timeout: float = 10 token: typing.Union[bool, str, NoneType] = None local_files_only: bool = False headers: typing.Optional[dict[str, str]] = None endpoint: typing.Optional[str] = None tqdm_class: typing.Optional[type[tqdm.asyncio.tqdm_asyncio]] = None dry_run: bool = False ) → str 或 DryRunFileInfo

引數

  • repo_id (str) — 倉庫中的使用者或組織名稱，用 / 分隔。
  • filename (str) — 倉庫中的檔名。
  • subfolder (str, 可選) — 對應模型倉庫內某個資料夾的可選值。
  • repo_type (str, 可選) — 如果從資料集或 Space 下載，則設定為 "dataset" 或 "space"，如果從模型下載，則設定為 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 時，等待伺服器傳送資料直至超時的秒數，該值將傳遞給 requests.request。
  • token (str, bool, 可選) — 用於下載的 token。
    • 如果為 True，則從 HuggingFace 配置資料夾讀取 token。
    • 如果為字串，則用作身份驗證 token。
  • local_files_only (bool, 可選, 預設為 False) — 如果為 True，則避免下載檔案，如果檔案存在於本地快取中，則返回其路徑。
  • headers (dict, 可選) — 請求的附加標頭。
  • tqdm_class (tqdm, 可選) — 如果提供，將覆蓋進度條的預設行為。傳入的引數必須繼承自 tqdm.auto.tqdm 或至少模仿其行為。預設為自定義 HF 進度條，可透過設定 HF_HUB_DISABLE_PROGRESS_BARS 環境變數停用。
  • 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 但找不到 token。
  • OSError — 如果 ETag 無法確定。
  • ValueError — 如果某些引數值無效。

如果檔案尚未存在於本地快取中，則下載給定檔案。

新的快取檔案佈局如下所示

  • 快取目錄包含每個 repo_id 的子資料夾（按 repo 型別名稱空間）
  • 每個倉庫資料夾內
    • refs 是最新已知修訂版 => commit_hash 對的列表
    • blobs 包含實際的檔案 blobs（由其 git-sha 或 sha256 標識，取決於它們是否為 LFS 檔案）
    • snapshots 包含每個提交的子資料夾，每個“提交”包含在該特定提交時解析的檔案子集。每個檔名都是指向該特定提交的 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: str filename: str subfolder: typing.Optional[str] = None repo_type: typing.Optional[str] = None revision: typing.Optional[str] = None endpoint: typing.Optional[str] = None )

引數

  • repo_id (str) — 名稱空間（使用者或組織）名稱和倉庫名稱，由 / 分隔。
  • filename (str) — 倉庫中的檔名。
  • subfolder (str, optional) — 倉庫內某個資料夾的可選值。
  • repo_type (str, optional) — 如果從資料集或空間下載，則設定為 "dataset" 或 "space"，如果從模型下載，則設定為 None 或 "model"。預設為 None。
  • revision (str, optional) — 一個可選的 Git 修訂 ID，可以是分支名稱、標籤或提交雜湊。

從給定資訊構建檔案的 URL。

解析後的地址可以是託管在 huggingface.co 上的 URL，也可以是到 Cloudfront（內容分發網路，簡稱 CDN）的連結，用於下載大小超過幾 MB 的大檔案。

示例

>>> 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），它是資源特定版本的識別符號 [1]_。物件的 ETag 是：如果儲存在 Git 中，則為其 git-sha1；如果儲存在 git-lfs 中，則為其 sha256。

參考文獻

下載倉庫快照

huggingface_hub.snapshot_download

< >

( repo_id: str repo_type: typing.Optional[str] = None revision: typing.Optional[str] = None cache_dir: typing.Union[str, pathlib.Path, NoneType] = None local_dir: typing.Union[str, pathlib.Path, NoneType] = None library_name: typing.Optional[str] = None library_version: typing.Optional[str] = None user_agent: typing.Union[dict, str, NoneType] = None etag_timeout: float = 10 force_download: bool = False token: typing.Union[str, bool, NoneType] = None local_files_only: bool = False allow_patterns: typing.Union[list[str], str, NoneType] = None ignore_patterns: typing.Union[list[str], str, NoneType] = None max_workers: int = 8 tqdm_class: typing.Optional[type[tqdm.asyncio.tqdm_asyncio]] = None headers: typing.Optional[dict[str, str]] = None endpoint: typing.Optional[str] = None dry_run: bool = False ) → str 或 DryRunFileInfo 列表

引數

  • repo_id (str) — 使用者名稱或組織名和倉庫名稱，由 / 分隔。
  • repo_type (str, optional) — 如果從資料集或空間下載，則設定為 "dataset" 或 "space"，如果從模型下載，則設定為 None 或 "model"。預設為 None。
  • revision (str, optional) — 一個可選的 Git 修訂 ID，可以是分支名稱、標籤或提交雜湊。
  • cache_dir (str, Path, optional) — 快取檔案儲存的資料夾路徑。
  • local_dir (str 或 Path, optional) — 如果提供，下載的檔案將放在此目錄下方。
  • library_name (str, optional) — 物件所對應庫的名稱。
  • library_version (str, optional) — 庫的版本。
  • user_agent (str, dict, optional) — 使用者代理資訊，可以是字典或字串形式。
  • etag_timeout (float, optional, defaults to 10) — 獲取 ETag 時，伺服器在放棄之前等待資料傳送的秒數，該值會傳遞給 httpx.request。
  • force_download (bool, optional, defaults to False) — 檔案是否應該被下載，即使它已存在於本地快取中。
  • token (str, bool, optional) — 用於下載的令牌。
    • 如果為 True，則從 HuggingFace 配置資料夾讀取令牌。
    • 如果為字串，則用作身份驗證令牌。
  • headers (dict, optional) — 請求中包含的其他標頭。這些標頭優先於其他標頭。
  • local_files_only (bool, optional, defaults to False) — 如果為 True，則避免下載檔案，如果檔案已存在於本地快取中，則返回本地快取檔案的路徑。
  • allow_patterns (list[str] 或 str, optional) — 如果提供，則僅下載匹配至少一個模式的檔案。
  • ignore_patterns (list[str] 或 str, optional) — 如果提供，則不下載匹配任何模式的檔案。
  • max_workers (int, optional) — 下載檔案的併發執行緒數（1 執行緒 = 1 個檔案下載）。預設為 8。
  • tqdm_class (tqdm, optional) — 如果提供，則覆蓋進度條的預設行為。傳遞的引數必須繼承自 tqdm.auto.tqdm 或至少模仿其行為。請注意，tqdm_class 未傳遞給每個單獨的下載。預設為自定義 HF 進度條，可透過設定 HF_HUB_DISABLE_PROGRESS_BARS 環境變數來停用。
  • dry_run (bool, optional, 預設為 False) — 如果為 True，則執行模擬執行，而不實際下載檔案。返回一個包含有關將要下載的內容的資訊的 DryRunFileInfo 物件列表。

返回

str 或 DryRunFileInfo 物件列表

  • 如果 dry_run=False：本地快照路徑。
  • 如果 dry_run=True：一個 DryRunFileInfo 物件列表，包含下載資訊。

引發

RepositoryNotFoundError 或 RevisionNotFoundError 或 EnvironmentError 或 OSError 或 ValueError

下載倉庫檔案。

下載指定版本倉庫的整個檔案快照。這對於您需要倉庫中的所有檔案的情況非常有用，因為您事先不知道需要哪些檔案。所有檔案都巢狀在一個資料夾中，以保留它們相對於該資料夾的實際檔名。您還可以使用 allow_patterns 和 ignore_patterns 過濾要下載的檔案。

如果提供了 local_dir，則倉庫的檔案結構將在此位置複製。使用此選項時，不會使用 cache_dir，並且將在 local_dir 的根目錄中建立一個 .cache/huggingface/ 資料夾來儲存與下載檔案相關的某些元資料。雖然此機制不如主快取系統健壯，但它針對定期拉取倉庫的最新版本進行了最佳化。

另一種方法是克隆倉庫，但這需要安裝並正確配置 git 和 git-lfs。使用 git 克隆倉庫時，也無法過濾要下載的檔案。

獲取檔案的元資料

get_hf_file_metadata

huggingface_hub.get_hf_file_metadata

< >

( url: str token: typing.Union[bool, str, NoneType] = None timeout: typing.Optional[float] = 10 library_name: typing.Optional[str] = None library_version: typing.Optional[str] = None user_agent: typing.Union[dict, str, NoneType] = None headers: typing.Optional[dict[str, str]] = None endpoint: typing.Optional[str] = None retry_on_errors: bool = False )

引數

  • url (str) — 檔案 URL，例如由 hf_hub_url() 返回。
  • token (str 或 bool, optional) — 用於下載的 token。
    • 如果為 True，則 token 從 HuggingFace 配置資料夾中讀取。
    • 如果為 False 或 None，則不提供 token。
    • 如果為字串，則用作身份驗證 token。
  • timeout (float, optional, 預設為 10) — 等待伺服器傳送元資料的時間（秒），超時後放棄。
  • library_name (str, optional) — 與物件對應的庫的名稱。
  • library_version (str, optional) — 庫的版本。
  • user_agent (dict, str, optional) — 使用者代理資訊，以字典或字串形式。
  • headers (dict, optional) — 與請求一起傳送的其他標頭。
  • endpoint (str, optional) — Hub 的終結點。預設為 https://huggingface.co。
  • retry_on_errors (bool, optional, 預設為 False) — 是否在出錯時重試（429、5xx、超時、網路錯誤）。如果為 False，則不重試，以快速回退到本地快取。

獲取 Hub 上版本化檔案的元資料。

HfFileMetadata

class huggingface_hub.HfFileMetadata

< >

( commit_hash: typing.Optional[str] etag: typing.Optional[str] location: str size: typing.Optional[int] xet_file_data: typing.Optional[huggingface_hub.utils._xet.XetFileData] )

引數

  • commit_hash (str, optional) — 與檔案相關的 commit_hash。
  • etag (str, optional) — 伺服器上檔案的 Etag。
  • location (str) — 下載檔案的位置。可以是 Hub URL 或 CDN。
  • size (size) — 檔案大小。對於 LFS 檔案，包含實際 LFS 檔案的大小，而不是指標。
  • xet_file_data (XetFileData, optional) — 檔案的 Xet 資訊。僅當檔案使用 Xet 儲存時才設定。

包含 Hub 上版本化檔案資訊的結構化資料。

由 get_hf_file_metadata() 根據 URL 返回。

快取

上面顯示的方法旨在與防止重複下載檔案的快取系統一起使用。快取系統在 v0.8.0 中進行了更新，成為跨依賴 Hub 的庫共享的中央快取系統。

有關 HF 快取的詳細介紹，請閱讀 快取系統指南。

在 GitHub 上更新

←CLI Mixins & 序列化方法→
© . This site is unofficial and not affiliated with Hugging Face, Inc.