Datasets documentation

构建并加载

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.2.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

构建并加载

几乎每个深度学习工作流都从加载数据集开始,因此这是最重要的步骤之一。借助 🤗 Datasets,您可以使用超过 900 个数据集来启动您的 NLP 任务。您只需调用 load_dataset() 即可迈出第一步。从某种意义上说,这个函数是真正的多面手,因为它负责构建并加载您使用的每个数据集。

ELI5:load_dataset

让我们从一个“像对五岁小孩解释一样”的基础版本开始。

数据集是一个包含以下内容的目录:

  • 一些采用通用格式(JSON、CSV、Parquet、文本等)的数据文件
  • 一个名为 README.md 的数据集卡片,其中包含有关该数据集的文档,以及一个用于定义数据集标签和配置的 YAML 头部

load_dataset() 函数会从本地或 Hugging Face Hub 获取所需的 dataset。Hub 是一个中心仓库,用于存储所有 Hugging Face 的 dataset 和模型。

如果数据集仅包含数据文件,那么 load_dataset() 会根据文件扩展名(json、csv、parquet、tsfile、txt 等)自动推断如何加载这些数据文件。 在底层,🤗 Datasets 会根据数据文件的格式使用相应的 DatasetBuilder。🤗 Datasets 中每种数据文件格式都有一个对应的 builder:

阅读 Share 部分,了解如何共享数据集的更多信息。

🤗 Datasets 会从原始 URL 下载数据集文件,生成数据集并将其缓存为驱动器上的 Arrow 表。 如果您之前已下载过该数据集,🤗 Datasets 将从缓存中重新加载它,从而免去您再次下载的麻烦。

现在,在你对数据集的构建方式有了高层面的了解之后,让我们更深入地看看这一切是如何运作的。

构建数据集

首次加载数据集时,🤗 Datasets 会读取原始数据文件,并将其构建为包含行和类型化列的表格。负责构建数据集的两个主要类是 BuilderConfig 和 DatasetBuilder。

BuilderConfig

BuilderConfig 是 DatasetBuilder 的配置类。BuilderConfig 包含数据集的以下基本属性:

属性描述
name数据集的简短名称。
version数据集版本标识符。
data_dir存储包含数据文件的本地文件夹的路径。
data_files存储本地数据文件的路径。
description数据集的描述。

如果您想为数据集添加其他属性(例如类别标签),可以继承基类 BuilderConfig。为 BuilderConfig 类或其子类填充属性有两种方式:

  • 在数据集的 DatasetBuilder.BUILDER_CONFIGS() 属性中,提供一个预定义的 BuilderConfig 类(或其子类)实例列表。

  • 调用 load_dataset() 时,任何不属于该方法特有的关键字参数都将用于设置 BuilderConfig 类的相应属性。如果选择了特定配置,这将覆盖预定义属性。

您还可以将 DatasetBuilder.BUILDER_CONFIG_CLASS 设置为 BuilderConfig 的任意自定义子类。

DatasetBuilder

DatasetBuilder 会访问 BuilderConfig 内部的所有属性来构建实际的 dataset。

DatasetBuilder 中有三个主要方法:

  1. DatasetBuilder._info() 负责定义数据集的属性。当你调用 dataset.info 时,🤗 Datasets 会返回此处存储的信息。同样,Features 也是在此处指定的。请记住,Features 就像是数据集的骨架,它提供了每一列的名称和类型。

  2. DatasetBuilder._split_generator 负责下载或获取所需的数据文件,将它们组织为不同的 split,并为生成过程定义特定参数。该方法包含一个 DownloadManager,用于下载文件或从本地文件系统获取文件。在 DownloadManager 中,有一个 DownloadManager.download_and_extract() 方法,它接受一个指向原始数据文件的 URL 字典,并下载所需的文件。接受的输入包括:单个 URL 或路径,或 URL 或路径的列表/字典。任何压缩文件类型(如 TAR、GZIP 和 ZIP 归档)都会被自动解压。

    文件下载完成后,SplitGenerator 会将它们组织成各个 split。SplitGenerator 包含 split 的名称,以及传递给 DatasetBuilder._generate_examples 方法的任何关键字参数。这些关键字参数可以针对每个 split 单独指定,通常至少包含每个 split 的数据文件的本地路径。

  3. DatasetBuilder._generate_examples 读取并解析某个 split 的数据文件。然后,它根据 DatasetBuilder._info() 中 features 指定的格式生成数据集示例。DatasetBuilder._generate_examples 的输入实际上是上一个方法的关键词参数中提供的 filepath。

    数据集通过 Python 生成器生成,该生成器不会将所有数据加载到内存中。因此,生成器可以处理大型数据集。但是,在生成的样本刷新到磁盘上的数据集文件之前,它们会存储在 ArrowWriter 缓冲区中。这意味着生成的样本是按批次写入的。如果您的数据集样本占用大量内存(例如图像或视频),请确保在 DatasetBuilder 中为 DEFAULT_WRITER_BATCH_SIZE 属性指定一个较低的值。我们建议不要超过 200 MB。

维护完整性

为确保数据集完整,load_dataset() 会对下载的文件执行一系列测试,以确认所有内容均已就位。这样,当所请求的数据集未能按预期生成时,您就不会遇到任何意外情况。load_dataset() 会验证:

  • 生成的DatasetDict中分割的数量。
  • 生成的 DatasetDict 中每个 split 的样本数量。
  • 已下载文件的列表。
  • 已下载文件的 SHA256 校验和(默认禁用)。

如果数据集未通过验证,则很可能是数据集作者对数据文件进行了一些更改。

在这种情况下,会引发一个错误以提示数据集已发生变化。 若要忽略该错误,需要在 load_dataset() 中指定 verification_mode="no_checks"。 每当遇到验证错误时,欢迎在相应数据集的“Community”标签页中发起讨论或提交拉取请求,以便更新该数据集的完整性检查。

安全

Hub 上的数据集仓库会进行恶意软件扫描,更多信息请参见此处。

Update on GitHub