🤗 Datasets 是一个轻量级的库，提供 两项 主要功能：

• 针对众多公开数据集的一行式数据加载器：只需一行代码即可下载并预处理 HuggingFace 数据集中心 上提供的 种主要公开数据集（图像数据集、音频数据集、涵盖 467 种语言和方言的文本数据集等）。通过简单的命令如 squad_dataset = load_dataset("rajpurkar/squad")，即可将这些数据集准备好，直接用于机器学习模型的训练或评估（NumPy/Pandas/PyTorch/TensorFlow/JAX）。
• 高效的数据预处理：无论是公开数据集还是您本地的 CSV、JSON、文本、PNG、JPEG、WAV、MP3、Parquet、HDF5 等格式的数据集，都能进行简单、快速且可重复的数据预处理。只需使用类似 processed_dataset = dataset.map(process_example) 的命令，即可高效地准备数据集，以便检查以及用于机器学习模型的评估和训练。

🎓 文档 🔎 在中心查找数据集 🌟 在中心分享数据集

🤗 Datasets 的设计宗旨是让社区能够轻松添加和分享新的数据集。

🤗 Datasets 还具备许多其他有趣的功能：

• 适合处理大规模数据集：🤗 Datasets 自然解决了用户受 RAM 内存限制的问题，所有数据集都采用高效的零序列化开销后端（Apache Arrow）进行内存映射。
• 智能缓存：无需多次等待数据处理。
• 轻量且快速，API 设计透明且符合 Python 风格（多进程/缓存/内存映射）。
• 内置与 NumPy、PyTorch、TensorFlow 2、JAX、Pandas、Polars 等框架的互操作性。
• 原生支持音频、图像和视频数据。
• 支持流式模式，节省磁盘空间，并可立即开始遍历数据集。

🤗 Datasets 最初源自优秀的 TensorFlow Datasets 的分支，HuggingFace 团队在此向 TensorFlow Datasets 团队致以深深的感谢，感谢他们打造了这一出色的库。

安装

使用 pip

🤗 Datasets 可从 PyPI 安装，建议在虚拟环境（如 venv 或 conda）中进行安装。

pip install datasets

使用 conda

也可以通过 conda 安装 🤗 Datasets，具体命令如下：

conda install -c huggingface -c conda-forge datasets

请参考 TensorFlow 和 PyTorch 的安装页面，了解如何使用 conda 安装它们。

更多安装细节，请参阅文档中的安装页面：https://huggingface.co/docs/datasets/installation

与机器学习及数据框架一起使用时的安装

如果您计划将 🤗 Datasets 与 PyTorch（2.0+）、TensorFlow（2.6+）或 JAX（0.4+）结合使用，还需分别安装 PyTorch、TensorFlow 或 JAX。此外，🤗 Datasets 也与 PyArrow、Pandas、Polars 和 Spark 等数据框架良好集成，这些框架需单独安装。

有关如何将该库与这些框架配合使用的详细信息，请参阅文档中的快速入门页面：https://huggingface.co/docs/datasets/quickstart

使用方法

🤗 Datasets 的设计非常简单易用——其 API 以单个函数为核心，即 datasets.load_dataset(dataset_name, **kwargs)，用于实例化数据集。

该库可用于文本、图像、音频等各类数据集。以下是一个加载文本数据集的示例：

以下是一个快速示例：

from datasets import load_dataset

# 打印所有可用的数据集
from huggingface_hub import list_datasets
print([dataset.id for dataset in list_datasets(limit=20)])

# 加载一个数据集并打印训练集中的第一个样本
squad_dataset = load_dataset('rajpurkar/squad')
print(squad_dataset['train'][0])

# 处理数据集——添加一列显示上下文文本的长度
dataset_with_length = squad_dataset.map(lambda x: {"length": len(x["context"])})

# 处理数据集——对上下文文本进行分词（使用 🤗 Transformers 库中的分词器）
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained('bert-base-cased')

tokenized_dataset = squad_dataset.map(lambda x: tokenizer(x['context']), batched=True)

如果您的数据集超出磁盘容量，或者您不想等待数据下载完成，可以使用流式处理：

# 如果您希望立即使用数据集，并在遍历数据集时高效地进行流式传输
image_dataset = load_dataset('timm/imagenet-1k-wds', streaming=True)
for example in image_dataset["train"]:
    break

有关该库的更多使用详情，请参阅文档中的快速入门页面：https://huggingface.co/docs/datasets/quickstart，以及以下特定页面：

• 加载数据集：https://huggingface.co/docs/datasets/loading
• 数据集的内容：https://huggingface.co/docs/datasets/access
• 使用 🤗 Datasets 处理数据：https://huggingface.co/docs/datasets/process
  • 处理音频数据：https://huggingface.co/docs/datasets/audio_process
  • 处理图像数据：https://huggingface.co/docs/datasets/image_process
  • 处理文本数据：https://huggingface.co/docs/datasets/nlp_process
• 流式传输数据集：https://huggingface.co/docs/datasets/stream
• 等等。

向 Hub 添加新数据集

我们提供了一份非常详细的分步指南，用于将新数据集添加到 已经在 HuggingFace 数据集 Hub 上提供的数据集中。

您可以找到：

