下載檔案

下載單個檔案

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[typing.Dict, str, NoneType] = None force_download: bool = False proxies: typing.Optional[typing.Dict] = None etag_timeout: float = 10 token: typing.Union[bool, str, NoneType] = None local_files_only: bool = False headers: typing.Optional[typing.Dict[str, str]] = None endpoint: typing.Optional[str] = None resume_download: typing.Optional[bool] = None force_filename: typing.Optional[str] = None local_dir_use_symlinks: typing.Union[bool, typing.Literal['auto']] = 'auto' ) → str

引數

repo_id (str) — 使用者或組織名稱和倉庫名稱，以 / 分隔。
filename (str) — 倉庫中的檔名。
subfolder (str, 可選) — 對應模型倉庫內資料夾的可選值。
repo_type (str, 可選) — 如果從資料集或空間下載，則設定為 "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) — 即使檔案已存在於本地快取中，是否也應下載該檔案。
proxies (dict, 可選) — 對映協議到代理 URL 的字典，傳遞給 requests.request。
etag_timeout (float, 可選, 預設為 10) — 獲取 ETag 時，等待伺服器傳送資料的時間（秒），傳遞給 requests.request。
token (str, bool, 可選) — 用於下載的令牌。
- 如果為 True，則從 HuggingFace 配置資料夾讀取令牌。
- 如果為字串，則用作身份驗證令牌。
local_files_only (bool, 可選, 預設為 False) — 如果為 True，則避免下載檔案，如果檔案存在於本地快取中，則返回其路徑。
headers (dict, 可選) — 請求中包含的額外請求頭。這些請求頭優先於其他請求頭。

字串

檔案的本地路徑，如果網路已關閉，則是磁碟上快取的檔案的最新版本。

引發

RepositoryNotFoundError 或 RevisionNotFoundError 或 EntryNotFoundError 或 LocalEntryNotFoundError 或 EnvironmentError 或 OSError 或 ValueError

RepositoryNotFoundError — 如果要下載的倉庫找不到。這可能是因為倉庫不存在，或者因為倉庫設定為 private 且您沒有訪問許可權。
RevisionNotFoundError — 如果要下載的修訂版本找不到。
EntryNotFoundError — 如果要下載的檔案找不到。
LocalEntryNotFoundError — 如果網路停用或不可用，並且在快取中找不到檔案。
EnvironmentError — 如果 token=True 但找不到令牌。
OSError — 如果無法確定 ETag。
ValueError — 如果某些引數值無效。

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

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

快取目錄包含每個 repo_id 的一個子資料夾（按倉庫型別名稱空間）
在每個倉庫資料夾內
- refs 是最新已知修訂版本 => commit_hash 對的列表
- blobs 包含實際的檔案 blob（由其 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, 可選) — 對應倉庫內資料夾的可選值。
repo_type (str, 可選) — 如果從資料集或空間下載，則設定為 "dataset" 或 "space"；如果從模型下載，則設定為 None 或 "model"。預設為 None。
revision (str, 可選) — 可選的 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。

參考文獻

[1] https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/ETag

下載倉庫快照

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[typing.Dict, str, NoneType] = None proxies: typing.Optional[typing.Dict] = None etag_timeout: float = 10 force_download: bool = False token: typing.Union[bool, str, NoneType] = None local_files_only: bool = False allow_patterns: typing.Union[typing.List[str], str, NoneType] = None ignore_patterns: typing.Union[typing.List[str], str, NoneType] = None max_workers: int = 8 tqdm_class: typing.Optional[typing.Type[tqdm.asyncio.tqdm_asyncio]] = None headers: typing.Optional[typing.Dict[str, str]] = None endpoint: typing.Optional[str] = None local_dir_use_symlinks: typing.Union[bool, typing.Literal['auto']] = 'auto' resume_download: typing.Optional[bool] = None ) → str

引數

