# 库 Datasets Hub 支持开源生态系统中的多个库。得益于 [huggingface_hub Python 库](/docs/huggingface_hub)，在 Hub 上共享数据集变得轻而易举。我们很高兴欢迎一批推动机器学习发展的开源库加入 Hub。 ## 库表 下表总结了受支持的库及其集成级别。 | 库 | 描述 | 从 Hub 下载 | 从 Hub 流式传输 | 推送到 Hub | 流式传输到 Hub | 优化的 Parquet 文件 | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------- | --------------- | ----------- | ------------- | ----------------------- | | [Daft](./datasets-daft) | 用于大规模多模态数据处理的 Python 原生接口数据引擎。 | ✅ | ✅ | ✅ | ✅ | ✅ | | [Dask](./datasets-dask) | 一个并行和分布式计算库，用于扩展现有的 Python 和 PyData 生态系统。 | ✅ | ✅ | ✅ | ✅ | ✅* | | [数据设计师](./datasets-data-designer) | 用于使用 LLM 生成合成数据集的 NVIDIA NeMo 框架。 | ✅ | ❌ | ✅ | ❌ | ❌ | | [数据集](./datasets-usage) | 🤗 Datasets 是一个用于访问和共享音频、计算机视觉和自然语言处理（NLP）数据集的库。 | ✅ | ✅ | ✅ | ✅ | ✅ | | [DuckDB](./datasets-duckdb) | 进程内 SQL OLAP 数据库管理系统。 | ✅ | ✅ | ✅ | ✅ | ❌ | | [Lance](./datasets-lance) | 面向多模态 AI 的开放湖仓格式。 | ✅ | ✅ | ❌ | ❌ | ❌ | | [Pandas](./datasets-pandas) | Python 数据分析工具包。 | ✅ | ❌ | ✅ | ❌ | ✅* | | [Polars](./datasets-polars) | 基于 OLAP 查询引擎的 DataFrame 库。 | ✅ | ✅ | ✅ | ❌ | ❌ | | [PyArrow](./datasets-pyarrow) | Apache Arrow 是一种列式格式，也是用于快速数据交换和内存分析的工具箱。 | ✅ | ✅ | ✅ | ✅ | ✅* | | [Spark](./datasets-spark) | 在分布式环境中进行实时、大规模数据处理的工具。 | ✅ | ✅ | ✅ | ✅ | ✅ | | [WebDataset](./datasets-webdataset) | 用于编写大型数据集 I/O 管道的库。 | ✅ | ✅ | ❌ | ❌ | ❌ | _ * 需要传递额外参数以写入优化后的 Parquet 文件_ 其他库提供了用于数据集整理的集成：[Embedding Atlas](./datasets-embedding-atlas)（嵌入可视化）、[Fenic](./datasets-fenic)（语义处理）、[FiftyOne](./datasets-fiftyone)（图像可视化与整理）。 ## 数据处理库 ### 流式 数据集流式处理允许逐步迭代 Hugging Face 上的数据集，而无需将其完整下载。由于数据不会写入磁盘，因此可以节省本地磁盘空间。由于每次仅使用数据集的一小部分，因此可以节省内存。此外，由于无需在 CPU 或 GPU 工作负载之前下载数据，因此可以节省时间。 除了从 Hugging Face 进行 *流式读取* 之外，许多库还支持将数据 *流式写回* Hugging Face。因此，它们可以运行端到端的流式处理流水线：从数据源流式读取，并逐步写入 Hugging Face，通常还会将下载、上传和处理步骤重叠执行。 有关流式处理的更多详细信息，请参阅支持流式处理的库的文档（见上表），或者，如果您想自行从 Hugging Face 流式加载数据集，请参阅 [streaming datasets](./datasets-streaming) 文档。 ### 优化的 Parquet 文件 Hugging Face 上的 Parquet 文件经过优化，可提升存储效率、加速下载和上传，并支持高效的数据集流式处理和编辑。 优化后的 Parquet 文件是具有以下附加功能的 Parquet 文件： * [Parquet 内容定义分块](https://huggingface.co/blog/parquet-cdc)针对 Hugging Face 的存储后端 [Xet](https://huggingface.co/docs/hub/en/xet/index) 优化了 Parquet。它通过基于分块的重复数据删除加速了上传和下载，并支持高效的文件编辑 * Page index 在流式传输时加速过滤，并支持高效的随机访问，例如在 [Dataset Viewer](https://huggingface.co/docs/dataset-viewer) 中。 某些库需要额外的参数来写入优化后的 Parquet 文件，例如 `Pandas` 和 `PyArrow`： * `use_content_defined_chunking=True` 以启用 Parquet Content Defined Chunking，用于[去重](https://huggingface.co/blog/parquet-cdc)和[编辑](./datasets-editing) * `write_page_index=True` 以在 Parquet 元数据中包含页面索引，用于[流式处理和随机访问](./datasets-streaming) ## 训练库 与 Hub 数据集集成、用于模型训练的库。下表展示了它们的流式处理能力——即无需先下载数据集即可进行训练的能力。 | 库 | 描述 | 从 Hub 流式传输 | | ------- | ----------- | --------------- | | [Axolotl](https://docs.axolotl.ai/docs/streaming.html) | 低代码 LLM 微调框架 | ✅ | | [LlamaFactory](https://github.com/hiyouga/LLaMA-Factory) | 统一微调 100 多种 LLM | ✅ | | [Sentence Transformers](https://sbert.net/docs/sentence_transformer/training_overview.html) | 文本嵌入与语义相似度 | ✅ | | [Transformers](https://huggingface.co/docs/transformers/trainer) | 🤗 Transformers Trainer 用于微调模型 | ✅ | | [TRL](https://huggingface.co/docs/trl) | 使用强化学习训练 LLM（SFT、DPO、GRPO） | ✅ | | [Unsloth](https://docs.unsloth.ai) | 快速 LLM 微调（速度提升 2 倍，内存减少 70%） | ✅ | | [LeRobot](https://huggingface.co/docs/lerobot/main/en/training_dataset_streaming) | 训练机器人策略 | ✅ | ### 从 Hub 流式传输 流式处理允许在无需预先下载的情况下对大规模数据集进行训练。这在以下情况下非常有用： - 您的数据集太大，无法存储在磁盘上 - 您希望立即开始训练 - 您正在使用 [HF Jobs](https://huggingface.co/docs/hub/jobs)，其同置计算可提供更快的流式传输 近期的改进使流式处理[效率最高提升了 100 倍](https://huggingface.co/blog/streaming-datasets)，具体表现为更快的启动速度、预取机制以及对大量工作节点的更优扩展能力。 **注意：**流式处理要求训练参数中包含 `max_steps`，因为数据集长度未知，并且使用基于缓冲区的洗牌。有关更多详细信息，请参阅 [流式数据集](./datasets-streaming)。 ### 记录到 Hub 一些工具可以在训练期间将训练数据流式传输回 Hub： - **[Trackio](https://github.com/gradio-app/trackio)**：将训练指标实时流式传输到 Hub 数据集 ## 将数据库和工具与 Hub 集成 本指南面向希望与 Hugging Face Hub 集成的数据库和工具的开发人员及维护者。无论您正在构建数据处理库、分析工具，还是任何需要与数据集交互的软件，本文档都将帮助您实现 Hub 集成。 本指南涵盖： - 从 Hub 将数据加载到库/工具中的可能方法 - 从您的库/工具上传数据到 Hub 的可行方法 ### 从 Hub 加载数据 如果您有一个用于处理数据的库，那么让用户能够从 Hub 加载数据会很有帮助。 通常，我们建议依赖 `datasets`、`pandas` 或 `polars` 等现有库来完成此操作，除非你有特定理由需要自行实现。如果你需要对加载过程进行更精细的控制，可以使用 `huggingface_hub` 库，例如，它允许你从仓库中下载特定的文件子集。 您可以在[此处](https://huggingface.co/docs/hub/datasets-downloading)找到有关从 Hub 加载数据的更多信息。 #### 通过数据集查看器和 Parquet 文件进行集成 Hub 的数据集查看器和 Parquet 转换系统提供了一种标准化的方式来集成数据集，无论其原始格式如何。该基础设施是 Hub 与外部库之间可靠的集成层。 如果数据集尚未采用 Parquet 格式，Hub 会自动将每个数据集的前 5GB 转换为 Parquet 格式，以支持数据集查看器并提供一致的访问模式。这种标准化为库集成带来了多项优势： - 无论原始格式如何，数据访问模式保持一致 - 通过 Hub 的数据集查看器内置数据集预览和探索功能。数据集查看器还可以以 iframe 的形式嵌入到您的应用程序中，从而轻松提供丰富的数据集预览。有关嵌入查看器的更多信息，请参阅 [数据集查看器嵌入文档](https://huggingface.co/docs/hub/en/datasets-viewer-embed)。 - 专为查询优化的高效列式存储。例如，您可以使用 [DuckDB](https://duckdb.org/) 等工具来查询或筛选特定的数据子集。 - Parquet 在机器学习和数据科学生态系统中得到了广泛支持。 有关使用 Dataset Viewer API 的更多详细信息，请参阅 [Dataset Viewer API 文档](https://huggingface.co/docs/dataset-viewer/index) ### 将数据上传到 Hub 本节介绍了在您的库中添加向 Hub 上传数据功能的可能方法，即如何实现 `push_to_hub` 方法。 本指南将介绍向 Hub 上传数据的三种主要方式： - 使用 `datasets` 库和 `push_to_hub` 方法 - 使用 `pandas` 写入 Hub - 使用 `huggingface_hub` 库和 `upload_folder` 方法 #### 使用 `datasets` 库 将数据推送到 Hub 的最直接方法是使用 `datasets` 库中现有的 [`push_to_hub`](https://huggingface.co/docs/datasets/main/en/package_reference/main_classes#datasets.Dataset.push_to_hub) 方法。`push_to_hub` 方法会自动处理以下事项： - 仓库的创建 - 将数据集转换为 Parquet - 将数据集分块为合适的部分 - 上传数据 例如，如果你有一个合成数据生成库，它返回一个字典列表，你可以简单地执行以下操作： ```python 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](https://github.com/argilla-io/distilabel/blob/8ad48387dfa4d7bd5639065661f1975dcb44c16a/src/distilabel/distiset.py#L77) #### 依赖现有库与 Hub 的集成 Polars、Pandas、Dask、Spark、DuckDB 和 Daft 都可以写入 Hugging Face Hub 仓库。有关更多详细信息，请参阅上方的 [库表格](#libraries-table)。 如果您已经在代码中使用了这些库之一，那么添加推送到 Hub 的功能非常简单。例如，如果您有一个可以返回 Pandas DataFrame 的合成数据生成库，以下是您需要编写以推送到 Hub 的代码： ```python 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。例如， ```python 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", ) ``` 您可以在[此处](https://huggingface.co/docs/huggingface_hub/main/en/guides/upload)找到有关将数据上传到 Hub 的更多方式的信息。 或者，在某些情况下，您可能希望在后台上传数据，例如每 10 分钟生成一次合成数据。在这种情况下，您可以使用 `huggingface_hub` 库中的 `CommitScheduler` 类。有关更多详细信息，请参阅 [计划上传文档](https://huggingface.co/docs/huggingface_hub/main/en/guides/upload#scheduled-uploads)。 您可以在 - [fastdata](https://github.com/AnswerDotAI/fastdata/blob/main/nbs/00_core.ipynb) 库 - 这个 [magpie](https://huggingface.co/spaces/davanstrien/magpie/blob/fc79672c740b8d3d098378dca37c0f191c208de0/app.py#L67) 演示空间 ## 更多支持 如需就集成方面的技术问题寻求帮助，请随时通过 datasets@huggingface.co 联系 datasets 团队。