英文原文正文为项目原始 README（英文），本站后续会翻译为中文，当前仅剔除图片与无关章节并统一排版。

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

• 为多种公共数据集提供一行加载器：一行代码即可下载并预处理主要公共数据集（图像数据集、音频数据集、467 种语言和方言的文本数据集、3D 医疗图像、视频数据集、代理跟踪等），这些数据集可在 HuggingFace Datasets Hub 获取。使用简单命令如 squad_dataset = load_dataset("rajpurkar/squad")，即可将这些数据集准备好用于数据加载器，在机器学习模型中进行训练/评估（支持 Numpy/Pandas/PyTorch/TensorFlow/JAX/Polars）。
• 高效的数据预处理：对公共数据集以及您自己的本地数据集（CSV、JSON、JSONL、Parquet、HDF5、XML、文本、PNG、JPEG、WAV、MP3、PDF、NIfTI 等）进行简单、快速且可复现的数据预处理。使用简单命令如 processed_dataset = dataset.map(process_example)，即可高效地准备数据集，以便检查和进行机器学习模型的评估与训练。

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

🚀 主要特点

🤗 Datasets旨在让社区轻松添加和共享新数据集，并提供强大的数据操作功能：

安装

使用 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 通过额外功能支持各种可选特性：

# For audio (torchcodec)
pip install datasets[audio]

# For image/video (Pillow, torchcodec)
pip install datasets[vision]

# For PDFs/NIfTI (pdfplumber, nibabel)
pip install datasets[pdfs,nibabel]

# For PyTorch/TensorFlow/JAX integration
pip install datasets[torch,tensorflow,jax]

有关安装的更多详细信息，请查看安装页面。

快速开始

🤗 Datasets 的设计目的是非常易于使用——API 以一个函数为中心，即 datasets.load_dataset(dataset_name, **kwargs)，用于实例化数据集。

下面是一个快速示例：

from datasets import load_dataset

# Load a dataset and print the first example in the training set
squad_dataset = load_dataset('rajpurkar/squad')
print(squad_dataset['train'][0])

# Process the dataset - add a column with the length of the context texts
dataset_with_length = squad_dataset.map(lambda x: {"length": len(x["context"])})

# Tokenize the context texts (using a tokenizer from the 🤗 Transformers library)
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained('bert-base-cased')

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

# Tokenize chat conversations with a chat template (using a model that supports chat templates)
# This is useful for fine-tuning instruction/chat models

# Load a popular chat dataset (ultrachat_200k contains ~200k AI assistant conversations)
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)

流模式

如果你的数据集比你的磁盘大，或者你不想等待下载数据，你可以使用流式传输：

# Stream the dataset without downloading anything
image_dataset = load_dataset('timm/imagenet-1k-wds', streaming=True)
for example in image_dataset["train"]:
    print(example["image"])
    break

多模态数据

🤗 Datasets 开箱即支持多种数据类型：

# Audio dataset
dataset = load_dataset("openslr/librispeech_asr", "clean")

# Image dataset
dataset = load_dataset("ILSVRC/imagenet-1k")

# Video dataset
dataset = load_dataset("Shofo/shofo-tiktok-general-small")

# PDF documents
dataset = load_dataset("pixparse/pdfa-eng-wds")

# NIfTI (3D medical imaging)
dataset = load_dataset("dartbrains/localizer", "betas")

从本地文件

# Load from local CSV
dataset = load_dataset('csv', data_files='my_data.csv')

# Load from local Parquet
dataset = load_dataset('parquet', data_files='data/*.parquet')

# Load from a local directory (auto-detect format)
dataset = load_dataset('./path/to/data')

From Python 对象

from datasets import Dataset

# From a dictionary
dataset = Dataset.from_dict({"text": ["Hello world", "How are you?"]})

# From a list
dataset = Dataset.from_list([{"text": "Hello world"}, {"text": "How are you?"}])

# From Pandas
import pandas as pd
df = pd.DataFrame({"col1": [1, 2, 3], "col2": ["a", "b", "c"]})
dataset = Dataset.from_pandas(df)

# From a generator
def gen():
    for i in range(10):
        yield {"value": i}
dataset = Dataset.from_generator(gen)

有关使用该库的更多详细信息，请查看快速入门指南以及以下具体页面：

• 加载数据集
• 数据集中包含的内容
• 使用 🤗 Datasets 处理数据
  • 处理音频数据
  • 处理图像数据
  • 处理文本数据
  • 处理 PDF 数据
  • 处理视频数据
• 数据集流式处理

核心类

该库提供两个主要数据集类：

两者都被封装在 DatasetDict / IterableDatasetDict 中，用于多拆分数据集（例如，训练/测试/验证）。

向中心添加新数据集

我们有一个非常详细的逐步指南，介绍如何将新数据集添加到已有的 HuggingFace 数据集中心 提供的数据集中。

您可以找到：

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

免责声明

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

如果您是数据集所有者，希望更新其任何部分（描述、引用、许可许可等），或不希望您的数据集被包含在 Hugging Face Hub 中，请通过在数据集页面的社区标签页开启讨论或拉取请求与我们联系。感谢您对机器学习社区的贡献！

贡献

我们欢迎贡献！有关详细信息，请参阅我们的 贡献指南：

• 如何提交问题和拉取请求
• 代码风格指南（我们使用 Ruff）
• 测试要求
• 文档标准

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 = "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 库的特定版本以确保可重复性，您可以使用此 列表 中对应版本的 Zenodo DOI。