Compartilhe um conjunto de dados usando a CLI

Na Hugging Face, temos a missão de democratizar um bom Machine Learning e acreditamos no valor do open source. Por isso, projetamos o 🤗 Datasets para que qualquer pessoa possa compartilhar um dataset com a comunidade de ML em geral. Atualmente, há milhares de datasets em mais de 100 idiomas no Hugging Face Hub, e a equipe da Hugging Face sempre dá as boas-vindas a novas contribuições!

Os repositórios de conjuntos de dados oferecem recursos como:

• Hospedagem gratuita de conjuntos de dados
• Versionamento de datasets
• Histórico de commits e diffs
• Metadados para descoberta
• Cards de dataset para documentação, licenciamento, limitações, etc.
• Visualizador de Conjuntos de Dados

Este guia mostrará como compartilhar uma pasta ou repositório de conjunto de dados que pode ser facilmente acessado por qualquer pessoa.

Adicionar um conjunto de dados

Você pode compartilhar seu conjunto de dados com a comunidade por meio de um repositório de conjuntos de dados no Hugging Face Hub. Ele também pode ser um conjunto de dados privado, caso você queira controlar quem tem acesso a ele.

Em um repositório de dataset, você pode hospedar todos os seus arquivos de dados e configurar seu dataset para definir qual arquivo vai para qual split. Os seguintes formatos são suportados: CSV, TSV, JSON, JSON lines, texto, Parquet, Arrow, SQLite, WebDataset. Muitos tipos de arquivos compactados também são suportados: GZ, BZ2, LZ4, LZMA ou ZSTD. Por exemplo, seu dataset pode ser composto por arquivos .json.gz.

Ao carregar um dataset do Hub, todos os arquivos nos formatos suportados são carregados, seguindo a estrutura do repositório.

Para mais informações sobre como carregar um dataset do Hub, confira o tutorial carregar um dataset do Hub.

Criar o repositório

Compartilhar um conjunto de dados da comunidade exigirá que você crie uma conta no hf.co, caso ainda não tenha uma. Você pode criar diretamente um novo repositório de conjunto de dados a partir da sua conta no Hugging Face Hub, mas este guia mostrará como enviar um conjunto de dados pelo terminal.

1. Certifique-se de que você está no ambiente virtual onde instalou o Datasets e execute o seguinte comando:

hf auth login

2. Faça login usando suas credenciais do Hugging Face Hub e crie um novo repositório de dataset:

hf repos create my-cool-dataset --type dataset

Prefixe o nome do repositório com uma organização para criá-lo sob essa organização:

hf repos create your-org-name/my-cool-dataset --type dataset

Prepare seus arquivos

Verifique seu diretório para garantir que os únicos arquivos que você está enviando são:

• Os arquivos de dados do conjunto de dados

• O cartão do conjunto de dados README.md

hf upload

Use o comando hf upload para enviar arquivos diretamente para o Hub. Internamente, ele usa os mesmos auxiliares upload_file e upload_folder descritos no Guia de upload. Nos exemplos abaixo, passaremos pelos casos de uso mais comuns. Para uma lista completa das opções disponíveis, você pode executar:

>>> hf upload --help

Para mais informações gerais sobre o hf, você pode consultar o guia da CLI.

Envie uma pasta inteira

O uso padrão para este comando é:

# Usage:  hf upload [dataset_repo_id] [local_path] [path_in_repo] --repo-type dataset

Para enviar o diretório atual na raiz do repositório, use:

>>> hf upload my-cool-dataset . . --repo-type dataset
https://huggingface.co/datasets/Wauplin/my-cool-dataset/tree/main/

Se o repositório ainda não existir, ele será criado automaticamente.

Você também pode enviar uma pasta específica:

>>> hf upload my-cool-dataset ./data . --repo-type dataset
https://huggingface.co/datasetsWauplin/my-cool-dataset/tree/main/

Por fim, você pode enviar uma pasta para um destino específico no repositório:

>>> hf upload my-cool-dataset ./path/to/curated/data /data/train --repo-type dataset
https://huggingface.co/datasetsWauplin/my-cool-dataset/tree/main/data/train

Envie um arquivo único

Você também pode enviar um arquivo único definindo local_path para apontar para um arquivo em sua máquina. Nesse caso, path_in_repo é opcional e usará o nome do seu arquivo local por padrão:

>>> hf upload Wauplin/my-cool-dataset ./files/train.csv --repo-type dataset
https://huggingface.co/datasetsWauplin/my-cool-dataset/blob/main/train.csv

