Hub documentation

库

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

库

Datasets Hub 支持开源生态系统中的多个库。借助 huggingface_hub Python 库，您可以轻松地在 Hub 上共享您的数据集。我们很高兴在 Hub 上欢迎一系列推动机器学习发展的开源库。

库表

下表总结了受支持的库及其集成级别。

库	描述	从 Hub 下载	从 Hub 流式传输	推送到 Hub	流式传输到 Hub	优化的 Parquet 文件
Argilla	面向重视高质量数据的 AI 工程师和领域专家的协作工具。	✅	❌	✅	❌	❌
Daft	用于大规模多模态数据处理的 Python 原生接口数据引擎。	✅	✅	✅	✅	✅
Dask	一个并行和分布式计算库，用于扩展现有的 Python 和 PyData 生态系统。	✅	✅	✅	✅	✅*
数据设计师	用于使用 LLM 生成合成数据集的 NVIDIA NeMo 框架。	✅	❌	✅	❌	❌
数据集	🤗 Datasets 是一个用于访问和共享音频、计算机视觉和自然语言处理（NLP）数据集的库。	✅	✅	✅	✅	✅
Distilabel	用于合成数据生成和 AI 反馈的框架。	✅	❌	✅	❌	❌
DuckDB	进程内 SQL OLAP 数据库管理系统。	✅	✅	❌	❌	❌
嵌入图谱	用于大型嵌入的交互式可视化和探索工具。	✅	✅	❌	❌	❌
Fenic	受 PySpark 启发的 DataFrame 框架，用于构建生产级 AI 和智能体应用。	✅	✅	❌	❌	❌
FiftyOne	FiftyOne 是一个用于图像、视频和 3D 数据整理与可视化的库。	✅	✅	✅	❌	❌
Lance	面向多模态 AI 的开放湖仓格式。	✅	✅	❌	❌	❌
Pandas	Python 数据分析工具包。	✅	❌	✅	❌	✅*
Polars	基于 OLAP 查询引擎的 DataFrame 库。	✅	✅	✅	❌	❌
PyArrow	Apache Arrow 是一种列式格式，也是用于快速数据交换和内存分析的工具箱。	✅	✅	✅	❌	✅*
Spark	在分布式环境中进行实时、大规模数据处理的工具。	✅	✅	✅	✅	✅
WebDataset	用于编写大型数据集 I/O 管道的库。	✅	✅	❌	❌	❌

* 需要传递额外参数以写入优化后的 Parquet 文件

数据处理库

流式

数据集流式处理（Dataset streaming）允许逐步迭代 Hugging Face 上的数据集，而无需将其完整下载。由于数据始终不写入磁盘，因此可节省本地磁盘空间；由于每次仅使用数据集的一小部分，因此可节省内存；由于无需在 CPU 或 GPU 工作负载开始前下载数据，因此可节省时间。

除了从 Hugging Face 流式读取之外，许多库还支持将数据流式写回 Hugging Face。因此，它们可以运行端到端的流式处理流水线：从数据源流式读取，并逐步写入 Hugging Face，通常将下载、上传和处理步骤重叠执行。

有关流式处理的更多详细信息，请参阅支持流式处理的库的文档（见上表），或者，如果您想自行从 Hugging Face 流式加载数据集，请参阅 streaming datasets 文档。

优化的 Parquet 文件

Hugging Face 上的 Parquet 文件经过优化，可提升存储效率、加速下载和上传，并支持高效的数据集流式处理和编辑。

优化后的 Parquet 文件是具有以下附加功能的 Parquet 文件：

Parquet 内容定义分块针对 Hugging Face 的存储后端 Xet 优化了 Parquet。它通过基于分块的重复数据删除加速了上传和下载，并支持高效的文件编辑
Page index 在流式传输时加速过滤，并支持高效的随机访问，例如在 Dataset Viewer 中。

某些库需要额外的参数来写入优化后的 Parquet 文件，例如 Pandas 和 PyArrow：

use_content_defined_chunking=True 以启用 Parquet Content Defined Chunking，用于去重和编辑
write_page_index=True 以在 Parquet 元数据中包含页面索引，用于流式处理和随机访问

训练库

与 Hub 数据集集成、用于模型训练的库。下表展示了它们的流式处理能力——即无需先下载数据集即可进行训练的能力。

库	描述	从 Hub 流式传输
Axolotl	低代码 LLM 微调框架	✅
LlamaFactory	统一微调 100 多种 LLM	✅
Sentence Transformers	文本嵌入与语义相似度	✅
Transformers	🤗 Transformers Trainer 用于微调模型	✅
TRL	使用强化学习训练 LLM（SFT、DPO、GRPO）	⚠️*
Unsloth	快速 LLM 微调（速度提升 2 倍，内存减少 70%）	✅

