跳到主要内容

库

Datasets Hub 支持开源生态中的多种库。借助 huggingface_hub Python 库，可以轻松地在 Hub 上分享数据集。我们很高兴欢迎这些推动机器学习前进的开源库加入 Hub。

下表总结了已支持的库及其集成程度。

库描述从 Hub 下载推送到 Hub
ArgillaAI 工程师与领域专家协作的高质量数据工具。✅✅
Daft面向大规模、多模态数据处理的 Python 原生数据引擎。✅✅
Dask扩展 Python 与 PyData 生态的并行与分布式计算库。✅✅
Datasets🤗 Datasets 是用于访问与分享音频、计算机视觉、自然语言处理数据集的库。✅✅
Distilabel合成数据生成与 AI 反馈框架。✅✅
DuckDB内嵌式 SQL OLAP 数据库管理系统。✅✅
Embedding Atlas大规模嵌入的交互式可视化与探索工具。✅❌
fenic类 PySpark 的 DataFrame 框架，用于构建生产级 AI 与 Agent 应用。✅❌
FiftyOne用于图像、视频、3D 数据整理与可视化的库。✅✅
PandasPython 数据分析工具包。✅✅
Polars基于 OLAP 查询引擎的 DataFrame 库。✅✅
PyArrowApache Arrow 提供列式格式与高效内存分析工具。✅✅
Spark分布式环境中的实时大规模数据处理工具。✅✅
WebDataset用于编写大规模数据集 I/O 管线的库。✅❌

将数据工具与 Hub 集成​

本指南面向希望与 Hugging Face Hub 集成的数据工具与库的开发者/维护者。无论你在构建数据处理库、分析工具，还是任何需要与数据集交互的软件，本指南都将帮助你实现 Hub 集成。

指南涵盖以下内容：

  • 如何在库/工具中加载 Hub 上的数据
  • 如何在库/工具中将数据上传到 Hub

从 Hub 加载数据​

如果你维护一个数据处理库，让用户直接从 Hub 加载数据会非常方便。

通常建议依赖现有库（如 datasets、pandas、polars），除非有特殊需求。若需更精细的加载控制，可使用 huggingface_hub 库，例如只下载仓库中的某个文件子集。

更多关于从 Hub 加载数据的信息，请查看这里。

通过数据集查看器与 Parquet 文件集成​

Hub 的数据集查看器与 Parquet 转换系统为数据集提供了标准化的集成途径，无论原始格式如何。该基础设施是 Hub 与外部库之间可靠的集成层。

若数据集尚未为 Parquet，Hub 会自动将每个数据集的前 5GB 转换为 Parquet，以支持数据集查看器并提供一致的访问方式。这种标准化带来多重好处：

  • 无论原始格式如何，都能获得一致的数据访问模式
  • 内置数据集预览与探索功能，可将查看器嵌入 iframe，便于在应用中提供丰富的预览。更多嵌入信息请参阅数据集查看器嵌入文档
  • Parquet 的列式存储适合高效查询，例如可用 DuckDB 来筛选数据
  • Parquet 在机器学习与数据科学生态中支持广泛

如需了解更多关于数据集查看器 API 的细节，请参阅数据集查看器 API 文档。

向 Hub 上传数据​

本节介绍如何在你的库中实现将数据上传至 Hub 的能力，即如何实现 push_to_hub 方法。

我们将介绍三种主要上传方式：

  • 使用 datasets 库的 push_to_hub
  • 使用 pandas 推送到 Hub
  • 使用 huggingface_hub 库（hf_hub_download等接口）
  • 直接使用 API 或 Git LFS

使用 datasets 库​

最简单的做法是依赖 datasets 库提供的 push_to_hub 方法。这会自动完成：

  • 创建仓库
  • 将数据集转换为 Parquet
  • 将数据集分块
  • 上传数据

例如，如果你的合成数据生成库返回字典列表，只需这样做：

from datasets import Dataset

data = [{"prompt": "Write a cake recipe", "response": "Measure 1 cup ..."}]
ds = Dataset.from_list(data)
ds.push_to_hub("USERNAME_OR_ORG/repo_ID")

集成示例：

依赖已有库与 Hub 的集成​

Polars、Pandas、Dask、Spark、DuckDB、Daft 都能向 Hugging Face Hub 仓库写入数据。详见数据集库。

若代码中已使用这些库，增加推送至 Hub 的能力非常简单。例如，如果你的合成数据生成库可返回 Pandas DataFrame，可使用以下代码推送到 Hub：

from huggingface_hub import HfApi

# 初始化 Hub API
hf_api = HfApi(token=os.getenv("HF_TOKEN"))

# 创建仓库（若不存在）
hf_api.create_repo(repo_id="username/my-dataset", repo_type="dataset")

# 将数据转换为 DataFrame 并直接写入 Hub
df.to_parquet("hf://datasets/username/my-dataset/data.parquet")

使用 huggingface_hub Python 库​

huggingface_hub Python 库提供了更灵活的上传方式，可上传仓库中的特定文件或文件子集。这在你拥有大型数据集、不想转换为 Parquet、只想上传特定文件，或希望精细控制仓库结构时十分有用。

根据使用场景，你可以在代码中的特定位置上传文件或文件夹，例如当用户点击“push to Hub”时，将工具中的注释放入 Hub。例如：

from huggingface_hub import HfApi
api = HfApi(token=HF_TOKEN)

api.upload_folder(
    folder_path="/my-cool-library/data-folder",
    repo_id="username/my-cool-space",
    repo_type="dataset",
    commit_message="Push annotations to Hub"
    allow_patterns="*.jsonl",
)

更多上传方式请见上传指南。

在某些情况下，你可能希望在后台上传数据，例如每 10 分钟生成的合成数据。这时可使用 huggingface_hub 的 scheduled_uploads 功能。详情请参阅定时上传文档。

实际案例：

更多支持​

若你在集成过程中遇到技术问题，欢迎联系 datasets 团队：[email protected]。

最后于 更新