Ingestão de Conjuntos de Dados

Os dados geralmente ficam armazenados em bancos de dados ou em armazenamento na nuvem em formatos que não são adequados para fluxos de trabalho de IA. Ingerir dados no Hub é uma boa maneira de publicá-los como conjuntos de dados prontos para IA, permitindo carregamento, processamento, treinamento e avaliação de modelos de forma fácil e eficiente.

Usando huggingface_hub

A maneira mais simples de ingerir dados é simplesmente enviar os arquivos de dados com huggingface_hub.

A biblioteca Python huggingface_hub oferece um conjunto rico de recursos que permite gerenciar repositórios, incluindo a criação de repositórios e o upload de conjuntos de dados para o Hub. Consulte a documentação da biblioteca de cliente para saber mais.

Isso é relevante se seus dados forem estáticos/congelados e se você puder obter facilmente um despejo local dos dados em um formato suportado pelo Hub (por exemplo, Parquet ou JSON Lines) com uma estrutura utilizável (por exemplo, campos bem definidos para treinamento e avaliação).

Usando dlt

dlt é uma biblioteca Python de código aberto para movimentação de dados (ETL) e é útil para desenvolvedores (e seus agentes) que constroem pipelines de dados. Ela pode ingerir dados de diversos tipos de origem:

• Armazenamento em nuvem ou arquivos
• APIs REST
• Bancos de dados SQL
• Geradores em Python

Exemplos de tipos de origem:

• filesystem (inclui s3, gs, az, abff, etc.)
• sql_database, mongodb, google_sheets
• notion, hubspot, rest_api

Encontre o tipo da sua fonte na lista de fontes e crie seu projeto dlt:

dlt init <source-type> filesystem

Em seguida, você pode criar um arquivo de configuração .dlt/secrets.toml na raiz do seu projeto dlt para definir o Hub como um destino de sistema de arquivos para seus conjuntos de dados, com base no protocolo hf://:

[destination.filesystem]
bucket_url = "hf://datasets/<namespace>"

[destination.filesystem.credentials]
hf_token = "hf_..."  # Your Hugging Face Access Token

O namespace deve ser seu nome de usuário ou o nome da sua organização/equipe onde você deseja ingerir seu conjunto de dados.

Em seguida, cada dataset dlt cria ou atualiza um repositório de dataset do Hugging Face. O nome do repositório é <namespace>/<dataset_name>, onde <namespace> é o mesmo que você usou no bucket_url (sua organização ou equipe) e <dataset_name> é o dataset_name do pipeline.

Aqui está um exemplo de pipeline:

import dlt

@dlt.resource
def my_data():
    # One of the functions auto-generated by `dlt init` that you can customize,
    # or you can define your own python generator function.

    # Here is an example from the `chess` source type:
    for player in ['magnuscarlsen', 'rpragchess']:
        response = requests.get(f'https://api.chess.com/pub/player/{player}')
        response.raise_for_status()
        yield response.json()

# Requires bucket_url = "hf://datasets/<namespace>" in .dlt/secrets.toml
pipeline = dlt.pipeline(
    pipeline_name="my_pipeline",
    destination="filesystem",
    dataset_name="dataset_name",
)

pipeline.run(my_data())

Personalize o recurso dlt para carregar os dados que você deseja e analisar os campos que você deseja publicar no seu conjunto de dados, por exemplo, o texto necessário para treinamento e avaliação.

Usando outras bibliotecas

Algumas bibliotecas, como 🤗 Datasets, Pandas, Polars, Dask, DuckDB, Spark ou Daft, podem ingerir dados de diversos locais para o Hub. Consulte a lista de Libraries supported by the Datasets Hub para mais informações.

Ingerir dados brutos

Se você está ingerindo dados brutos que precisam de mais curadoria antes de serem publicados como datasets prontos para IA, ou se precisa de uma experiência semelhante à do S3, considere ingeri-los em Hugging Face Storage Buckets. Para mover uma coleção existente grande para um bucket a partir do disco local ou de outra nuvem, consulte o Migration Guide.

Se seus dados já estão em um repositório de dataset, modelo ou Space, você pode copiá-los para um bucket no servidor — sem download ou reenvio — com hf buckets cp:

hf cp hf://datasets/username/my-dataset/ hf://buckets/username/my-bucket/

Apenas os hashes de conteúdo Xet são migrados, portanto, mesmo arquivos muito grandes são copiados instantaneamente. Consulte Copiar arquivos entre repositórios e buckets.

Ingestão agendada

