Hugging Face Datasets: Referência para Desenvolvedores

Um conjunto de dados do Hugging Face é uma coleção estruturada e versionada de dados armazenada no Hugging Face Hub e consumida por meio da biblioteca Python datasets . Cada conjunto de dados expõe uma ou maispartições (normalmente treino, validação e teste), um esquema tipado que descreve todas as colunas, além de metadados sobre licença, categoria de tarefa e marcadores linguísticos. A biblioteca lida com o download, o cacheamento e a conversão de formato, de modo que você quase nunca precisa lidar diretamente com arquivos brutos.características esquema que descreve todas as colunas, além de metadados que abrangem licença, categoria de tarefa e tags de idioma. A biblioteca lida com o download, o armazenamento em cache e a conversão de formato, de modo que você quase nunca precisa lidar diretamente com arquivos brutos.

Localizando Conjuntos de Dados no Hub

A principal interface de descoberta é huggingface.co/datasets. Filtros disponíveis na interface gráfica:

• Tarefa — classificação de texto, resposta a perguntas, segmentação de imagens, tradução, resumo, entre outros
• Idioma — códigos ISO 639-1 (en, zh, fr, de, …)
• Licença — Apache 2.0, MIT, CC-BY, CC0, OpenRAIL, etc.
• Categoria de tamanho — menos de 1 mil linhas até mais de 1 bilhão de linhas
• Modalidade — texto, imagem, áudio, vídeo, tabelar, multimodal

Você também pode pesquisar programaticamente usando o cliente Python do Hub:

from huggingface_hub import list_datasets

results = list_datasets(filter='task_categories:text-classification', limit=20)
for ds in results:
    print(ds.id, ds.downloads)

A API REST do Datasets Server expõe um endpoint /valid que lista todos os conjuntos de dados com exportações pré-computadas em formato Parquet, permitindo visualizações rápidas e amostragem de linhas sem baixar o conjunto completo.

Instalação

Odatasets A biblioteca é compatível com Python 3.8+ e independente de plataforma.

pip install datasets

Para suporte a imagens e áudio, instale os pacotes complementares relevantes:

pip install datasets[vision]# Pillow
pip install datasets    # librosa, soundfile

Para autenticação em conjuntos de dados privados ou para publicar dados no Hub:

pip install huggingface_hub
huggingface-cli login          # solicita seu token de acesso ao HF

Seu token é armazenado em ~/.cache/huggingface/token no macOS/Linux ou em %USERPROFILE%.cachehuggingfacetoken no Windows. Alternativamente, defina diretamente a variável de ambiente HF_TOKEN HF_TOKEN.

Carregando um Conjunto de Dados

O ponto de entrada principal é load_dataset(). Sem o argumentosplit , ele retorna um DatasetDict contendo todas as partições disponíveis:

from datasets import load_dataset

ds = load_dataset('stanfordnlp/imdb')
print(ds)
# DatasetDict({
#     train: Dataset({features: ['text', 'label'], num_rows: 25000})
#     test:  Dataset({features: ['text', 'label'], num_rows: 25000})
# })

train = ds['train']
print(train.features)
# {'text': Value(dtype='string'), 'label': ClassLabel(names=['neg', 'pos'])}

print(train[0]['text'][:120])

Carregando uma Única Divisão

train = load_dataset('stanfordnlp/imdb', split='train')
# Retorna um Dataset diretamente, não um DatasetDict

Carregando uma Configuração Nomeada

Muitos conjuntos de dados definem configurações nomeadas para variantes linguísticas, subconjuntos de domínio ou versões de esquema. Passe o nome da configuração como segundo argumento posicional:

ds = load_dataset('Helsinki-NLP/opus_books', 'en-fr')

Para listar todas as configurações disponíveis de um conjunto de dados antes do carregamento:

from datasets import get_dataset_config_names
print(get_dataset_config_names('Helsinki-NLP/opus_books'))

Carregando a Partir de Arquivos Locais

Passe um nome de formato e um caminho de arquivo em vez de um ID de conjunto de dados do Hub. Os formatos suportados incluem CSV, JSON/JSONL, Parquet, Arrow, texto simples, bem como as convenções ImageFolder/AudioFolder.

ds = load_dataset('csv', data_files='meus_dados.csv')
ds = load_dataset('json', data_files={'train': 'treino.jsonl', 'test': 'teste.jsonl'})
ds = load_dataset('imagefolder', data_dir='./fotos/')

