数据集文档
组织你的仓库
并获得增强的文档体验
开始
组织你的仓库
要托管和分享你的数据集,请在 Hugging Face Hub 上创建一个数据集仓库并上传你的数据文件。
本指南将向你展示上传数据集时如何组织你的数据集仓库。具有支持的结构和文件格式(.txt、.csv、.parquet、.jsonl、.mp3、.jpg、.zip 等)的数据集将通过 load_dataset() 自动加载,并且它将在 Hub 上的数据集页面上拥有一个数据集查看器。
主要用例
最简单的数据集结构有两个文件:train.csv
和 test.csv
(这适用于任何支持的文件格式)。
你的仓库还将包含一个 README.md
文件,即 数据集卡片 显示在你的数据集页面上。
my_dataset_repository/
├── README.md
├── train.csv
└── test.csv
在这种简单的情况下,你将获得一个包含两个拆分的数据集:train
(包含来自 train.csv
的示例)和 test
(包含来自 test.csv
的示例)。
在 YAML 中定义你的拆分和子集
拆分
如果你有多个文件并想定义哪个文件属于哪个拆分,你可以使用 README.md
顶部的 YAML configs
字段。
例如,给定这样一个仓库
my_dataset_repository/
├── README.md
├── data.csv
└── holdout.csv
你可以通过在 README.md
顶部的 YAML 块中添加 configs
字段来定义你的拆分
---
configs:
- config_name: default
data_files:
- split: train
path: "data.csv"
- split: test
path: "holdout.csv"
---
你可以使用路径列表为每个拆分选择多个文件
my_dataset_repository/
├── README.md
├── data/
│ ├── abc.csv
│ └── def.csv
└── holdout/
└── ghi.csv
---
configs:
- config_name: default
data_files:
- split: train
path:
- "data/abc.csv"
- "data/def.csv"
- split: test
path: "holdout/ghi.csv"
---
或者你可以使用 glob 模式自动列出你需要的所有文件
---
configs:
- config_name: default
data_files:
- split: train
path: "data/*.csv"
- split: test
path: "holdout/*.csv"
---
请注意,即使你只有一个配置,config_name
字段也是必需的。
配置
你的数据集可能包含你希望能够单独加载的多个数据子集。在这种情况下,你可以在 YAML 中的 configs
字段内定义一个配置列表
my_dataset_repository/
├── README.md
├── main_data.csv
└── additional_data.csv
---
configs:
- config_name: main_data
data_files: "main_data.csv"
- config_name: additional_data
data_files: "additional_data.csv"
---
每个配置在 Hugging Face Hub 上单独显示,并且可以通过传递其名称作为第二个参数来加载
from datasets import load_dataset
main_data = load_dataset("my_dataset_repository", "main_data")
additional_data = load_dataset("my_dataset_repository", "additional_data")
构建器参数
不仅 data_files
,其他构建器特定的参数也可以通过 YAML 传递,从而在不需任何自定义代码的情况下,更灵活地加载数据。例如,定义在哪个配置中使用哪个分隔符来加载你的 csv
文件
---
configs:
- config_name: tab
data_files: "main_data.csv"
sep: "\t"
- config_name: comma
data_files: "additional_data.csv"
sep: ","
---
请参考 特定构建器的文档,以查看它们有哪些配置参数。
你可以使用 default: true
设置默认配置,例如,如果你设置了以下内容,则可以运行 main_data = load_dataset("my_dataset_repository")
- config_name: main_data
data_files: "main_data.csv"
default: true
自动拆分检测
如果未提供 YAML,🤗 Datasets 会在数据集仓库中搜索某些模式以自动推断数据集拆分。模式有一个顺序,从自定义文件名拆分格式开始,到在未找到任何模式时将所有文件视为单个拆分。
目录名称
你的数据文件也可以放置在名为 train
、test
和 validation
的不同目录中,其中每个目录包含该拆分的的数据文件
my_dataset_repository/
├── README.md
└── data/
├── train/
│ └── bees.csv
├── test/
│ └── more_bees.csv
└── validation/
└── even_more_bees.csv
文件名拆分
如果你没有任何非传统的拆分,那么你可以将拆分名称放置在数据文件中的任何位置,它会被自动推断。唯一的规则是拆分名称必须用非单词字符分隔,例如 test-file.csv
而不是 testfile.csv
。支持的分隔符包括下划线、破折号、空格、点和数字。
例如,以下文件名都是可接受的
- 训练拆分:
train.csv
、my_train_file.csv
、train1.csv
- 验证拆分:
validation.csv
、my_validation_file.csv
、validation1.csv
- 测试拆分:
test.csv
、my_test_file.csv
、test1.csv
这是一个所有文件都放置在名为 data
的目录中的示例
my_dataset_repository/
├── README.md
└── data/
├── train.csv
├── test.csv
└── validation.csv
自定义文件名拆分
如果你的数据集拆分具有 train
、test
或 validation
以外的自定义名称,那么你可以将你的数据文件命名为 data/<split_name>-xxxxx-of-xxxxx.csv
。
这是一个包含三个拆分的示例,train
、test
和 random
my_dataset_repository/
├── README.md
└── data/
├── train-00000-of-00003.csv
├── train-00001-of-00003.csv
├── train-00002-of-00003.csv
├── test-00000-of-00001.csv
├── random-00000-of-00003.csv
├── random-00001-of-00003.csv
└── random-00002-of-00003.csv
单拆分
当 🤗 Datasets 找不到上述任何模式时,它会将所有文件视为单个训练拆分。如果你的数据集拆分未按预期加载,则可能是由于模式不正确。
拆分名称关键字
有几种命名拆分的方法。验证拆分有时称为“dev”,而测试拆分可能被称为“eval”。也支持这些其他拆分名称,以下关键字是等效的
- train, training
- validation, valid, val, dev
- test, testing, eval, evaluation
以下结构是一个有效的仓库
my_dataset_repository/
├── README.md
└── data/
├── training.csv
├── eval.csv
└── valid.csv
每个拆分多个文件
如果你的一个拆分包含多个文件,🤗 Datasets 仍然可以从文件名中推断出它是训练、验证还是测试拆分。例如,如果你的训练和测试拆分跨越多个文件
my_dataset_repository/
├── README.md
├── train_0.csv
├── train_1.csv
├── train_2.csv
├── train_3.csv
├── test_0.csv
└── test_1.csv
确保你的训练集的所有文件名中都包含 train(测试和验证集也一样)。即使你在文件名中为 train
添加前缀或后缀(例如 my_train_file_00001.csv
),🤗 Datasets 仍然可以推断出适当的拆分。
为了方便起见,你也可以将你的数据文件放置在不同的目录中。在这种情况下,拆分名称将从目录名称中推断出来。
my_dataset_repository/
├── README.md
└── data/
├── train/
│ ├── shard_0.csv
│ ├── shard_1.csv
│ ├── shard_2.csv
│ └── shard_3.csv
└── test/
├── shard_0.csv
└── shard_1.csv