repo_id (str) — 使用者或組織名稱以及以 / 分隔的倉庫名稱。
repo_type (str, 可選) — 如果從資料集或空間下載，則設定為 "dataset" 或 "space"；如果從模型下載，則設定為 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, 可選) — 使用者代理資訊，可以是字典或字串形式。
proxies (dict, 可選) — 對映協議到代理 URL 的字典，傳遞給 requests.request。
etag_timeout (float, 可選, 預設為 10) — 獲取 ETag 時，等待伺服器傳送資料的時間（秒），傳遞給 requests.request。
force_download (bool, 可選, 預設為 False) — 即使檔案已存在於本地快取中，是否也應下載該檔案。
token (str, bool, 可選) — 用於下載的令牌。
- 如果為 True，則從 HuggingFace 配置資料夾讀取令牌。
- 如果為字串，則用作身份驗證令牌。
headers (dict, 可選) — 請求中包含的額外請求頭。這些請求頭優先於其他請求頭。
local_files_only (bool, optional,預設為 False) — 如果為 True，則避免下載檔案，如果本地快取檔案存在，則返回其路徑。
allow_patterns (List[str] 或 str, 可選) — 如果提供，則只下載至少匹配一個模式的檔案。
ignore_patterns (List[str] 或 str, 可選) — 如果提供，則不下載匹配任何模式的檔案。
max_workers (int, 可選) — 下載檔案的併發執行緒數 (1 執行緒 = 1 檔案下載)。預設為 8。
tqdm_class (tqdm, 可選) — 如果提供，則覆蓋進度條的預設行為。傳遞的引數必須繼承自 tqdm.auto.tqdm 或至少模仿其行為。請注意，tqdm_class 不會傳遞給每個單獨的下載。預設為自定義的 HF 進度條，可以透過設定 HF_HUB_DISABLE_PROGRESS_BARS 環境變數來停用。

字串

倉庫快照的資料夾路徑。

引發

RepositoryNotFoundError 或 RevisionNotFoundError 或 EnvironmentError 或 OSError 或 ValueError

RepositoryNotFoundError — 如果要下載的倉庫找不到。這可能是因為倉庫不存在，或者因為倉庫設定為 private 且您沒有訪問許可權。
RevisionNotFoundError — 如果要下載的修訂版本找不到。
EnvironmentError — 如果 token=True 但找不到令牌。
OSError — 如果無法確定 ETag。
ValueError — 如果某些引數值無效。

下載倉庫檔案。

下載指定修訂版倉庫檔案的完整快照。當您需要倉庫中的所有檔案，因為您事先不知道需要哪些檔案時，這非常有用。所有檔案都巢狀在一個資料夾中，以保持其相對於該資料夾的實際檔名。您還可以使用 allow_patterns 和 ignore_patterns 篩選要下載的檔案。

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

獲取檔案元資料

get_hf_file_metadata

huggingface_hub.get_hf_file_metadata

< 源 >

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

引數

url (str) — 檔案 URL，例如由 hf_hub_url() 返回。
token (str 或 bool, 可選) — 用於下載的令牌。
- 如果為 True，則從 HuggingFace 配置資料夾中讀取令牌。
- 如果為 False 或 None，則不提供令牌。
- 如果為字串，則用作身份驗證令牌。
proxies (dict, 可選) — 對映協議到代理 URL 的字典，傳遞給 requests.request。
timeout (float, 可選, 預設為 10) — 等待伺服器傳送元資料的時間，單位為秒。
library_name (str, 可選) — 物件對應的庫名稱。
library_version (str, 可選) — 庫的版本。
user_agent (dict, str, 可選) — 使用者代理資訊，以字典或字串形式提供。
headers (dict, 可選) — 請求附帶的附加頭部。
endpoint (str, 可選) — Hub 的端點。預設為 https://huggingface.co。

獲取 Hub 上版本化檔案的元資料，針對給定 URL。

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, 可選) — 與檔案相關的 commit_hash。
etag (str, 可選) — 伺服器上檔案的 Etag。
location (str) — 下載檔案的位置。可以是 Hub URL 或其他（CDN）。
size (size) — 檔案大小。如果是 LFS 檔案，則包含實際 LFS 檔案的大小，而不是指標的大小。
xet_file_data (XetFileData, 可選) — 檔案的 Xet 資訊。僅當檔案使用 Xet 儲存時設定。

包含 Hub 上檔案版本資訊的 Data structure。

由 get_hf_file_metadata() 基於 URL 返回。

快取

上述方法旨在配合快取系統，防止檔案重複下載。快取系統在 v0.8.0 中進行了更新，成為所有依賴於 Hub 的庫共享的中心快取系統。

閱讀快取系統指南，瞭解 HF 快取的詳細介紹。

< > 在 GitHub 上更新

Hub Python 庫