Ingestion de jeux de données

Les données sont généralement stockées dans des bases de données ou des espaces de stockage cloud sous des formats inadaptés aux flux de travail IA. L’ingestion de données dans le Hub est une bonne façon de les publier sous forme de jeux de données prêts pour l’IA, permettant un chargement, un traitement et un entraînement et une évaluation des modèles faciles et efficaces.

Avec huggingface_hub

La manière la plus simple d'ingérer des données consiste à téléverser les fichiers de données à l'aide de huggingface_hub.

La bibliothèque Python huggingface_hub offre un ensemble de fonctionnalités riche qui vous permet de gérer des dépôts, y compris la création de dépôts et le téléversement de jeux de données sur le Hub. Consultez la documentation de la bibliothèque client pour en savoir plus.

Ceci est pertinent si vos données sont statiques/gelées et si vous pouvez facilement obtenir un déchargement local des données dans un format pris en charge par le Hub (par exemple, Parquet ou JSON Lines) avec une structure exploitable (par exemple, des champs bien définis pour l’entraînement et l’évaluation).

Utilisation de dlt

dlt est une bibliothèque Python open source pour le mouvement de données (ETL), utile aux développeurs (et à leurs agents) qui construisent des pipelines de données. Elle peut ingérer des données à partir de divers types de sources :

• Stockage cloud ou fichiers
• API REST
• Bases de données SQL
• Générateurs Python

Exemples de types de source :

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

Trouvez votre type de source dans la liste des sources et créez votre projet dlt :

dlt init <source-type> filesystem

Vous pouvez ensuite créer un fichier de configuration .dlt/secrets.toml à la racine de votre projet dlt pour définir le Hub comme destination système de fichiers pour vos jeux de données, basé sur le protocole hf:// :

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

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

L'espace de noms doit être votre nom d'utilisateur ou le nom de votre organisation/équipe où vous souhaitez ingérer votre jeu de données.

Chaque jeu de données dlt crée ou met à jour un dépôt de jeu de données Hugging Face. Le nom du dépôt est <namespace>/<dataset_name>, où <namespace> est le même que celui utilisé dans bucket_url (votre organisation ou votre équipe), et <dataset_name> est le dataset_name du pipeline.

Voici un exemple 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())

Personnalisez la ressource dlt pour charger les données souhaitées et analyser les champs que vous souhaitez publier dans votre jeu de données, par exemple le texte nécessaire pour l’entraînement et l’évaluation.

Utiliser d'autres bibliothèques

Certaines bibliothèques comme 🤗 Datasets, Pandas, Polars, Dask, DuckDB, Spark ou Daft peuvent ingérer des données depuis diverses sources vers le Hub. Consultez la liste des bibliothèques prises en charge par le Datasets Hub pour plus d’informations.

Ingestion de données brutes

Si vous ingérez des données brutes qui nécessitent une curation supplémentaire avant d’être publiées sous forme de jeux de données prêts pour l’IA, ou si vous avez besoin d’une expérience similaire à S3, envisagez de les ingérer dans des bacs de stockage Hugging Face. Pour déplacer un ensemble existant de grande taille vers un bac depuis le disque local ou un autre cloud, consultez le guide de migration.

Si vos données sont déjà dans un dépôt de jeu de données, de modèle ou de Space, vous pouvez les copier dans un bucket côté serveur — sans téléchargement ni réenvoi — avec hf buckets cp :

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

Seuls les hachages de contenu Xet sont migrés, de sorte que même les fichiers très volumineux sont copiés instantanément. Consultez Copier des fichiers entre dépôts et buckets.

Ingestion planifiée

Il existe certaines limites lors de la mise à jour du même fichier sur le Hub des milliers de fois. Par exemple, vous pourriez vouloir ingérer les générations d’un serveur d’inférence LLM en cours d’exécution, les traces d’agents en direct, ou les journaux d’un entraînement de modèle en cours. Dans de tels cas, il est pertinent de téléverser les données en tant que jeu de données sur le Hub, mais cela peut s’avérer difficile à faire correctement. La raison principale est que vous ne souhaitez pas versionner chaque mise à jour de vos données, car cela rendrait le dépôt git inutilisable.

Trois options sont disponibles :

• Utiliser un Storage Bucket plutôt qu’un dépôt de Dataset : les Storage Buckets offrent une expérience de type S3 permettant de mettre à jour les fichiers très fréquemment, car ils ne sont pas basés sur git. Les Storage Buckets sont particulièrement utiles pour des données pas encore prêtes à être publiées en tant que dataset, par exemple des données encore en évolution ou nécessitant davantage de curation.
• Utiliser un CommitScheduler : le CommitScheduler de huggingface_hub offre une ingestion quasi en temps réel pour garder l’historique git d’un dépôt de Dataset maîtrisable. Il peut être configuré pour effectuer des commits git à des intervalles définis en minutes.
• Utiliser Hugging Face Jobs pour planifier des scripts d'ingestion : Hugging Face Jobs permet d'exécuter et de planifier des scripts Python sur l'infrastructure Hugging Face. Planifiez l'exécution des scripts d'ingestion à des intervalles définis à l'aide de la syntaxe Cron.

Fréquence élevée à l'aide de Storage Buckets

Contrairement aux dépôts de Dataset basés sur git, vous pouvez mettre à jour les fichiers sur les Storage Buckets à un taux très élevé, offrant une ingestion quasi en temps réel.

Utilisez batch_bucket_files() dans huggingface_hub pour mettre à jour les fichiers d’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)])

Sinon, vous pouvez ajouter des éléments à des fichiers dans un Bucket et flush() à chaque nouvel élément :

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

Le stockage Hugging Face est basé sur Xet, ce qui permet une I/O efficace lors de l’ajout de données à des fichiers : les téléversements sont dédupliqués et seules les nouvelles données sont téléversées. Retrouvez plus d’informations sur l’ingestion dynamique de données dans les buckets dans la documentation des buckets sur les téléversements et dans la documentation sur l’édition des jeux de données.

Quasi temps réel à l'aide d'un CommitScheduler

L’idée est d’exécuter une tâche en arrière-plan qui pousse régulièrement un dossier local vers le Hub. Vous souhaitez enregistrer des données sur le Hub (potentiellement des millions d’entrées), mais vous n’avez pas besoin d’enregistrer en temps réel chaque saisie utilisateur. Vous pouvez plutôt enregistrer les données localement dans un fichier JSON et les téléverser toutes les 10 minutes. Par exemple :

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

Découvrez comment ingérer des données dynamiques sans avoir à tout réenvoyer à chaque fois dans la documentation sur l'édition de jeux de données.

Retrouvez plus d'informations sur les téléversements planifiés dans la documentation de huggingface_hub.

Basé sur Cron à l'aide de Hugging Face Jobs

Planifier des scripts Python pour ingérer des données selon un calendrier

Par exemple, pour exécuter le script ingest.py toutes les 5 minutes :

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

Déclarez les dépendances du script dans l’en-tête du script ou utilisez --with. Par exemple, pour exécuter un pipeline dlt chaque jour à minuit :

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

Vous pouvez consulter les journaux de chaque exécution à l’aide de hf jobs logs ou directement sur la page Jobs de votre compte sur Hugging Face.

Retrouvez plus d'informations sur les Hugging Face Jobs dans la documentation des Jobs.