# Структура вашего репозитория

Чтобы разместить и поделиться своим набором данных, создайте репозиторий датасета на Hugging Face Hub и загрузите файлы с данными.

В этом руководстве показано, как структурировать репозиторий набора данных при его загрузке. Набор данных с поддерживаемой структурой и форматом файлов (`.txt`, `.csv`, `.parquet`, `.jsonl`, `.mp3`, `.jpg`, `.zip` и т. д.) автоматически загружается с помощью [load_dataset()](/docs/datasets/v5.2.0/ru/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

## Разделения

Если у вас несколько файлов и вы хотите определить, какой файл попадает в какой сплит, используйте поле `configs` в формате YAML в начале вашего README.md.

Например, если у вас есть репозиторий, похожий на этот:

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

Вы можете определить свои разбиения, добавив поле `configs` в YAML-блок в начале вашего README.md:

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

```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` является обязательным, даже если у вас только одна конфигурация.

## Конфигурации

Ваш набор данных может содержать несколько подмножеств, которые вы хотите загружать отдельно. В этом случае вы можете определить список конфигураций в поле `configs` в YAML:

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

## Параметры конструктора

Не только `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 ищет определённые шаблоны в репозитории датасета, чтобы автоматически определить разбиения (splits) датасета. Шаблоны проверяются в определённом порядке: от формата разбиения по имени файла до обработки всех файлов как единого разбиения, если ни один шаблон не найден.

### Имя каталога

Файлы данных также могут быть размещены в разных каталогах с именами `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 split: `train.csv`, `my_train_file.csv`, `train1.csv`
- раздел для валидации: `validation.csv`, `my_validation_file.csv`, `validation1.csv`
- test split: `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, обучение
- 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* (то же самое для test и validation). Даже если вы добавите префикс или суффикс к `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
```

