Hub Python Library documentation
文件系统 API
文件系统 API
HfFileSystem 类基于 fsspec，为 Hugging Face Hub 提供了一个符合 Python 风格的文件接口。
HfFileSystem
HfFileSystem 基于 fsspec，因此与其提供的大多数 API 兼容。更多详情，请参阅我们的指南和 fsspec 的API Reference。
class huggingface_hub.HfFileSystem
< source >( *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, 可选) — 是否展开文件的信息。 - max_workers (
int, 可选) — 用于并行列出大型目录的最大并发请求数（参见 find()）。默认值为 16。将其设置为 1 可禁用并行列出。 - live_follow (
bool, 可选) — 是否实时跟踪 Hub 上存储桶中的文件变更，以便缓存的列表保持最新，而无需手动调用 HfFileSystem.invalidate_cache()。 启用后，列出存储桶时会打开到该存储桶 Hub 事件流的后台连接。 对模型、数据集和空间仓库没有影响（Hub 不为这些仓库提供变更事件流）。 - **storage_options (
dict, 可选) — 文件系统的其他选项。请参阅 fsspec 文档。
将远程 Hugging Face 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)cp_file
< source >( path1: strpath2: strrevision: str | None = None**kwargs )
在仓库内部或仓库之间复制文件，或复制到存储桶中。
注意：在可能的情况下，请使用
HfApi.upload_file()以获得更好的性能。
查找
< source >( path: strmaxdepth: int | None = Nonewithdirs: bool = Falsedetail: bool = Falserefresh: bool = Falserevision: 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 文档。
大型仓库会按目录并行列出，以绕过 Hub
tree端点的基于游标的分页。可通过 HfFileSystem 的max_workers参数进行调整。
get_file
< source >( rpathlpath = Nonecallback = <fsspec.callbacks.NoOpCallback object at 0x7f9673955c90>outfile = None**kwargs )
将单个远程文件复制到本地。
注意：在可能的情况下，请使用
HfApi.hf_hub_download()或HfApi.download_bucket_files以获得更好的性能。
glob
< source >( path: strmaxdepth: int | None = None**kwargs ) → list[str]
通过 glob 匹配查找文件。
有关更多详细信息，请参阅 fsspec 文档。
信息
< source >( path: strrefresh: bool = Falserevision: str | None = None**kwargs ) → dict[str, Any]
获取文件或目录的信息。
有关更多详细信息，请参阅 fsspec 文档。
注意：在可能的情况下，使用
HfApi.get_paths_info()或HfApi.repo_info()以获得更好的性能（对于 buckets，使用HfApi.get_bucket_paths_info()或HfApi.bucket_info()）
检查路径是否为目录。
有关更多详细信息，请参阅 fsspec 文档。
检查路径是否为文件。
有关更多详细信息，请参阅 fsspec 文档。
ls
< source >( path: strdetail: bool = Truerefresh: bool = Falserevision: str | None = None**kwargs ) → list[Union[str, dict[str, Any]]]
列出目录的内容。
有关更多详细信息，请参阅 fsspec 文档。
注意：在可能的情况下，请使用
HfApi.list_repo_tree()以获得更好的性能。
获取文件的最后修改时间。
有关更多详细信息，请参阅 fsspec 文档。
resolve_path
< source >( path: strrevision: str | None = None ) → HfFileSystemResolvedPath
将 Hugging Face 文件系统路径解析为其各个组成部分。
rm
< source >( path: strrecursive: bool = Falsemaxdepth: int | None = Nonerevision: str | None = None**kwargs )
从存储库中删除文件。
有关更多详细信息，请参阅 fsspec 文档。
注意：在可能的情况下，请使用
HfApi.delete_file()以获得更好的性能。
获取给定路径的 HTTP URL。
walk
< source >( path: str*args**kwargs ) → Iterator[tuple[str, list[str], list[str]]]
返回给定路径下的所有文件。
有关更多详细信息，请参阅 fsspec 文档。