Se você deseja enviar um arquivo único para um diretório específico, defina path_in_repo de acordo:

>>> hf upload Wauplin/my-cool-dataset ./files/train.csv /data/train.csv --repo-type dataset
https://huggingface.co/datasetsWauplin/my-cool-dataset/blob/main/data/train.csv

Carregar vários arquivos

Para enviar vários arquivos de uma pasta de uma vez, sem enviar a pasta inteira, use os padrões --include e --exclude. Também é possível combiná-los com a opção --delete para excluir arquivos no repositório enquanto envia novos. No exemplo abaixo, sincronizamos o Space local excluindo arquivos remotos e enviando todos os arquivos CSV:

# Sync local Space with Hub (upload new CSV files, delete removed files)
>>> hf upload Wauplin/my-cool-dataset --repo-type dataset --include="/data/*.csv" --delete="*" --commit-message="Sync local dataset with Hub"
...

Upload para uma organização

Para enviar conteúdo para um repositório pertencente a uma organização em vez de um repositório pessoal, você deve especificá-lo explicitamente no repo_id:

>>> hf upload MyCoolOrganization/my-cool-dataset . . --repo-type dataset
https://huggingface.co/datasetsMyCoolOrganization/my-cool-dataset/tree/main/

Upload para uma revisão específica

Por padrão, os arquivos são enviados para o ramo main. Se você quiser enviar arquivos para outro ramo ou referência, use a opção --revision:

# Upload files to a PR
hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
...

Observação: se revision não existir e --create-pr não estiver definido, um branch será criado automaticamente a partir do branch main.

Envie e crie um PR

Se você não tiver permissão para fazer push em um repositório, deve abrir um PR e informar os autores sobre as alterações que deseja fazer. Isso pode ser feito definindo a opção --create-pr:

# Create a PR and upload the files to it
>>> hf upload bigcode/the-stack --repo-type dataset --revision refs/pr/104 --create-pr . .
https://huggingface.co/datasets/bigcode/the-stack/blob/refs%2Fpr%2F104/

Envie em intervalos regulares

Em alguns casos, você pode querer enviar atualizações regulares para um repositório. Por exemplo, isso é útil se o seu conjunto de dados estiver crescendo ao longo do tempo e você quiser enviar a pasta de dados a cada 10 minutos. Você pode fazer isso usando a opção --every:

# Upload new logs every 10 minutes
hf upload my-cool-dynamic-dataset data/ --every=10

Especifique uma mensagem de commit

Use o --commit-message e o --commit-description para definir uma mensagem e descrição personalizadas para o seu commit, em vez da padrão

>>> hf upload Wauplin/my-cool-dataset ./data . --repo-type dataset --commit-message="Version 2" --commit-description="Train size: 4321. Check Dataset Viewer for more details."
...
https://huggingface.co/datasetsWauplin/my-cool-dataset/tree/main

Especifique um token

Para enviar arquivos, você deve usar um token. Por padrão, o token salvo localmente (usando hf auth login) será utilizado. Se você quiser autenticar explicitamente, use a opção --token:

>>> hf upload Wauplin/my-cool-dataset ./data . --repo-type dataset --token=hf_****
...
https://huggingface.co/datasetsWauplin/my-cool-data/tree/main

Modo silencioso

Por padrão, o comando hf upload é detalhado. Ele exibe informações como mensagens de aviso, detalhes sobre os arquivos enviados e barras de progresso. Se você deseja silenciar tudo isso, use a opção --quiet. Apenas a última linha (ou seja, a URL dos arquivos enviados) é exibida. Isso pode ser útil se você quiser passar a saída para outro comando em um script.

>>> hf upload Wauplin/my-cool-dataset ./data . --repo-type dataset --quiet
https://huggingface.co/datasets/Wauplin/my-cool-dataset/tree/main

Aproveite!

Parabéns, seu conjunto de dados agora foi enviado ao Hugging Face Hub, onde qualquer pessoa pode carregá-lo em uma única linha de código! 🥳

dataset = load_dataset("Wauplin/my-cool-dataset")

Se o seu conjunto de dados for suportado, ele também deve ter um Dataset Viewer para que todos possam explorar o conteúdo do conjunto de dados.

Por fim, não se esqueça de enriquecer o cartão do conjunto de dados para documentá-lo e torná-lo mais fácil de encontrar! Consulte o guia Criar um cartão de conjunto de dados para saber mais.