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() 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 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:

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

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

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

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

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

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:

---
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 para ver quais parâmetros de configuração eles possuem.

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

Copiado

- 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