Hub Python 函式庫文件
Filesystem API
並獲得增強的文件體驗
開始使用
Filesystem API
HfFileSystem 類別提供了一個基於 fsspec 的 Hugging Face Hub Python 風格檔案介面。
HfFileSystem
HfFileSystem 是基於 fsspec 建構的，因此它與該函式庫提供的大多數 API 相容。欲了解更多詳細資訊，請參閱我們的指南以及 fsspec 的 API 參考。
class huggingface_hub.HfFileSystem
< 原始碼 >( *args **kwargs )
參數
- endpoint (
str, 選填) — Hub 的端點。預設為 https://huggingface.co。 - token (
bool或str, 選填) — 有效的使用者存取權杖（字串）。預設為本地儲存的權杖，這是推薦的身份驗證方法（請參閱 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。若要停用身份驗證，請傳入False。 - block_size (
int, 選填) — 讀取與寫入檔案的區塊大小。 - expand_info (
bool, 選填) — 是否展開檔案資訊。 - **storage_options (
dict, 選填) — 檔案系統的額外選項。請參閱 fsspec 文件。
像存取本地檔案系統一樣存取遠端的 Hugging Face Hub 儲存庫。
[!WARNING][HfFileSystem](/docs/huggingface_hub/v1.16.2/en/package_reference/hf_file_system#huggingface_hub.HfFileSystem) 提供了 fsspec 相容性，這對於需要它的程式庫（例如直接使用
pandas讀取 Hugging Face 資料集）很有用。然而，由於此相容層，它會帶來額外的開銷。為了獲得更好的效能與可靠性，建議在可能的情況下使用HfApi方法。
該檔案系統支援 hf:// 協定的路徑，遵循以下 URL 架構：
- 模型、資料集與 Spaces 儲存庫
hf://<repo-id>[@<revision>]/<path/in/repo>
hf://datasets/<repo-id>[@<revision>]/<path/in/repo>
hf://spaces/<repo-id>[@<revision>]/<path/in/repo>注意：直接使用 HfFileSystem 時，路徑中的 hf:// 協定字首是選填的。
用法
>>> from huggingface_hub import hffs
>>> # List files
>>> hffs.glob("my-username/my-model/*.bin")
['my-username/my-model/pytorch_model.bin']
>>> hffs.ls("datasets/my-username/my-dataset", detail=False)
['datasets/my-username/my-dataset/.gitattributes', 'datasets/my-username/my-dataset/README.md', 'datasets/my-username/my-dataset/data.json']
>>> # Read/write files
>>> with hffs.open("my-username/my-model/pytorch_model.bin") as f:
... data = f.read()
>>> with hffs.open("my-username/my-model/pytorch_model.bin", "wb") as f:
... f.write(data)指定身份驗證用的權杖 (token)
>>> from huggingface_hub import HfFileSystem
>>> hffs = HfFileSystem(token=token)cp_file
< 原始碼 >( path1: str path2: str revision: str | None = None **kwargs )
在儲存庫內或儲存庫之間複製檔案。
注意：在可能的情況下，請使用
HfApi.upload_file()以獲得更好的效能。
find
< 原始碼 >( path: str maxdepth: int | None = None withdirs: bool = False detail: bool = False refresh: bool = False revision: str | None = None **kwargs ) → Union[list[str], dict[str, dict[str, Any]]]
參數
- path (
str) — 用於列出檔案的根路徑。 - maxdepth (
int, 選填) — 深入子目錄的最大深度。 - withdirs (
bool, 選填) — 在輸出中包含目錄路徑。預設為 False。 - detail (
bool, 選填) — 若為 True，則回傳一個將路徑映射至檔案資訊的字典。預設為 False。 - refresh (
bool, 選填) — 若為 True，則繞過快取並獲取最新資料。預設為 False。 - revision (
str, 選填) — 要列出的 git 修訂版本。
返回
Union[list[str], dict[str, dict[str, Any]]]
路徑清單或檔案資訊字典。
列出路徑下的所有檔案。
欲了解更多詳細資訊，請參閱 fsspec 文件。
get_file
< 原始碼 >( rpath lpath callback = <fsspec.callbacks.NoOpCallback object at 0x7f3f1823ffa0> outfile = None **kwargs )
將單一遠端檔案複製到本地。
注意：在可能的情況下，請使用
HfApi.hf_hub_download()或HfApi.download_bucket_files以獲得更好的效能。
glob
< 原始碼 >( path: str maxdepth: int | None = None **kwargs ) → list[str]
透過 glob 匹配尋找檔案。
欲了解更多詳細資訊，請參閱 fsspec 文件。
info
< 原始碼 >( path: str refresh: bool = False revision: str | None = None **kwargs ) → dict[str, Any]
取得有關檔案或目錄的資訊。
欲了解更多詳細資訊，請參閱 fsspec 文件。
注意：在可能的情況下，請使用
HfApi.get_paths_info()或HfApi.repo_info()以獲得更好的效能（或者針對儲存桶使用HfApi.get_bucket_paths_info()或HfApi.bucket_info()）。
清除給定路徑的快取。
欲了解更多詳細資訊，請參閱 fsspec 文件。
檢查路徑是否為目錄。
欲了解更多詳細資訊，請參閱 fsspec 文件。
檢查路徑是否為檔案。
欲了解更多詳細資訊，請參閱 fsspec 文件。
ls
< 原始碼 >( path: str detail: bool = True refresh: bool = False revision: str | None = None **kwargs ) → list[Union[str, dict[str, Any]]]
列出目錄內容。
欲了解更多詳細資訊，請參閱 fsspec 文件。
注意：在可能的情況下，請使用
HfApi.list_repo_tree()以獲得更好的效能。
取得檔案的最後修改時間。
欲了解更多詳細資訊，請參閱 fsspec 文件。
resolve_path
< 原始碼 >( path: str revision: str | None = None ) → HfFileSystemResolvedPath
將 Hugging Face 檔案系統路徑解析為其組成部分。
rm
< 原始碼 >( path: str recursive: bool = False maxdepth: int | None = None revision: str | None = None **kwargs )
從儲存庫中刪除檔案。
更多詳細資訊，請參閱 fsspec 文件。
注意：若可能，請使用
HfApi.delete_file()以獲得更好的效能。
取得給定路徑的 HTTP URL。