Hugging Face 的 LOGO

Datasets 文档

库结构

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

库结构

要托管和共享您的数据集，请在 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"
---

或者您可以使用通配符模式自动列出您需要的所有文件。

---
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/-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*（测试和验证文件也一样）。即使您在文件名中为 `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
< > 在 GitHub 上更新

←创建数据集卡片 数据集 🤝 Arrow→