🤗 Datasets 是一个轻量级库，提供**两项**主要功能：
- **针对许多公开数据集的单行 dataloader**：通过单行代码即可下载和预处理  上的主要公开数据集（包括图像数据集、音频数据集、涵盖 467 种语言和方言的文本数据集、3D 医学图像、视频数据集、agent traces 等），这些数据集均提供在 [HuggingFace Datasets Hub](https://huggingface.co/datasets) 上。使用如 `squad_dataset = load_dataset("rajpurkar/squad")` 的简单命令，即可准备好这些数据集，供用于训练/评估 ML 模型（Numpy/Pandas/PyTorch/TensorFlow/JAX/Polars）的 dataloader 使用，
- **高效的数据预处理**：针对公开数据集以及您自己的本地数据集（CSV、JSON、JSONL、Parquet、HDF5、XML、文本、PNG、JPEG、WAV、MP3、PDF、NIfTI 等格式），提供简单、快速且可复现的数据预处理。使用如 `processed_dataset = dataset.map(process_example)` 的简单命令，即可高效准备数据集，以供检查以及进行 ML 模型评估和训练。
[🎓 **文档**](https://huggingface.co/docs/datasets/) [🔎 **在 Hub 上查找数据集**](https://huggingface.co/datasets) [🌟 **在 Hub 上分享数据集**](https://huggingface.co/docs/datasets/share)
# 🚀 核心功能
🤗 Datasets 旨在让社区能够轻松添加和共享新数据集，并为数据操作提供强大的功能：
| 功能 | 描述 |
|---------|-------------|
| 📦 **单行加载数据集** | 使用 `load_dataset()` 从 [Hugging Face Hub](https://huggingface.co/datasets) 或本地文件加载适配 AI 的数据集 |
| 🔍 **多种格式** | 原生支持 CSV、JSON、JSONL、Parquet、Arrow、XML、文本、Webdataset 等 |
| 🖼️ **多模态数据** | 内置支持文本、音频、图像、视频、PDF 和 NIfTI（3D 医疗）数据 |
| 🚀 **流式模式** | 无需下载即可对数据集进行流式传输——使用 `streaming=True` 即时迭代数据（在 Xet 后端加持下，速度提升高达 **100 倍**） |
| 💾 **HF 存储桶** | 直接对 [Hugging Face 存储桶](https://huggingface.co/docs/hub/storage-buckets) 进行读写，适用于可变的、大规模的原始数据 |
| 🧠 **AI Agent Traces** | 从 Hub 加载并处理 AI agent traces（prompts、工具调用、响应） |
| ⚡ **Apache Arrow 后端** | 零拷贝内存映射存储——数据集自然使您免受 RAM 限制 |
| 🔄 **智能缓存** | 无需等待数据被处理两次——自动重用缓存结果 |
| 📊 **多框架互操作性** | 原生支持与 NumPy、Pandas、Polars、Arrow、PyTorch、TensorFlow、JAX 和 Spark 的相互转换 |
| 🏎️ **多进程处理** | 使用 `map(num_proc=N)` 进行快速并行数据处理 |
| 🔎 **搜索与索引** | 内置 FAISS 和 Elasticsearch 索引支持，用于相似性搜索 |
| 📦 **JSON 类型** | 使用 `Json()` 特征类型提供灵活的 JSON/结构化数据支持 |
# 安装
## 使用 pip
🤗 Datasets 可以从 PyPi 安装，并且应该安装在虚拟环境（例如 venv 或 conda）中：
```
pip install datasets
```
如需获取最新的开发版本：
```
pip install "datasets @ git+https://github.com/huggingface/datasets.git"
```
## 使用 conda
```
conda install -c huggingface -c conda-forge datasets
```
## 可选依赖
🤗 Datasets 通过扩展功能支持各种可选特性：
```
# 对于音频 (torchcodec)
pip install datasets[audio]
# 对于图像/视频 (Pillow, torchcodec)
pip install datasets[vision]
# 对于 PDF/NIfTI (pdfplumber, nibabel)
pip install datasets[pdfs,nibabel]
# 对于 PyTorch/TensorFlow/JAX 集成
pip install datasets[torch,tensorflow,jax]
```
有关安装的更多详细信息，请查看[安装页面](https://huggingface.co/docs/datasets/installation)。
# 快速开始
🤗 Datasets 的设计宗旨是极易使用——其 API 以单个函数 `datasets.load_dataset(dataset_name, **kwargs)` 为核心，用于实例化数据集。
以下是一个简单的示例：
```
from datasets import load_dataset
# 加载一个 dataset 并打印训练集中的第一个样本
squad_dataset = load_dataset('rajpurkar/squad')
print(squad_dataset['train'][0])
# 处理 dataset - 添加一个包含 context 文本长度的列
dataset_with_length = squad_dataset.map(lambda x: {"length": len(x["context"])})
# 对 context 文本进行 tokenize（使用来自 🤗 Transformers 库的 tokenizer）
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained('bert-base-cased')
tokenized_dataset = squad_dataset.map(lambda x: tokenizer(x['context']), batched=True)
# 使用 chat template 对 chat 对话进行 tokenize（使用支持 chat template 的模型）
# 这对于 fine-tune instruction/chat 模型很有用
# 加载一个流行的 chat dataset（ultrachat_200k 包含约 20 万条 AI 助手对话）
chat_dataset = load_dataset('HuggingFaceH4/ultrachat_200k', split='train_sft')
chat_tokenizer = AutoTokenizer.from_pretrained('Qwen/Qwen2.5-7B-Instruct')
def tokenize_chat(examples):
# Apply the chat template and tokenize in one step
return chat_tokenizer.apply_chat_template(examples["messages"])
tokenized_chat_dataset = chat_dataset.map(tokenize_chat, batched=True)
```
## 流式模式
如果您的数据集大于您的磁盘空间，或者您不想等待下载数据，您可以使用流式传输：
```
# 流式传输 dataset 而无需下载任何内容
image_dataset = load_dataset('timm/imagenet-1k-wds', streaming=True)
for example in image_dataset["train"]:
print(example["image"])
break
```
## 多模态数据
🤗 Datasets 开箱即用地支持多种数据类型：
```
# 音频 dataset
dataset = load_dataset("openslr/librispeech_asr", "clean")
# 图像 dataset
dataset = load_dataset("ILSVRC/imagenet-1k")
# 视频 dataset
dataset = load_dataset("Shofo/shofo-tiktok-general-small")
# PDF 文档
dataset = load_dataset("pixparse/pdfa-eng-wds")
# NIfTI（3D 医学影像）
dataset = load_dataset("dartbrains/localizer", "betas")
```
## 从本地文件
```
# 从本地 CSV 加载
dataset = load_dataset('csv', data_files='my_data.csv')
# 从本地 Parquet 加载
dataset = load_dataset('parquet', data_files='data/*.parquet')
# 从本地目录加载（自动检测格式）
dataset = load_dataset('./path/to/data')
```
## 从 Python 对象
```
from datasets import Dataset
# 从 dictionary 加载
dataset = Dataset.from_dict({"text": ["Hello world", "How are you?"]})
# 从 list 加载
dataset = Dataset.from_list([{"text": "Hello world"}, {"text": "How are you?"}])
# 从 Pandas 加载
import pandas as pd
df = pd.DataFrame({"col1": [1, 2, 3], "col2": ["a", "b", "c"]})
dataset = Dataset.from_pandas(df)
# 从 generator 加载
def gen():
for i in range(10):
yield {"value": i}
dataset = Dataset.from_generator(gen)
```
有关使用该库的更多详细信息，请查看[快速入门指南](https://huggingface.co/docs/datasets/quickstart) 以及以下特定页面：
- [加载数据集](https://huggingface.co/docs/datasets/loading)
- [Dataset 中包含什么](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)
- [处理 PDF 数据](https://huggingface.co/docs/datasets/pdf_process)
- [处理视频数据](https://huggingface.co/docs/datasets/video_process)
- [流式传输数据集](https://huggingface.co/docs/datasets/stream)
# 核心类
该库提供了两个主要的 dataset 类：
| 类 | 描述 |
|-------|-------------|
| `Dataset` | 由 Apache Arrow 支持的内存映射数据集。支持索引、切片、随机访问和缓存。 |
| `IterableDataset` | 用于大规模/核外处理的惰性、可流式传输数据集。支持流式传输和无限迭代。 |
对于多划分数据集（例如 train/test/val），两者都封装在 `DatasetDict` / `IterableDatasetDict` 中。
# 向 Hub 添加新数据集
我们提供了一份非常详细的分步指南，指导您如何将新数据集添加到 [HuggingFace Datasets Hub](https://huggingface.co/datasets) 上已经提供的  数据集中。
您可以找到：
- [如何使用您的 Web 浏览器或 Python 将数据集上传到 Hub](https://huggingface.co/docs/datasets/upload_dataset) 以及
- [如何使用 Git 上传数据集](https://huggingface.co/docs/datasets/share)。
# 免责声明
您可以使用 🤗 Datasets 加载基于由数据集作者维护的版本化 git 仓库的数据集。出于可复现性的考虑，我们要求用户固定（pin）他们所使用仓库的 `revision`。
如果您是数据集的所有者，并希望更新其任何部分（描述、引用、许可证等），或者不希望您的数据集被包含在 Hugging Face Hub 中，请通过在数据集页面的“社区”选项卡中发起讨论或提交 pull request 与我们联系。感谢您对 ML 社区的贡献！
# BibTeX
如果您想引用我们的 🤗 Datasets 库，可以使用我们的[论文](https://huggingface.co/papers/2109.02846)：
```
@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 = "The scale, variety, and quantity of publicly-available NLP datasets has grown rapidly as researchers propose new tasks, larger models, and novel benchmarks. Datasets is a community library for contemporary NLP designed to support this ecosystem. Datasets aims to standardize end-user interfaces, versioning, and documentation, while providing a lightweight front-end that behaves similarly for small datasets as for internet-scale corpora. The design of the library incorporates a distributed, community-driven approach to adding datasets and documenting usage. After a year of development, the library now includes more than 650 unique datasets, has more than 250 contributors, and has helped support a variety of novel cross-dataset research projects and shared tasks. The library is available at https://github.com/huggingface/datasets.",
eprint={2109.02846},
archivePrefix={arXiv},
primaryClass={cs.CL},
}
```
如果出于可复现性的考虑，您需要引用 🤗 Datasets 库的特定版本，可以使用此[列表](https://zenodo.org/search?q=conceptrecid:%224817768%22&sort=-version&all_versions=True) 中相应版本的 Zenodo DOI。