Hub Python 库文档

通过文件系统 API 与 Hub 交互

Hugging Face's logo
加入 Hugging Face 社区

并获得增强型文档体验

开始

通过文件系统 API 与 Hub 交互

除了 HfApi 之外,huggingface_hub 库还提供 HfFileSystem,这是一个 Python 风格的 与 fsspec 兼容 的文件接口,用于访问 Hugging Face Hub。 HfFileSystem 基于 HfApi 构建,并提供典型文件系统样式的操作,如 cpmvlsduglobget_fileput_file

用法

>>> from huggingface_hub import HfFileSystem
>>> fs = HfFileSystem()

>>> # List all files in a directory
>>> fs.ls("datasets/my-username/my-dataset-repo/data", detail=False)
['datasets/my-username/my-dataset-repo/data/train.csv', 'datasets/my-username/my-dataset-repo/data/test.csv']

>>> # List all ".csv" files in a repo
>>> fs.glob("datasets/my-username/my-dataset-repo/**.csv")
['datasets/my-username/my-dataset-repo/data/train.csv', 'datasets/my-username/my-dataset-repo/data/test.csv']

>>> # Read a remote file
>>> with fs.open("datasets/my-username/my-dataset-repo/data/train.csv", "r") as f:
...     train_data = f.readlines()

>>> # Read the content of a remote file as a string
>>> train_data = fs.read_text("datasets/my-username/my-dataset-repo/data/train.csv", revision="dev")

>>> # Write a remote file
>>> with fs.open("datasets/my-username/my-dataset-repo/data/validation.csv", "w") as f:
...     f.write("text,label")
...     f.write("Fantastic movie!,good")

可选的 revision 参数可以传递以从特定提交运行操作,例如分支、标签名称或提交哈希值。

与 Python 的内置 open 不同,fsspecopen 默认使用二进制模式,"rb"。这意味着您必须将模式明确设置为 "r" 以用于文本模式的读取和 "w" 以用于写入。目前不支持追加到文件(模式 "a""ab")。

集成

可以将 HfFileSystem 与任何与 fsspec 集成的库一起使用,前提是 URL 遵循该方案

hf://[<repo_type_prefix>]<repo_id>[@<revision>]/<path/in/repo>

对于数据集,repo_type_prefixdatasets/,对于空间,repo_type_prefixspaces/,模型在 URL 中不需要前缀。

下面列出了一些有趣的集成,其中 HfFileSystem 简化了与 Hub 的交互。

  • 从 Hub 仓库中读取/写入 Pandas DataFrame

    >>> import pandas as pd
    
    >>> # Read a remote CSV file into a dataframe
    >>> df = pd.read_csv("hf://datasets/my-username/my-dataset-repo/train.csv")
    
    >>> # Write a dataframe to a remote CSV file
    >>> df.to_csv("hf://datasets/my-username/my-dataset-repo/test.csv")

相同的工作流程也适用于 DaskPolars 数据框。

  • 使用 DuckDB 查询(远程)Hub 文件

    >>> from huggingface_hub import HfFileSystem
    >>> import duckdb
    
    >>> fs = HfFileSystem()
    >>> duckdb.register_filesystem(fs)
    >>> # Query a remote file and get the result back as a dataframe
    >>> fs_query_file = "hf://datasets/my-username/my-dataset-repo/data_dir/data.parquet"
    >>> df = duckdb.query(f"SELECT * FROM '{fs_query_file}' LIMIT 10").df()
  • 使用 Hub 作为数组存储与 Zarr 一起使用

    >>> import numpy as np
    >>> import zarr
    
    >>> embeddings = np.random.randn(50000, 1000).astype("float32")
    
    >>> # Write an array to a repo
    >>> with zarr.open_group("hf://my-username/my-model-repo/array-store", mode="w") as root:
    ...    foo = root.create_group("embeddings")
    ...    foobar = foo.zeros('experiment_0', shape=(50000, 1000), chunks=(10000, 1000), dtype='f4')
    ...    foobar[:] = embeddings
    
    >>> # Read an array from a repo
    >>> with zarr.open_group("hf://my-username/my-model-repo/array-store", mode="r") as root:
    ...    first_row = root["embeddings/experiment_0"][0]

身份验证

在许多情况下,您必须使用 Hugging Face 帐户登录才能与 Hub 交互。请参考文档的 身份验证 部分,了解有关 Hub 上身份验证方法的更多信息。

您还可以通过将您的 token 作为参数传递给 HfFileSystem 来以编程方式登录。

>>> from huggingface_hub import HfFileSystem
>>> fs = HfFileSystem(token=token)

如果您以这种方式登录,请注意不要在共享源代码时意外泄露令牌!

< > 更新 在 GitHub 上