Estrutura de um Conjunto de Dados: Partições e Recursos

Verifique quais divisões um conjunto de dados possui antes de carregá-lo:

from datasets import get_dataset_split_names
print(get_dataset_split_names('stanfordnlp/imdb'))
# ['train', 'test', 'unsupervised']

Ocaracterísticas dict mapeia nomes de colunas para descritores tipados. Tipos de recurso comuns:

Streaming de Grandes Conjuntos de Dados

Para conjuntos de dados muito grandes para serem baixados — Common Crawl, The Pile, LAION-5B — passe streaming=True. Os dados são buscados e decodificados sob demanda, sem ocupar seu disco:

ds = load_dataset('allenai/c4', 'en', split='train', streaming=True)

for example in ds.take(1000):
    print(example['text'][:80])

O modo streaming retorna umIterableDataset em vez de um Dataset. Ele suporta.map(), .filter(), .shuffle(buffer_size=N), e .take(N), mas não suporta indexação aleatória nem len(). Para obter um trecho fixo sem fazer o streaming de todo o conjunto de dados:

ds = load_dataset('allenai/c4', 'en', split='train[:50000]')

A fatiação de divisões aceita contagens absolutas de linhas ([:50000]), percentuais ([:10%]) e intervalos com passo ([10%:20%]).

Filtragem e Processamento

Todas as operações são executadas no Apache Arrow e usam multiprocessamento por padrão. O resultado é armazenado em cache no disco; executar novamente a mesma .map() nos mesmos dados retorna o cache instantaneamente.

# Filtrar linhas
short = train.filter(lambda x: len(x['text']) < 500)

# Mapeamento em lote — muito mais rápido para tokenização
def tokenize(batch):
    return tokenizer(batch['text'], truncation=True, padding='max_length')

tokenized = train.map(tokenize, batched=True, batch_size=256, num_proc=4)

# Operações em colunas
tokenized = tokenized.remove_columns(['text'])
ds = ds.rename_column('label', 'labels')

# Embaralhar e selecionar
ds = ds.shuffle(seed=42).select(range(10000))

Conversão para Outros Formatos

Publicando Seu Próprio Conjunto de Dados no Hub

Após executar huggingface-cli login, envie qualquerDataset ou DatasetDict objeto diretamente:

from datasets import Dataset, DatasetDict
import pandas as pd

df = pd.read_csv('my_data.csv')
ds = Dataset.from_pandas(df)

ds.push_to_hub('seu-usuario/minha-base-de-dados', private=False)

Para enviar as partições de treinamento e teste juntas:

split = ds.train_test_split(test_size=0.1)
DatasetDict({'train': split['train'], 'test': split['test']}).push_to_hub('seu-usuario/minha-base-de-dados')

O Hub armazena conjuntos de dados como arquivos Parquet fragmentados e gera automaticamente uma visualização interativa do conjunto de dados. Adicione um README.md cartão de conjunto de dados (Dataset Card) com metadados YAML no início do arquivo para tornar seu conjunto de dados filtrável por tarefa, idioma e licença na interface de busca do Hub.

Observações sobre Plataforma

Caminhos de cache

Windows

No Windows, é usado o método de inicializaçãospawn para processamento paralelo, o que exige que o ponto de entrada do seu script esteja dentro de um bloco if __name__ == '__main__': protegido. Sem isso,.map(num_proc=4) ficará travado ou gerará um erro RuntimeError. Se você estiver executando em um notebook Jupyter, use num_proc=1 ou instale o pacotemultiprocess juntamente com datasets, que a biblioteca prioriza em vez do módulo padrão multiprocessing da biblioteca-padrão.

Espaço em disco

Conjuntos de dados grandes (como Common Crawl, RedPajama e LAION) consomem centenas de gigabytes ao serem totalmente armazenados em cache. Use streaming=True para evitar downloads. Para ver o conteúdo do seu cache, execute python -c "from datasets import inspect_dataset; print(inspect_dataset.__doc__)" ou navegue diretamente pelo diretório de cache. Os conjuntos de dados em cache são armazenados como arquivos Arrow organizados por nome e hash do conjunto de dados; exclua manualmente as subpastas para recuperar espaço em disco.

Usando Conjuntos de Dados para Ajuste Fino e Avaliação

