Bibliotecas

O Hub de Datasets oferece suporte a várias bibliotecas do ecossistema de Código Aberto. Graças à biblioteca Python huggingface_hub, é fácil habilitar o compartilhamento dos seus datasets no Hub. Temos o prazer de receber no Hub um conjunto de bibliotecas de Código Aberto que estão impulsionando o Aprendizado de Máquina.

Tabela de bibliotecas

A tabela abaixo resume as bibliotecas suportadas e seu nível de integração.

* Exige a passagem de argumentos extras para gravar arquivos Parquet otimizados

Bibliotecas de Processamento de Dados

Streaming

O streaming de datasets permite iterar sobre um dataset do Hugging Face de forma progressiva, sem a necessidade de baixá-lo por completo. Ele economiza espaço no disco local, pois os dados nunca ficam armazenados em disco. Ele economiza memória, já que apenas uma pequena parte do dataset é usada de cada vez. E ele economiza tempo, pois não é necessário baixar os dados antes da carga de trabalho da CPU ou da GPU.

Além de fazer streaming a partir do Hugging Face, muitas bibliotecas também suportam streaming de volta para o Hugging Face. Portanto, elas podem executar pipelines de streaming de ponta a ponta: fazendo streaming de uma fonte e gravando no Hugging Face progressivamente, muitas vezes sobrepondo as etapas de download, upload e processamento.

Para mais detalhes sobre como fazer streaming, consulte a documentação de uma biblioteca que suporte streaming (veja a tabela acima) ou a documentação de datasets de streaming, caso queira fazer streaming de datasets do Hugging Face por conta própria.

Arquivos Parquet otimizados

Arquivos Parquet no Hugging Face são otimizados para melhorar a eficiência de armazenamento, acelerar downloads e uploads e permitir streaming e edição eficientes de datasets.

Arquivos Parquet otimizados são arquivos Parquet com recursos adicionais:

• O Parquet Content Defined Chunking otimiza o Parquet para o Xet, o backend de armazenamento da Hugging Face. Ele acelera uploads e downloads graças à deduplicação baseada em chunks e permite a edição eficiente de arquivos
• O índice de página acelera os filtros durante o streaming e permite acesso aleatório eficiente, por exemplo, no Dataset Viewer

Algumas bibliotecas exigem um argumento extra para gravar arquivos Parquet otimizados, como Pandas e PyArrow:

• use_content_defined_chunking=True para habilitar o Parquet Content Defined Chunking, para deduplicação e edição
• write_page_index=True para incluir um índice de páginas nos metadados do Parquet, para transmissão e acesso aleatório

Bibliotecas de Treinamento

Bibliotecas de treinamento que se integram aos conjuntos de dados do Hub para o treinamento de modelos. A tabela abaixo mostra suas capacidades de streaming — a capacidade de treinar em conjuntos de dados sem baixá-los primeiro.

* SFTTrainer e DPOTrainer suportam streaming; GRPOTrainer ainda não suporta entrada em streaming

Streaming do Hub

O streaming permite treinar em conjuntos de dados massivos sem baixá-los primeiro. Isso é valioso quando:

• Seu conjunto de dados é grande demais para caber no disco
• Você deseja começar a treinar imediatamente
• Você está usando o HF Jobs, onde a computação co-localizada oferece streaming mais rápido

Melhorias recentes tornaram o streaming até 100x mais eficiente, com inicialização mais rápida, pré-busca e melhor escalonamento para muitos workers.

Observação: O streaming requer max_steps nos argumentos de treinamento, pois o comprimento do conjunto de dados é desconhecido, e utiliza embaralhamento baseado em buffer. Consulte conjuntos de dados em streaming para mais detalhes.

Registro no Hub

Algumas ferramentas podem transmitir dados de treinamento de volta para o Hub durante o treinamento:

• Trackio: Transmite métricas de treinamento para um dataset do Hub em tempo real

Integrando bibliotecas e ferramentas de dados com o Hub

Este guia foi criado para desenvolvedores e mantenedores de bibliotecas e ferramentas de dados que desejam integrar-se ao Hugging Face Hub. Seja você uma biblioteca de processamento de dados, uma ferramenta de análise ou qualquer software que precise interagir com conjuntos de dados, esta documentação ajudará você a implementar uma integração com o Hub.

O guia abrange:

• Abordagens possíveis para carregar dados do Hub para sua biblioteca/ferramenta
• Abordagens possíveis para enviar dados da sua biblioteca/ferramenta para o Hub

Carregando dados do Hub

Se você tem uma biblioteca para trabalhar com dados, pode ser útil para seus usuários carregar dados do Hub.

Em geral, sugerimos que você dependa de uma biblioteca existente, como datasets, pandas ou polars, para fazer isso, a menos que tenha um motivo específico para implementar a sua própria solução. Se você precisar de mais controle sobre o processo de carregamento, pode usar a biblioteca huggingface_hub, que permitirá, por exemplo, baixar um subconjunto específico de arquivos de um repositório.

Você pode encontrar mais informações sobre o carregamento de dados do Hub aqui.

Integração por meio do Dataset Viewer e dos arquivos Parquet

