Bibliothèques

Le Hub Datasets prend en charge plusieurs bibliothèques de l'écosystème Open Source. Grâce à la bibliothèque Python huggingface_hub, il est facile d'activer le partage de vos jeux de données sur le Hub. Nous sommes ravis d'accueillir sur le Hub un ensemble de bibliothèques Open Source qui font progresser le Machine Learning.

Table des bibliothèques

Le tableau ci-dessous résume les bibliothèques prises en charge et leur niveau d'intégration.

* Nécessite de passer des arguments supplémentaires pour écrire des fichiers Parquet optimisés

Bibliothèques de traitement de données

Streaming

Le streaming de jeu de données permet d’itérer progressivement sur un jeu de données de Hugging Face sans avoir à le télécharger entièrement. Il économise de l’espace disque local car les données ne sont jamais écrites sur le disque. Il économise de la mémoire car seule une petite partie du jeu de données est utilisée à la fois. Et il fait gagner du temps, car il n’est pas nécessaire de télécharger les données avant la charge de travail du CPU ou du GPU.

En plus du streaming depuis Hugging Face, de nombreuses bibliothèques prennent également en charge le streaming vers Hugging Face. Elles peuvent donc exécuter des pipelines de streaming de bout en bout : streaming depuis une source et écriture progressive vers Hugging Face, en superposant souvent les étapes de téléchargement, de téléversement et de traitement.

Pour plus de détails sur la manière de réaliser du streaming, consultez la documentation d'une bibliothèque qui prend en charge le streaming (voir le tableau ci-dessus) ou la documentation des jeux de données en streaming si vous souhaitez streamer vous-même des jeux de données depuis Hugging Face.

Fichiers Parquet optimisés

Les fichiers Parquet sur Hugging Face sont optimisés pour améliorer l’efficacité du stockage, accélérer les téléchargements et les téléversements, et permettre un streaming et une édition efficaces des jeux de données.

Les fichiers Parquet optimisés sont des fichiers Parquet dotés de fonctionnalités supplémentaires :

• Parquet Content Defined Chunking optimise Parquet pour Xet, le backend de stockage de Hugging Face. Il accélère les téléversements et les téléchargements grâce à la déduplication par chunks et permet une édition efficace des fichiers
• L'index de page accélère les filtres lors du streaming et permet un accès aléatoire efficace, par exemple dans le Dataset Viewer

Certaines bibliothèques nécessitent un argument supplémentaire pour écrire des fichiers Parquet optimisés, comme Pandas et PyArrow :

• use_content_defined_chunking=True pour activer le Parquet Content Defined Chunking, pour la déduplication et l'édition
• write_page_index=True pour inclure un index de pages dans les métadonnées Parquet, pour le streaming et l'accès aléatoire

Bibliothèques d'entraînement

Bibliothèques d’entraînement qui s’intègrent aux jeux de données du Hub pour l’entraînement de modèles. Le tableau ci-dessous présente leurs capacités de streaming, c’est-à-dire la possibilité d’entraîner sur des jeux de données sans les télécharger au préalable.

* SFTTrainer et DPOTrainer prennent en charge le streaming ; GRPOTrainer ne prend pas encore en charge l’entrée en streaming

Streaming depuis le Hub

Le streaming permet d'entraîner sur des jeux de données massifs sans les télécharger au préalable. C'est précieux lorsque :

• Votre jeu de données est trop volumineux pour tenir sur le disque
• Vous souhaitez commencer l'entraînement immédiatement
• Vous utilisez HF Jobs où le calcul co-localisé offre un streaming plus rapide

Les récentes améliorations ont rendu le streaming jusqu'à 100 fois plus efficace, avec un démarrage plus rapide, un préchargement optimisé et une meilleure scalabilité sur de nombreux workers.

Remarque : Le streaming nécessite max_steps dans les arguments d'entraînement, car la longueur du jeu de données est inconnue, et utilise un mélange basé sur des tampons. Consultez les jeux de données en streaming pour plus de détails.

Journalisation sur le Hub

Certains outils peuvent diffuser les données d’entraînement vers le Hub pendant l’entraînement :

• Trackio : Transmet les métriques d’entraînement à un jeu de données du Hub en temps réel

Intégration des bibliothèques et outils de données avec le Hub

Ce guide s’adresse aux développeurs et mainteneurs de bibliothèques et d’outils de données souhaitant s’intégrer au Hugging Face Hub. Que vous développiez une bibliothèque de traitement de données, un outil d’analyse ou tout logiciel devant interagir avec des jeux de données, cette documentation vous aidera à implémenter une intégration avec le Hub.

Le guide couvre :

• Approches possibles pour charger des données depuis le Hub dans votre bibliothèque/outil
• Approches possibles pour téléverser des données de votre bibliothèque/outil vers le Hub

Chargement des données depuis le Hub

Si vous disposez d'une bibliothèque pour manipuler des données, il peut être utile pour vos utilisateurs de charger des données depuis le Hub.