O fluxo-padrão de ajuste fino é: carregar o conjunto de dados → tokenizar com.map(batched=True) → definir o formato como 'torch' → passá-lo para um objetoTrainer ou para um loop de treinamento personalizado. A classe transformers da Hugging Face aceita um objeto Trainer diretamente como argumento para os parâmetros Dataset train_dataset e e eval_dataset .

Ao avaliar modelos em relação a conjuntos de dados de referência (benchmarks), o Ranking de LLMs fornece pontuações em conjuntos de avaliação comuns — um contexto útil ao decidir qual conjunto de dados usar como alvo para seu próprio benchmark. Se você estiver avaliando se deve fazer fine-tuning e hospedar o modelo localmente ou simplesmente chamar uma API, o calculadora de ponto de equilíbrio entre hospedagem local e uso de API pode modelar o ponto de inflexão de custo com base no volume de requisições. Para obter o custo bruto por token via API entre diferentes provedores, use o Calculadora de custos de API. E, se você pretende executar um modelo com fine-tuning localmente, a VRAM é a restrição física mais rígida — o Calculadora de VRAM estima os requisitos de memória da GPU com base no tamanho do modelo e na precisão da quantização.

Perguntas frequentes

Qual é a diferença entre um Dataset e um DatasetDict?

A Dataset é uma única divisão (split) — uma única tabela com linhas e colunas. Um DatasetDict é um contêiner semelhante a um dicionário que armazena múltiplas divisões e é o tipo de retorno padrão de load_dataset() quando você omite o argumento split . Acesse divisões individuais pela chave: ds['train'], ds['test'], etc. Se você passarsplit='train', obterá diretamente um objeto Dataset simples.

Como carregar um conjunto de dados privado do Hub?

Autentique-se primeiro com huggingface-cli login, ou defina a variável de ambiente HF_TOKEN como seu token de acesso. Em seguida, chame load_dataset('org/private-dataset', token=True). O bloco O parâmetro indica à biblioteca que deve usar as credenciais armazenadas em cache ou definidas na variável de ambiente. Para pipelines de CI/CD, defina HF_TOKEN como um segredo e omita a etapa interativa de login.

Por que load_dataset() demora tanto na primeira chamada?

A primeira chamada baixa os arquivos de dados brutos, converte-os para o formato Apache Arrow e grava o cache em disco. Para conjuntos de dados grandes, isso pode levar minutos ou mais. Chamadas subsequentes na mesma máquina retornam os arquivos Arrow em cache quase instantaneamente. Se você estiver em uma conexão lenta ou tiver espaço em disco limitado, passe streaming=True para processar os dados sob demanda, sem armazená-los em cache localmente.

Posso usar conjuntos de dados do Hugging Face sem conexão com a internet?

Sim. Uma vez que um conjunto de dados tenha sido armazenado em cache, defina a variável de ambiente HF_DATASETS_OFFLINE=1 eload_dataset() para que a biblioteca leia exclusivamente do cache local, sem realizar nenhuma solicitação de rede. Isso é útil em servidores isolados (air-gapped), execuções offline reproduzíveis ou clusters de computação de alto desempenho (HPC), onde os nós de trabalho não possuem acesso à internet, mas compartilham um sistema de arquivos em rede com o diretório de cache.

Qual formato de arquivo o Hub usa internamente?

Os conjuntos de dados armazenados no Hub são disponibilizados como arquivos Apache Parquet, divididos em fragmentos (shards). A biblioteca datasets baixa esses shards e os converte para o formato Apache Arrow (.arrow) para armazenamento em cache local. É possível ignorar totalmente a biblioteca e acessar os shards Parquet diretamente pelo navegador de arquivos do Hub ou usando huggingface_hub.hf_hub_download().

Qual é o tamanho máximo permitido para um conjunto de dados do Hugging Face?

Não há limite de tamanho imposto, e existem conjuntos de dados de vários terabytes no Hub (por exemplo, os pares imagem-texto LAION-5B ou grandes instantâneos do Common Crawl). Para conjuntos de dados acima de alguns gigabytes, o Hub armazena os dados como múltiplos shards Parquet, em vez de um único arquivo. Use streaming=True na biblioteca datasets para trabalhar com esses conjuntos de dados sem baixá-los integralmente, ou baixe shards específicos usando o argumento data_files .