# Estruture seu repositório

Para hospedar e compartilhar seu conjunto de dados, crie um repositório de conjunto de dados no Hugging Face Hub e envie seus arquivos de dados.

Este guia mostrará como estruturar seu repositório de dataset ao enviá-lo. Um dataset com estrutura e formato de arquivo suportados (`.txt`, `.csv`, `.parquet`, `.jsonl`, `.mp3`, `.jpg`, `.zip` etc.) é carregado automaticamente com [load_dataset()](/docs/datasets/main/pt/package_reference/loading_methods#datasets.load_dataset) e terá um visualizador de dataset em sua página de dataset no Hub.

## Principais casos de uso

A estrutura de dataset mais simples possui dois arquivos: `train.csv` e `test.csv` (isso funciona com qualquer formato de arquivo suportado).

O seu repositório também conterá um arquivo `README.md`, o [dataset card](dataset_card) exibido na página do seu dataset.

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

Neste caso simples, você obterá um dataset com duas divisões: `train` (contendo exemplos de `train.csv`) e `test` (contendo exemplos de `test.csv`).

## Defina suas divisões e subconjuntos em YAML

## Divisões

Se você tiver vários arquivos e quiser definir em qual split cada arquivo deve ser colocado, você pode usar o campo `configs` do YAML no topo do seu README.md.

Por exemplo, dado um repositório como este:

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

Você pode definir suas divisões adicionando o campo `configs` no bloco YAML no topo do seu README.md:

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

Você pode selecionar vários arquivos por split usando uma lista de caminhos:

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

Ou você pode usar padrões glob para listar automaticamente todos os arquivos necessários:

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

> [!WARNING]
> Observe que o campo `config_name` é obrigatório, mesmo que você tenha apenas uma configuração.

## Configurações

Seu conjunto de dados pode ter vários subconjuntos de dados que você deseja carregar separadamente. Nesse caso, você pode definir uma lista de configurações dentro do campo `configs` no 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"
---
```

Cada configuração é exibida separadamente no Hugging Face Hub e pode ser carregada passando seu nome como segundo parâmetro:

```python
from datasets import load_dataset

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

## Parâmetros do Builder

Não apenas `data_files`, mas também outros parâmetros específicos do builder podem ser passados via YAML, permitindo mais flexibilidade na forma de carregar os dados sem exigir nenhum código personalizado. Por exemplo, defina qual separador usar em qual configuração para carregar seus arquivos `csv`:

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

Consulte a [documentação dos builders específicos](./package_reference/builder_classes) para ver quais parâmetros de configuração eles possuem.

> [!TIP]
> Você pode definir uma configuração padrão usando `default: true`, por exemplo, você pode executar `main_data = load_dataset("my_dataset_repository")` se você definir
>
> ```yaml
> - config_name: main_data
>   data_files: "main_data.csv"
>   default: true
> ```

## Detecção automática de splits

Se nenhum YAML for fornecido, o 🤗 Datasets procura por certos padrões no repositório do dataset para inferir automaticamente as divisões do dataset. Existe uma ordem para os padrões, começando pelo formato de divisão de nome de arquivo personalizado até tratar todos os arquivos como uma única divisão, caso nenhum padrão seja encontrado.

### Nome do diretório

Os arquivos de dados também podem ser colocados em diretórios diferentes nomeados `train`, `test` e `validation`, onde cada diretório contém os arquivos de dados para essa divisão:

```
my_dataset_repository/
├── README.md
└── data/
    ├── train/
    │   └── bees.csv
    ├── test/
    │   └── more_bees.csv
    └── validation/
        └── even_more_bees.csv
```

### Divisões de nome de arquivo

Se você não tiver nenhum split não tradicional, pode colocar o nome do split em qualquer lugar do arquivo de dados e ele será inferido automaticamente. A única regra é que o nome do split deve ser delimitado por caracteres não alfanuméricos, como `test-file.csv`, por exemplo, em vez de `testfile.csv`. Os delimitadores suportados incluem sublinhados, hífens, espaços, pontos e números.

Por exemplo, os seguintes nomes de arquivo são todos aceitáveis:

- treino: `train.csv`, `my_train_file.csv`, `train1.csv`
- split de validação: `validation.csv`, `my_validation_file.csv`, `validation1.csv`
- conjunto de teste: `test.csv`, `my_test_file.csv`, `test1.csv`

Aqui está um exemplo em que todos os arquivos são colocados em um diretório chamado `data`:

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

### Divisão de nome de arquivo personalizado

Se as divisões do seu conjunto de dados tiverem nomes personalizados que não sejam `train`, `test` ou `validation`, você pode nomear seus arquivos de dados como `data/<split_name>-xxxxx-of-xxxxx.csv`.

Aqui está um exemplo com três divisões, `train`, `test` e `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
```

### Divisão única

Quando o 🤗 Datasets não encontra nenhum dos padrões acima, ele trata todos os arquivos como um único split de treino. Se os splits do seu dataset não estiverem sendo carregados como esperado, isso pode ser devido a um padrão incorreto.

### Palavras-chave do nome dividido

Existem várias formas de nomear as divisões. As divisões de validação são às vezes chamadas de "dev", e as divisões de teste podem ser referidas como "eval". Esses outros nomes de divisão também são suportados, e as seguintes palavras-chave são equivalentes:

- treino, treinamento
- validação, válido, val, dev
- test, testing, eval, evaluation

A estrutura abaixo é um repositório válido:

```
my_dataset_repository/
├── README.md
└── data/
    ├── training.csv
    ├── eval.csv
    └── valid.csv
```

### Vários arquivos por divisão

Se uma das suas divisões compreende vários arquivos, o 🤗 Datasets ainda pode inferir se é a divisão de treino, validação e teste a partir do nome do arquivo. Por exemplo, se suas divisões de treino e teste abrangem vários arquivos:

```
my_dataset_repository/
├── README.md
├── train_0.csv
├── train_1.csv
├── train_2.csv
├── train_3.csv
├── test_0.csv
└── test_1.csv
```

Certifique-se de que todos os arquivos do seu conjunto `train` tenham *train* em seus nomes (o mesmo para teste e validação). Mesmo que você adicione um prefixo ou sufixo a `train` no nome do arquivo (como `my_train_file_00001.csv`, por exemplo), o 🤗 Datasets ainda pode inferir a divisão apropriada.

Para sua conveniência, você também pode colocar seus arquivos de dados em diretórios diferentes. Nesse caso, o nome do split é inferido a partir do nome do diretório.

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

