Hub Python 库文档
文件系统 API (Filesystem API)
并获得增强的文档体验
开始使用
文件系统 API
HfFileSystem 类提供了一个基于 fsspec 的 Pythonic 文件接口，用于访问 Hugging Face Hub。
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 提供了 fsspec 兼容性，这对于需要该功能的库（例如直接使用
pandas读取 Hugging Face 数据集）非常有用。但是，由于这种兼容层，它会引入额外的开销。为了获得更好的性能和可靠性，建议尽可能使用HfApi方法。
该文件系统支持 hf:// 协议的路径，该协议遵循以下 URL 方案：
- 模型、数据集和 Space 仓库
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)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。