Datasets 文档
构建和加载
并获得增强的文档体验
开始使用
构建和加载
几乎所有的深度学习工作流程都始于加载数据集,这使得它成为最重要的步骤之一。借助 🤗 Datasets,有超过 900 个数据集可供你开始进行 NLP 任务。你所要做的就是调用:load_dataset() 来迈出你的第一步。这个函数在各个方面都是一个真正的“主力”,因为它构建并加载你使用的每个数据集。
ELI5: load_dataset
让我们从一个基本的“五岁小孩都能懂”的解释开始。
数据集是一个包含以下内容的目录:
- 一些通用格式的数据文件(JSON、CSV、Parquet、文本等)
- 一个名为
README.md
的数据集卡片,其中包含有关数据集的文档以及定义数据集标签和配置的 YAML 头部
load_dataset() 函数从本地或 Hugging Face Hub 获取请求的数据集。Hub 是一个中央存储库,所有 Hugging Face 数据集和模型都存储在那里。
如果数据集只包含数据文件,那么 load_dataset() 会自动根据其扩展名(json、csv、parquet、txt 等)推断如何加载数据文件。在底层,🤗 Datasets 将根据数据文件格式使用适当的 DatasetBuilder。🤗 Datasets 中每种数据文件格式都有一个构建器:
- datasets.packaged_modules.text.Text 用于文本
- datasets.packaged_modules.csv.Csv 用于 CSV 和 TSV
- datasets.packaged_modules.json.Json 用于 JSON 和 JSONL
- datasets.packaged_modules.parquet.Parquet 用于 Parquet
- datasets.packaged_modules.arrow.Arrow 用于 Arrow(流式文件格式)
- datasets.packaged_modules.sql.Sql 用于 SQL 数据库
- datasets.packaged_modules.imagefolder.ImageFolder 用于图像文件夹
- datasets.packaged_modules.audiofolder.AudioFolder 用于音频文件夹
阅读分享部分,了解如何分享数据集的更多信息。
🤗 Datasets 从原始 URL 下载数据集文件,生成数据集并将其缓存为硬盘上的 Arrow 表。如果你之前下载过数据集,那么 🤗 Datasets 将从缓存中重新加载它,以省去你再次下载的麻烦。
现在你已经对数据集的构建方式有了高层次的理解,让我们更深入地了解这一切是如何运作的。
构建数据集
当你第一次加载数据集时,🤗 Datasets 会获取原始数据文件并将其构建成一个由行和类型化列组成的表。有两个主要类负责构建数据集:BuilderConfig 和 DatasetBuilder。

BuilderConfig
BuilderConfig 是 DatasetBuilder 的配置类。BuilderConfig 包含以下关于数据集的基本属性:
属性 | 描述 |
---|---|
名称 | 数据集的简短名称。 |
版本 | 数据集版本标识符。 |
数据目录 | 存储包含数据文件的本地文件夹路径。 |
数据文件 | 存储本地数据文件的路径。 |
描述 | 数据集的描述。 |
如果你想为数据集添加额外的属性,例如类标签,你可以继承基类 BuilderConfig。填充 BuilderConfig 类或子类属性有两种方法:
在数据集的
DatasetBuilder.BUILDER_CONFIGS()
属性中提供一个预定义 BuilderConfig 类(或子类)实例的列表。当你调用 load_dataset() 时,任何不特定于该方法的关键字参数都将用于设置 BuilderConfig 类的相关属性。如果选择了特定配置,这将覆盖预定义的属性。
你也可以将 DatasetBuilder.BUILDER_CONFIG_CLASS 设置为 BuilderConfig 的任何自定义子类。
DatasetBuilder
DatasetBuilder 访问 BuilderConfig 中的所有属性来构建实际的数据集。

DatasetBuilder 中有三个主要方法:
DatasetBuilder._info()
负责定义数据集属性。当你调用dataset.info
时,🤗 Datasets 返回此处存储的信息。同样,Features 也在此处指定。请记住,Features 就像数据集的骨架。它提供了每一列的名称和类型。DatasetBuilder._split_generator
下载或检索请求的数据文件,将它们组织成切分,并为生成过程定义特定参数。此方法有一个 DownloadManager,用于下载文件或从本地文件系统获取文件。在 DownloadManager 中,有一个 DownloadManager.download_and_extract() 方法,它接受一个包含原始数据文件 URL 的字典,并下载请求的文件。接受的输入包括:单个 URL 或路径,或 URL 或路径的列表/字典。任何压缩文件类型(如 TAR、GZIP 和 ZIP 存档)都将自动提取。文件下载完成后,SplitGenerator 会将它们组织成数据切分。SplitGenerator 包含数据切分的名称,以及提供给
DatasetBuilder._generate_examples
方法的任何关键字参数。关键字参数可以特定于每个数据切分,并且通常至少包含每个数据切分的数据文件的本地路径。DatasetBuilder._generate_examples
读取并解析数据切分的数据文件。然后,它根据DatasetBuilder._info()
中features
指定的格式生成数据集示例。DatasetBuilder._generate_examples
的输入实际上是最后一个方法的关键字参数中提供的filepath
。数据集由 Python 生成器生成,它不会将所有数据加载到内存中。因此,生成器可以处理大型数据集。但是,在生成的样本刷新到磁盘上的数据集文件之前,它们会存储在
ArrowWriter
缓冲区中。这意味着生成的样本是批量写入的。如果你的数据集样本消耗大量内存(图像或视频),请确保在 DatasetBuilder 中为DEFAULT_WRITER_BATCH_SIZE
属性指定一个低值。我们建议不要超过 200 MB 的大小。
维护完整性
为确保数据集完整,load_dataset() 将对下载的文件执行一系列测试,以确保所有内容都已到位。这样,当请求的数据集未按预期生成时,你就不会遇到任何意外。load_dataset() 验证:
- 生成的
DatasetDict
中的分割数量。 - 生成的
DatasetDict
中每个分割的样本数量。 - 已下载文件的列表。
- 已下载文件的 SHA256 校验和(默认禁用)。
如果数据集未能通过验证,很可能是数据集作者对数据文件进行了一些更改。
在这种情况下,会抛出错误以提醒数据集已更改。要忽略该错误,需要在 load_dataset() 中指定 verification_mode="no_checks"
。无论何时你看到验证错误,请随时在相应数据集的“社区”选项卡中打开讨论或拉取请求,以便更新该数据集的完整性检查。
安全
Hub 上的数据集仓库会进行恶意软件扫描,更多信息请参阅此处。
< > 在 GitHub 上更新