Existem algumas limitações ao atualizar o mesmo arquivo no Hub milhares de vezes. Por exemplo, você pode querer ingerir gerações de um servidor de inferência de LLM em execução, rastreamentos de agentes ao vivo ou logs de um treinamento de modelo em andamento. Nesses casos, fazer o upload dos dados como um dataset no Hub faz sentido, mas pode ser difícil de fazer corretamente. O principal motivo é que você não quer versionar cada atualização dos seus dados, pois isso tornaria o repositório git inutilizável.

Três opções estão disponíveis:

• Use um Storage Bucket em vez de um repositório de Dataset: os Storage Buckets oferecem uma experiência semelhante à do S3 que permite atualizar arquivos com muita frequência, pois não são baseados em git. Os Storage Buckets são especialmente úteis para dados que ainda não estão prontos para serem publicados como um dataset, por exemplo, dados que ainda estão em evolução ou que precisam de mais curadoria.
• Use um CommitScheduler: O CommitScheduler em huggingface_hub oferece ingestão em tempo quase real para manter o histórico git de um repositório de Dataset gerenciável. Ele pode ser configurado para fazer commits git em intervalos definidos em minutos.
• Use Hugging Face Jobs para agendar scripts de ingestão: Hugging Face Jobs oferece uma maneira de executar e agendar scripts python na infraestrutura do Hugging Face. Agende scripts de ingestão para serem executados em intervalos definidos usando a sintaxe Cron.

Alta frequência usando Storage Buckets

Ao contrário dos repositórios de Dataset baseados em git, você pode atualizar arquivos em Storage Buckets em uma taxa muito alta, oferecendo ingestão quase em tempo real.

Use batch_bucket_files() em huggingface_hub para atualizar arquivos em um bucket:

from huggingface_hub import batch_bucket_files

def update_bucket(local_files):
    destinations = [os.path.basename(local_file) for local_file in local_file]
    batch_bucket_files(bucket_id="username/bucket_name", add=[(local_file, dst) for local_file, dst in zip(local_files, destinations)])

Alternativamente, você pode adicionar a arquivos em um Bucket e flush() a cada novo item:

from huggingface_hub import hffs

with hffs.open("buckets/username/bucket_name/texts.jsonl", "a") as f:
    for text in live_texts_stream:
        f.write(json.dumps({"text": text}) + "\n")
        f.flush()

The HfFileSystem is based on fsspec which has a default blocksize of 5MiB, which means flushing actually uploads the data once a full chunk of 5MiB of new data was appended. If you want to upload more often, lower blocksize in hffs.open() (e.g. hffs.open(..., blocksize=100 * 2 ** 10) for 100 kiB) or use f.flush(force=True).

O armazenamento do Hugging Face é baseado no Xet, que permite I/O eficiente ao anexar dados a arquivos: os uploads são deduplicados e apenas os novos dados são enviados. Encontre mais informações sobre ingestão dinâmica de dados em buckets na documentação de buckets sobre uploads e na documentação de edição de datasets.

Quase em tempo real usando um CommitScheduler

A ideia é executar um job em segundo plano que regularmente faz push de uma pasta local para o Hub. Você deseja salvar dados no Hub (potencialmente milhões de entradas), mas não precisa salvar em tempo real a entrada de cada usuário. Em vez disso, você pode salvar os dados localmente em um arquivo JSON e enviá-los a cada 10 minutos. Por exemplo:

import json
from huggingface_hub import CommitScheduler

folder_path = "path/to/files/to/ingest"
every = 10  # ingest every 10min

with CommitScheduler(repo_id="username/dataset_name", repo_type="dataset", folder_path=folder_path, every=every) as scheduler:
    # Write to the folder to ingest every 10min
    # For example:
    with open(folder_path + "/texts.jsonl", "a") as f:
        f.write(json.dumps({"text": text}) + "\n")
    ...

Confira como ingerir dados dinâmicos sem precisar reenviar tudo a cada vez na documentação sobre edição de datasets.

Encontre mais informações sobre uploads agendados na documentação do huggingface_hub.

Baseado em cron usando Hugging Face Jobs

Agende scripts em Python para ingerir dados de acordo com um cronograma

Por exemplo, para executar o script ingest.py a cada 5 minutos:

hf jobs scheduled uv run "*/5 * * * *" ingest.py

Declare as dependências do script no cabeçalho do script ou use --with. Por exemplo, para executar um pipeline dlt todos os dias à meia-noite:

hf jobs scheduled uv run --with "dlt[hf]" "0 0 * * *" pipeline.py

Você pode verificar os logs de cada execução usando hf jobs logs ou diretamente na página de Jobs da sua conta no Hugging Face.

Encontre mais informações sobre Hugging Face Jobs na documentação de Jobs.