En général, nous vous recommandons de vous appuyer sur une bibliothèque existante comme datasets, pandas ou polars pour effectuer cette tâche, à moins que vous n’ayez une raison spécifique d’implémenter votre propre solution. Si vous avez besoin d’un contrôle plus fin sur le processus de chargement, vous pouvez utiliser la bibliothèque huggingface_hub, qui vous permettra, par exemple, de télécharger un sous-ensemble spécifique de fichiers d’un dépôt.

Vous trouverez plus d’informations sur le chargement de données depuis le Hub ici.

Intégration via le Dataset Viewer et les fichiers Parquet

Le visualiseur de jeux de données du Hub et le système de conversion en Parquet offrent une méthode standardisée pour intégrer les jeux de données, quel que soit leur format d’origine. Cette infrastructure constitue une couche d’intégration fiable entre le Hub et les bibliothèques externes.

Si le jeu de données n'est pas déjà au format Parquet, le Hub convertit automatiquement les 5 Go initiaux de chaque jeu de données au format Parquet pour alimenter le visualiseur de jeux de données et offrir des schémas d'accès cohérents. Cette normalisation présente plusieurs avantages pour les intégrations de bibliothèques :

• Des modèles d'accès aux données cohérents, quel que soit le format d'origine
• Aperçu et exploration intégrés des jeux de données via le visualiseur de jeux de données du Hub. Le visualiseur de jeux de données peut également être intégré en tant qu’iframe dans vos applications, ce qui facilite la fourniture d’aperçus riches des jeux de données. Pour plus d’informations sur l’intégration du visualiseur, consultez la documentation sur l’intégration du visualiseur de jeux de données.
• Stockage en colonnes efficace, optimisé pour les requêtes. Par exemple, vous pouvez utiliser un outil comme DuckDB pour interroger ou filtrer un sous-ensemble spécifique de données.
• Parquet est bien pris en charge dans tout l'écosystème de l'apprentissage automatique et de la science des données.

Pour plus de détails sur le travail avec l'API du Dataset Viewer, consultez la documentation de l'API du Dataset Viewer

Téléchargement de données sur le Hub

Cette section aborde les approches possibles pour ajouter la capacité de téléverser des données sur le Hub dans votre bibliothèque, c'est-à-dire comment implémenter une méthode push_to_hub.

Ce guide abordera trois principales méthodes pour téléverser des données sur le Hub :

• à l'aide de la bibliothèque datasets et de la méthode push_to_hub
• utiliser pandas pour écrire sur le Hub
• à l'aide de la bibliothèque huggingface_hub et de la méthode upload_folder

Utiliser la bibliothèque datasets

L’approche la plus simple pour envoyer des données sur le Hub consiste à s’appuyer sur la méthode existante push_to_hub de la bibliothèque datasets. La méthode push_to_hub gère automatiquement :

• la création du dépôt
• la conversion du jeu de données au format Parquet
• découper le jeu de données en parties adaptées
• téléchargement des données

Par exemple, si vous disposez d'une bibliothèque de génération de données synthétiques qui renvoie une liste de dictionnaires, vous pouvez simplement faire ce qui suit :

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

Exemples de ce type d'intégration :

• Distilabel

S'appuyer sur l'intégration existante d'une bibliothèque avec le Hub

Polars, Pandas, Dask, Spark, DuckDB et Daft peuvent tous écrire dans un dépôt du Hugging Face Hub. Consultez le tableau des bibliothèques ci-dessus pour plus de détails.

Si vous utilisez déjà l’une de ces bibliothèques dans votre code, ajouter la possibilité de pousser sur le Hub est simple. Par exemple, si vous disposez d’une bibliothèque de génération de données synthétiques capable de retourner un DataFrame Pandas, voici le code à écrire pour le 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")

Utilisation de la bibliothèque Python huggingface_hub

La bibliothèque Python huggingface_hub propose une approche plus flexible pour téléverser des données sur le Hub. La bibliothèque vous permet de téléverser des fichiers spécifiques ou des sous-ensembles de fichiers vers un dépôt. Cela est utile si vous disposez d’un grand jeu de données que vous ne souhaitez pas convertir en Parquet, si vous voulez téléverser un sous-ensemble spécifique de fichiers, ou si vous souhaitez un meilleur contrôle sur la structure du dépôt.

Selon votre cas d'usage, vous pouvez téléverser un fichier ou un dossier à un point précis de votre code, c'est-à-dire exporter des annotations depuis un outil vers le Hub lorsqu'un utilisateur clique sur « push to Hub ». Par exemple,

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

Vous trouverez plus d'informations sur les méthodes pour téléverser des données sur le Hub ici.

Sinon, il existe des situations où vous souhaitez peut-être téléverser des données en arrière-plan, par exemple des données synthétiques générées toutes les 10 minutes. Dans ce cas, vous pouvez utiliser la classe CommitScheduler de la bibliothèque huggingface_hub. Pour plus de détails, consultez la documentation sur les téléversements planifiés.

Vous pouvez voir un exemple d'utilisation de cette approche pour téléverser des données sur le Hub dans

• La bibliothèque fastdata
• Cet espace de démonstration magpie

Plus de support

Pour toute question technique concernant l'intégration, n'hésitez pas à contacter l'équipe datasets à datasets@huggingface.co.