Ingesta de conjuntos de datos

Los datos suelen residir en bases de datos o en almacenamiento en la nube en formatos que no son adecuados para flujos de trabajo de IA. Ingresar datos en el Hub es una buena manera de publicarlos como conjuntos de datos listos para IA, lo que permite una carga, un procesamiento y un entrenamiento y evaluación de modelos fáciles y eficientes.

Usando huggingface_hub

La forma más sencilla de importar datos es simplemente subir los archivos de datos con huggingface_hub.

La biblioteca de Python huggingface_hub ofrece un conjunto de funciones completo que te permite gestionar repositorios, incluida la creación de repos y la carga de conjuntos de datos en el Hub. Consulta la documentación de la biblioteca de cliente para obtener más información.

Esto es relevante si tus datos son estáticos/congelados y si puedes obtener fácilmente un volcado local de los datos en un formato compatible con el Hub (p. ej., Parquet o JSON Lines) con una estructura utilizable (p. ej., campos bien definidos para el entrenamiento y la evaluación).

Usando dlt

dlt es una biblioteca de Python de código abierto para el movimiento de datos (ETL) y resulta útil para los desarrolladores (y sus agentes) que construyen pipelines de datos. Puede ingerir datos de diversos tipos de origen:

• Almacenamiento en la nube o archivos
• APIs REST
• Bases de datos SQL
• Generadores de Python

Ejemplos de tipos de origen:

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

Encuentra tu tipo de origen en la lista de orígenes y crea tu proyecto de dlt:

dlt init <source-type> filesystem

A continuación, puede crear un archivo de configuración .dlt/secrets.toml en la raíz de su proyecto de dlt para definir el Hub como un destino de sistema de archivos para sus conjuntos de datos, basado en el protocolo hf://:

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

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

El espacio de nombres debe ser tu nombre de usuario o el nombre de tu organización/equipo donde deseas ingerir tu conjunto de datos.

Luego, cada conjunto de datos de dlt crea o actualiza un repositorio de conjuntos de datos de Hugging Face. El nombre del repositorio es <namespace>/<dataset_name>, donde <namespace> es el mismo que usaste en bucket_url (tu organización o equipo) y <dataset_name> es el dataset_name del pipeline.

Aquí hay un ejemplo 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())

Personaliza el recurso dlt para cargar los datos que desees y analizar los campos que quieras publicar en tu conjunto de datos, por ejemplo, el texto que necesitas para el entrenamiento y la evaluación.

Uso de otras bibliotecas

Algunas bibliotecas como 🤗 Datasets, Pandas, Polars, Dask, DuckDB, Spark o Daft pueden importar datos de diversos lugares al Hub. Consulta la lista de Libraries supported by the Datasets Hub para obtener más información.

Ingestar datos sin procesar

Si está ingiriendo datos crudos que requieren una curaduría adicional antes de publicarse como conjuntos de datos listos para IA, o si necesita una experiencia similar a S3, considere ingirirlos en Hugging Face Storage Buckets. Para mover una colección existente de gran tamaño a un bucket desde el disco local u otra nube, consulte la Migration Guide.

Si tus datos ya se encuentran en un repositorio de dataset, modelo o Space, puedes copiarlos a un bucket en el servidor — sin necesidad de descargarlos ni volver a subirlos — con hf buckets cp:

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

Solo se migran los hashes de contenido de Xet, por lo que incluso los archivos muy grandes se copian al instante. Consulte Copiar archivos entre repositorios y cubos.

Ingesta programada

Existen algunas limitaciones al actualizar el mismo archivo en el Hub miles de veces. Por ejemplo, es posible que desees incorporar las generaciones de un servidor de inferencia de LLM en ejecución, las trazas de agentes en vivo o los registros de un entrenamiento de modelo en curso. En tales casos, tiene sentido subir los datos como un conjunto de datos en el Hub, pero puede ser difícil hacerlo correctamente. La razón principal es que no deseas versionar cada actualización de tus datos, ya que haría que el repositorio de git fuera inutilizable.

Hay tres opciones disponibles:

• Usar un Storage Bucket en lugar de un repositorio de Dataset: los Storage Buckets ofrecen una experiencia similar a S3 que permite actualizar archivos con mucha frecuencia, ya que no se basan en git. Los Storage Buckets son especialmente útiles para datos que no están listos para publicarse como un dataset, por ejemplo, datos que aún están evolucionando o que necesitan más curaduría.
• Usar un CommitScheduler: El CommitScheduler de huggingface_hub ofrece ingestión casi en tiempo real para mantener el historial de git de un repositorio de Dataset manejable. Se puede configurar para realizar commits de git a intervalos definidos en minutos.
• Use Hugging Face Jobs to schedule ingestion scripts: Hugging Face Jobs ofrece una forma de ejecutar y programar scripts de Python en la infraestructura de Hugging Face. Programe los scripts de ingesta para que se ejecuten en intervalos definidos mediante la sintaxis Cron.

Alta frecuencia usando Storage Buckets

A diferencia de los repositorios de Dataset basados en git, puedes actualizar archivos en los Storage Buckets a una tasa muy alta, lo que ofrece una ingesta casi en tiempo real.

Use batch_bucket_files() en huggingface_hub para actualizar archivos en un 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, puede agregar a archivos en un Bucket y flush() en cada nuevo elemento:

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

El HfFileSystem se basa en fsspec, que tiene un blocksize predeterminado de 5 MiB, lo que significa que la descarga en realidad sube los datos una vez que se ha añadido un bloque completo de 5 MiB de datos nuevos. Si desea subir con más frecuencia, reduzca blocksize en hffs.open() (por ejemplo, hffs.open(..., blocksize=100 * 2 ** 10) para 100 kiB) o use f.flush(force=True).

El almacenamiento de Hugging Face se basa en Xet, lo que permite una entrada/salida eficiente al agregar datos a archivos: las cargas se deduplican y solo se suben los datos nuevos. Encuentra más información sobre la ingesta dinámica de datos en los buckets en la documentación de buckets sobre cargas y en la documentación de edición de datasets.

Casi en tiempo real usando un CommitScheduler

La idea es ejecutar una tarea en segundo plano que suba periódicamente una carpeta local al Hub. Desea guardar datos en el Hub (posiblemente millones de entradas), pero no necesita guardar en tiempo real la entrada de cada usuario. En su lugar, puede guardar los datos localmente en un archivo JSON y subirlos cada 10 minutos. Por ejemplo:

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")
    ...

Consulte en la documentación sobre edición de conjuntos de datos cómo ingerir datos dinámicos sin tener que volver a subir todo cada vez.

Encuentra más información sobre las cargas programadas en la documentación de huggingface_hub.

Basado en cron con Hugging Face Jobs

Programar scripts de Python para ingerir datos según un horario

Por ejemplo, para ejecutar un script ingest.py cada 5 minutos:

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

Declarar las dependencias del script en la cabecera del script o usar --with. Por ejemplo, para ejecutar un pipeline de dlt cada día a medianoche:

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

Puedes consultar los registros de cada ejecución con hf jobs logs o directamente en la página de Jobs de tu cuenta en Hugging Face.

Encuentra más información sobre Hugging Face Jobs en la documentación de Jobs.