• 如何使用网页浏览器或 Python 将数据集上传到 Hub，以及
• 如何使用 Git 上传数据集。

免责声明

您可以使用 🤗 Datasets 加载基于数据集作者维护的版本化 Git 仓库的数据集。出于可重复性的考虑，我们要求用户固定所使用的仓库的 revision。

如果您是数据集的所有者，并希望更新其任何部分（描述、引用、许可证等），或者不希望您的数据集被纳入 Hugging Face Hub，请通过在数据集页面的“社区”选项卡中发起讨论或拉取请求与我们联系。感谢您对机器学习社区的贡献！

BibTeX

如果您想引用我们的 🤗 Datasets 库，可以使用我们的 论文：

@inproceedings{lhoest-etal-2021-datasets,
    title = "Datasets: A Community Library for Natural Language Processing",
    author = "Lhoest, Quentin  and
      Villanova del Moral, Albert  and
      Jernite, Yacine  and
      Thakur, Abhishek  and
      von Platen, Patrick  and
      Patil, Suraj  and
      Chaumond, Julien  and
      Drame, Mariama  and
      Plu, Julien  and
      Tunstall, Lewis  and
      Davison, Joe  and
      {\v{S}}a{\v{s}ko}, Mario  and
      Chhablani, Gunjan  and
      Malik, Bhavitvya  and
      Brandeis, Simon  and
      Le Scao, Teven  and
      Sanh, Victor  and
      Xu, Canwen  and
      Patry, Nicolas  and
      McMillan-Major, Angelina  and
      Schmid, Philipp  and
      Gugger, Sylvain  and
      Delangue, Cl{\'e}ment  and
      Matussi{\`e}re, Th{\'e}o  and
      Debut, Lysandre  and
      Bekman, Stas  and
      Cistac, Pierric  and
      Goehringer, Thibault  and
      Mustar, Victor  and
      Lagunas, Fran{\c{c}}ois  and
      Rush, Alexander  and
      Wolf, Thomas",
    booktitle = "Proceedings of the 2021 Conference on Empirical Methods in Natural Language Processing: System Demonstrations",
    month = nov,
    year = "2021",
    address = "Online and Punta Cana, Dominican Republic",
    publisher = "Association for Computational Linguistics",
    url = "https://aclanthology.org/2021.emnlp-demo.21",
    pages = "175--184",
    abstract = "随着研究人员提出新的任务、更大的模型和新颖的基准，公开可用的 NLP 数据集的数量、种类和规模迅速增长。Datasets 是一个面向当代 NLP 的社区库，旨在支持这一生态系统。Datasets 致力于标准化最终用户的接口、版本管理和文档，同时提供一个轻量级的前端，无论处理小型数据集还是互联网规模的语料库，其行为都保持一致。该库的设计采用了分布式、社区驱动的方式来添加数据集并记录使用方法。经过一年的开发，该库现已包含 650 多个独特的数据集，拥有 250 多位贡献者，并已帮助支持了多种跨数据集的创新研究项目和共享任务。该库可在 https://github.com/huggingface/datasets 上获取。",
    eprint={2109.02846},
    archivePrefix={arXiv},
    primaryClass={cs.CL},
}

如果您需要为可重复性引用 🤗 Datasets 库的特定版本，可以使用此 列表 中对应的 Zenodo DOI。

🤗 Datasets 快速上手指南

datasets 是 Hugging Face 提供的一个轻量级库，旨在让开发者能够轻松加载、预处理和共享各种公共数据集（文本、图像、音频等）。它支持内存映射技术，可高效处理超出 RAM 容量的大型数据集，并原生兼容 PyTorch、TensorFlow、JAX、Pandas 等主流框架。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：建议 Python 3.8+
• 前置依赖：
  • 推荐使用虚拟环境（如 venv 或 conda）
  • 若需与深度学习框架配合使用，请预先安装 PyTorch、TensorFlow 或 JAX
  • 可选依赖：pyarrow, pandas, polars 等用于数据操作

💡 提示：国内用户可使用清华或阿里镜像源加速安装过程。

安装步骤

方式一：使用 pip（推荐）

pip install datasets -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：使用 conda

conda install -c huggingface -c conda-forge datasets

如需配合特定机器学习框架，请另行安装对应包，例如：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

基本使用

1. 加载公开数据集

from datasets import load_dataset

# 加载 SQuAD 数据集
squad_dataset = load_dataset('rajpurkar/squad')

# 查看训练集第一条数据
print(squad_dataset['train'][0])

2. 数据预处理

# 添加新字段：上下文长度
dataset_with_length = squad_dataset.map(lambda x: {"length": len(x["context"])})

# 使用 Transformers 进行分词
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained('bert-base-cased')

tokenized_dataset = squad_dataset.map(lambda x: tokenizer(x['context']), batched=True)

3. 流式加载（适合超大数据集）

# 启用流模式，无需等待下载完成即可开始迭代
image_dataset = load_dataset('timm/imagenet-1k-wds', streaming=True)
for example in image_dataset["train"]:
    break

4. 浏览可用数据集

from huggingface_hub import list_datasets

# 打印前 20 个可用数据集名称
print([dataset.id for dataset in list_datasets(limit=20)])

---

更多详细用法请参考官方文档：

• 加载数据集
• 数据处理
• 流式读取