O visualizador de datasets do Hub e o sistema de conversão para Parquet oferecem uma maneira padronizada de integrar-se a datasets, independentemente do formato original. Essa infraestrutura é uma camada de integração confiável entre o Hub e bibliotecas externas.

Se o conjunto de dados não estiver já em Parquet, o Hub converte automaticamente os primeiros 5GB de cada conjunto de dados para o formato Parquet para alimentar o visualizador de conjuntos de dados e fornecer padrões de acesso consistentes. Essa padronização oferece vários benefícios para as integrações de biblioteca:

• Padrões de acesso a dados consistentes, independentemente do formato original
• Pré-visualização e exploração de conjuntos de dados integradas por meio do visualizador de conjuntos de dados do Hub. O visualizador de conjuntos de dados também pode ser incorporado como um iframe em seus aplicativos, facilitando a oferta de pré-visualizações ricas de conjuntos de dados. Para mais informações sobre a incorporação do visualizador, consulte a documentação de incorporação do visualizador de conjuntos de dados.
• Armazenamento colunar eficiente otimizado para consultas. Por exemplo, você pode usar uma ferramenta como DuckDB para consultar ou filtrar um subconjunto específico de dados.
• Parquet é bem suportado em todo o ecossistema de machine learning e ciência de dados.

Para mais detalhes sobre o trabalho com a API do Dataset Viewer, consulte a documentação da API do Dataset Viewer

Enviando dados para o Hub

Esta seção aborda possíveis abordagens para adicionar a capacidade de enviar dados para o Hub na sua biblioteca, ou seja, como implementar um método push_to_hub.

Este guia abordará três maneiras principais de enviar dados para o Hub:

• usando a biblioteca datasets e o método push_to_hub
• usando pandas para gravar no Hub
• usando a biblioteca huggingface_hub e o método upload_folder

Use a biblioteca datasets

A abordagem mais direta para enviar dados para o Hub é recorrer ao método push_to_hub existente da biblioteca datasets. O método push_to_hub tratará automaticamente de:

• a criação do repositório
• a conversão do dataset para Parquet
• dividir o conjunto de dados em partes adequadas
• enviando os dados

Por exemplo, se você tiver uma biblioteca de geração de dados sintéticos que retorna uma lista de dicionários, você pode simplesmente fazer o seguinte:

from datasets import Dataset

data = [{"prompt": "Write a cake recipe", "response": "Measure 1 cup ..."}]
ds = Dataset.from_list(data)
ds.push_to_hub("USERNAME_OR_ORG/repo_ID")

Exemplos desse tipo de integração:

• Distilabel

Dependa da integração de uma biblioteca existente com o Hub

Polars, Pandas, Dask, Spark, DuckDB e Daft podem todos gravar em um repositório do Hugging Face Hub. Consulte a tabela de bibliotecas acima para mais detalhes.

Se você já está usando uma dessas bibliotecas no seu código, adicionar a capacidade de enviar para o Hub é simples. Por exemplo, se você tem uma biblioteca de geração de dados sintéticos que pode retornar um DataFrame do Pandas, este é o código que você precisaria escrever para o Hub:

from huggingface_hub import HfApi

# Initialize the Hub API
hf_api = HfApi()

# Create a repository (if it doesn't exist)
hf_api.create_repo(repo_id="username/my-dataset", repo_type="dataset", exist_ok=True)

# Convert your data to a DataFrame and save directly to the Hub
df.to_parquet("hf://datasets/username/my-dataset/data.parquet")

Usando a biblioteca Python huggingface_hub

A biblioteca Python huggingface_hub oferece uma abordagem mais flexível para enviar dados ao Hub. A biblioteca permite que você envie arquivos específicos ou subconjuntos de arquivos para um repositório. Isso é útil se você tiver um conjunto de dados grande que não deseja converter para Parquet, quiser enviar um subconjunto específico de arquivos ou precisar de mais controle sobre a estrutura do repositório.

Dependendo do seu caso de uso, você pode enviar um arquivo ou pasta em um ponto específico do seu código, ou seja, exportar anotações de uma ferramenta para o Hub quando um usuário clica em “push to Hub”. Por exemplo,

from huggingface_hub import HfApi
api = HfApi()

api.upload_folder(
    folder_path="/my-cool-library/data-folder",
    repo_id="username/my-dataset",
    repo_type="dataset",
    commit_message="Push annotations to Hub",
    allow_patterns="*.jsonl",
)

Você pode encontrar mais informações sobre as formas de enviar dados para o Hub aqui.

Alternativamente, existem situações em que você pode querer enviar dados em segundo plano, por exemplo, dados sintéticos gerados a cada 10 minutos. Nesse caso, você pode usar a classe CommitScheduler da biblioteca huggingface_hub. Para mais detalhes, consulte a documentação de uploads agendados.

Você pode ver um exemplo do uso dessa abordagem para enviar dados para o Hub em

• A biblioteca fastdata
• Este Espaço de demonstração magpie

Mais suporte

Para dúvidas técnicas sobre integração, sinta-se à vontade para entrar em contato com a equipe de datasets em datasets@huggingface.co.