# 组织你的仓库

要在 Hugging Face Hub 上托管并共享您的数据集，请创建一个数据集仓库并上传您的数据文件。

本指南将展示在上传数据集时如何组织数据集仓库。具有受支持的结构和文件格式（`.txt`、`.csv`、`.parquet`、`.jsonl`、`.mp3`、`.jpg`、`.zip` 等）的数据集会通过 [load_dataset()](/docs/datasets/main/zh/package_reference/loading_methods#datasets.load_dataset) 自动加载，并且其 Hub 上的数据集页面将包含一个数据集查看器。

## 主要用例

最简单的数据集结构包含两个文件：`train.csv` 和 `test.csv`（适用于任何受支持的文件格式）。

您的仓库还将包含一个 `README.md` 文件，即显示在您的数据集页面上的 [数据集卡片](dataset_card)。

```
my_dataset_repository/
├── README.md
├── train.csv
└── test.csv
```

在这个简单示例中，你将获得一个包含两个子集的数据集：`train`（包含来自 `train.csv` 的样本）和 `test`（包含来自 `test.csv` 的样本）。

## 在 YAML 中定义你的数据划分和子集

## 拆分

如果您有多个文件并希望定义每个文件属于哪个 split，可以在 README.md 顶部使用 YAML `configs` 字段。

例如，给定一个如下所示的仓库：

```
my_dataset_repository/
├── README.md
├── data.csv
└── holdout.csv
```

您可以在 README.md 顶部的 YAML 块中添加 `configs` 字段来定义数据划分：

```yaml
---
configs:
- config_name: default
  data_files:
  - split: train
    path: "data.csv"
  - split: test
    path: "holdout.csv"
---
```

您可以使用路径列表为每个 split 选择多个文件：

```
my_dataset_repository/
├── README.md
├── data/
│   ├── abc.csv
│   └── def.csv
└── holdout/
    └── ghi.csv
```

```yaml
---
configs:
- config_name: default
  data_files:
  - split: train
    path:
    - "data/abc.csv"
    - "data/def.csv"
  - split: test
    path: "holdout/ghi.csv"
---
```

或者，您可以使用 glob 模式自动列出所需的所有文件：

```yaml
---
configs:
- config_name: default
  data_files:
  - split: train
    path: "data/*.csv"
  - split: test
    path: "holdout/*.csv"
---
```

> [!WARNING]
> 请注意，即使只有一个配置，`config_name` 字段也是必需的。

## 配置

您的数据集可能包含多个希望单独加载的数据子集。在这种情况下，您可以在 YAML 的 `configs` 字段中定义一个配置列表：

```
my_dataset_repository/
├── README.md
├── main_data.csv
└── additional_data.csv
```

```yaml
---
configs:
- config_name: main_data
  data_files: "main_data.csv"
- config_name: additional_data
  data_files: "additional_data.csv"
---
```

每个配置在 Hugging Face Hub 上单独展示，可以通过将其名称作为第二个参数传入来加载：

```python
from datasets import load_dataset

main_data = load_dataset("my_dataset_repository", "main_data")
additional_data = load_dataset("my_dataset_repository", "additional_data")
```

## Builder 参数

不仅`data_files`，其他特定于构建器的参数也可以通过 YAML 传递，从而在加载数据时提供更大的灵活性，且无需编写任何自定义代码。例如，定义在加载`csv`文件时，在哪个配置中使用哪个分隔符：

```yaml
---
configs:
- config_name: tab
  data_files: "main_data.csv"
  sep: "\t"
- config_name: comma
  data_files: "additional_data.csv"
  sep: ","
---
```

请参阅[特定构建器的文档](./package_reference/builder_classes)，以了解它们具有哪些配置参数。

> [!TIP]
> 您可以使用 `default: true` 设置默认配置，例如，如果您设置了 `main_data = load_dataset("my_dataset_repository")`，就可以运行
>
> ```yaml
> - 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 无法找到上述任何模式时，它会将所有文件视为单个 train split。如果您的数据集 split 未按预期加载，可能是由于模式不正确所致。

### 拆分名称关键字

有几种方式为数据划分命名。验证集有时被称为“dev”，测试集则可能被称为“eval”。这些其他划分名称同样受支持，且以下关键字是等价的：

- train, 训练
- 验证，有效，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 仍然可以推断出正确的 split。

为了方便起见，您也可以将数据文件放置在不同的目录中。在这种情况下，分割名称将根据目录名称推断得出。

```
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
```