* SFTTrainer 和 DPOTrainer 支持流式处理；GRPOTrainer 尚不支持流式输入

从 Hub 流式传输

流式处理允许在无需预先下载的情况下对大规模数据集进行训练。这在以下情况下非常有用：

您的数据集太大，无法存储在磁盘上
您希望立即开始训练
您正在使用 HF Jobs，其同置计算可提供更快的流式传输

近期的改进使流式处理效率最高提升了 100 倍，具体表现为更快的启动速度、预取机制以及对大量工作节点的更优扩展能力。

注意：流式处理要求训练参数中包含 max_steps，因为数据集长度未知，并且使用基于缓冲区的洗牌。有关更多详细信息，请参阅流式数据集。

记录到 Hub

一些工具可以在训练期间将训练数据流式传输回 Hub：

Trackio：将训练指标实时流式传输到 Hub 数据集

将数据库和工具与 Hub 集成

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

本指南涵盖：

从 Hub 将数据加载到库/工具中的可能方法
从您的库/工具上传数据到 Hub 的可行方法

从 Hub 加载数据

如果您有一个用于处理数据的库，那么让用户能够从 Hub 加载数据会很有帮助。

通常，我们建议依赖 datasets、pandas 或 polars 等现有库来完成此操作，除非你有特定理由需要自行实现。如果你需要对加载过程进行更精细的控制，可以使用 huggingface_hub 库，例如，它允许你从仓库中下载特定的文件子集。

您可以在此处找到有关从 Hub 加载数据的更多信息。

通过数据集查看器和 Parquet 文件进行集成

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

如果数据集尚未采用 Parquet 格式，Hub 会自动将每个数据集的前 5GB 转换为 Parquet 格式，以支持数据集查看器并提供一致的访问模式。这种标准化为库集成带来了多项优势：

无论原始格式如何，数据访问模式保持一致
通过 Hub 的数据集查看器内置数据集预览和探索功能。数据集查看器还可以以 iframe 的形式嵌入到您的应用程序中，从而轻松提供丰富的数据集预览。有关嵌入查看器的更多信息，请参阅数据集查看器嵌入文档。
专为查询优化的高效列式存储。例如，您可以使用 DuckDB 等工具来查询或筛选特定的数据子集。
Parquet 在机器学习和数据科学生态系统中得到了广泛支持。

有关使用 Dataset Viewer API 的更多详细信息，请参阅 Dataset Viewer API 文档

将数据上传到 Hub

本节介绍了在您的库中添加向 Hub 上传数据功能的可能方法，即如何实现 push_to_hub 方法。

本指南将介绍向 Hub 上传数据的三种主要方式：

使用 datasets 库和 push_to_hub 方法
使用 pandas 写入 Hub
使用 huggingface_hub 库和 upload_folder 方法

使用 datasets 库

将数据推送到 Hub 的最直接方法是使用 datasets 库中现有的 push_to_hub 方法。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")

此类集成的示例：

Distilabel

依赖现有库与 Hub 的集成

Polars、Pandas、Dask、Spark、DuckDB 和 Daft 都可以写入 Hugging Face Hub 仓库。有关更多详细信息，请参阅上方的库表格。

如果您已经在代码中使用了这些库之一，那么添加推送到 Hub 的功能非常简单。例如，如果您有一个可以返回 Pandas DataFrame 的合成数据生成库，以下是您需要编写以推送到 Hub 的代码：

from huggingface_hub import HfApi

# Initialize the Hub API
hf_api = HfApi()

# Create a repository (if it doesn't exist)
hf_api.create_repo(repo_id="username/my-dataset", repo_type="dataset", exist_ok=True)

# Convert your data to a DataFrame and save directly to the Hub
df.to_parquet("hf://datasets/username/my-dataset/data.parquet")

使用 huggingface_hub Python 库

huggingface_hub Python 库提供了一种更灵活的方式将数据上传到 Hub。该库允许你将特定文件或文件子集上传到仓库。如果你有一个大型数据集，不想将其转换为 Parquet 格式，或者想上传特定的文件子集，又或者希望更精细地控制仓库结构，那么这种方式会非常有用。

根据您的使用场景，您可以在代码的特定位置上传文件或文件夹，例如在用户点击“推送到 Hub”时，将工具的标注导出到 Hub。例如，

from huggingface_hub import HfApi
api = HfApi()

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

您可以在此处找到有关将数据上传到 Hub 的更多方式的信息。

或者，在某些情况下，您可能希望在后台上传数据，例如每 10 分钟生成一次合成数据。在这种情况下，您可以使用 huggingface_hub 库中的 CommitScheduler 类。有关更多详细信息，请参阅计划上传文档。

您可以在

fastdata 库
这个 magpie 演示空间

Hub

库

库表