Hugging Face Datasets : Référence pour les développeurs

Un jeu de données Hugging Face est une collection structurée et versionnée de données stockée sur le Hub Hugging Face et consommée via la bibliothèque Python datasets . Chaque jeu de données expose un ou plusieurssous-ensembles (généralement train, validation et test), un schéma typé décrivant chaque colonne, ainsi que des métadonnées couvrant la licence, la catégorie de tâche et les étiquettes linguistiques. La bibliothèque gère le téléchargement, la mise en cache et la conversion de format, de sorte que vous n’avez presque jamais à manipuler directement les fichiers bruts.caractéristiques schéma décrivant chaque colonne, ainsi que des métadonnées couvrant la licence, la catégorie de tâche et les étiquettes linguistiques. La bibliothèque gère le téléchargement, la mise en cache et la conversion de format, de sorte que vous n’avez presque jamais à manipuler directement les fichiers bruts.

Rechercher des jeux de données sur le Hub

L’interface principale de découverte est huggingface.co/datasets. Les filtres disponibles dans l’interface utilisateur sont les suivants :

• Tâche — classification de texte, réponse aux questions, segmentation d’images, traduction, résumé, etc.
• Langue — codes ISO 639-1 (en, zh, fr, de, …)
• Licence — Apache 2.0, MIT, CC-BY, CC0, OpenRAIL, etc.
• Catégorie de taille — moins de 1 000 lignes jusqu’à plus d’un milliard de lignes
• Modalité — texte, image, audio, vidéo, données tabulaires, multimodal

Vous pouvez également effectuer des recherches par programmation à l’aide du client Python du Hub :

from huggingface_hub import list_datasets

results = list_datasets(filter='task_categories:text-classification', limit=20)
for ds in results:
    print(ds.id, ds.downloads)

L’API REST du serveur Datasets expose un point de terminaison /valid qui liste tous les jeux de données disposant d’exportations précalculées au format Parquet, permettant ainsi des aperçus rapides et des échantillons de lignes sans télécharger l’intégralité du jeu de données.

Installation

Ledatasets La bibliothèque fonctionne sous Python 3.8+ et est indépendante de la plateforme.

pip install datasets

Pour prendre en charge les images et l’audio, installez les modules complémentaires appropriés :

pip install datasets[vision]# Pillow
pip install datasets    # librosa, soundfile

Pour vous authentifier afin d’accéder à des jeux de données privés ou de publier des données sur le Hub :

pip install huggingface_hub
huggingface-cli login          # demande votre jeton d’accès HF

Votre jeton est stocké dans ~/.cache/huggingface/token sur macOS/Linux, ou dans %USERPROFILE%.cachehuggingfacetoken sous Windows. Vous pouvez aussi définir directement la variable d’environnement HF_TOKEN .

Charger un jeu de données

Le point d’entrée principal est load_dataset(). En l’absence d’argumentsplit , celle-ci renvoie un objet DatasetDict contenant tous les sous-ensembles disponibles :

from datasets import load_dataset

ds = load_dataset('stanfordnlp/imdb')
print(ds)
# DatasetDict({
#     train: Dataset({features: ['text', 'label'], num_rows: 25000})
#     test:  Dataset({features: ['text', 'label'], num_rows: 25000})
# })

train = ds['train']
print(train.features)
# {'text': Value(dtype='string'), 'label': ClassLabel(names=['neg', 'pos'])}

print(train[0]['text'][:120])

Chargement d'une seule partition

train = load_dataset('stanfordnlp/imdb', split='train')
# Renvoie directement un Dataset, pas un DatasetDict

Chargement d'une configuration nommée

De nombreux jeux de données définissent des configurations nommées pour les variantes linguistiques, les sous-ensembles thématiques ou les versions du schéma. Passez le nom de la configuration comme deuxième argument positionnel :

ds = load_dataset('Helsinki-NLP/opus_books', 'en-fr')

Pour lister toutes les configurations disponibles d’un jeu de données avant son chargement :

from datasets import get_dataset_config_names
print(get_dataset_config_names('Helsinki-NLP/opus_books'))

Chargement à partir de fichiers locaux

Spécifiez plutôt qu’un identifiant de jeu de données sur le Hub un nom de format et un chemin de fichier. Les formats pris en charge incluent CSV, JSON/JSONL, Parquet, Arrow, texte brut, ainsi que les conventions ImageFolder/AudioFolder.

ds = load_dataset('csv', data_files='my_data.csv')
ds = load_dataset('json', data_files={'train': 'train.jsonl', 'test': 'test.jsonl'})
ds = load_dataset('imagefolder', data_dir='./photos/')

Structure d’un jeu de données : sous-ensembles et caractéristiques

Vérifiez quelles partitions contient un jeu de données avant de le charger :

from datasets import get_dataset_split_names
print(get_dataset_split_names('stanfordnlp/imdb'))
# ['train', 'test', 'unsupervised']

Lecaractéristiques Le dictionnaire associe les noms de colonnes à des descripteurs typés. Types de fonctionnalités courants :

Chargement différé (streaming) de jeux de données volumineux

Pour les jeux de données trop volumineux pour être téléchargés — Common Crawl, The Pile, LAION-5B — spécifiez streaming=True. Les données sont récupérées et décodées à la volée sans remplir votre disque dur :

ds = load_dataset('allenai/c4', 'en', split='train', streaming=True)

for example in ds.take(1000):
    print(example['text'][:80])

Le mode diffusion renvoie unIterableDataset plutôt qu’un Dataset. Il prend en charge.map(), .filter(), .shuffle(buffer_size=N), et .take(N), mais pas l’indexation aléatoire ni len(). Pour obtenir une tranche fixe sans diffuser l’intégralité du jeu de données :

ds = load_dataset('allenai/c4', 'en', split='train[:50000]')

La découpe des partitions accepte des nombres absolus de lignes ([:50000]), des pourcentages ([:10%]) et des plages avec pas ([10%:20%]).

Filtrage et traitement

Toutes les opérations s’exécutent dans Apache Arrow et utilisent le multiprocessus par défaut. Le résultat est mis en cache sur disque ; réexécuter la même opération sur les mêmes données renvoie immédiatement le cache. .map() # Filtrer les lignes short = train.filter(lambda x: len(x['text']) < 500)# Application par lots — bien plus rapide pour la tokenisation def tokenize(batch): return tokenizer(batch['text'], truncation=True, padding='max_length')tokenized = train.map(tokenize, batched=True, batch_size=256, num_proc=4)# Opérations sur les colonnes tokenized = tokenized.remove_columns(['text']) ds = ds.rename_column('label', 'labels')# Mélange et sélection ds = ds.shuffle(seed=42).select(range(10000))

# Filtrer les lignes
short = train.filter(lambda x: len(x['text']) < 500)

# Application par lots — bien plus rapide pour la tokenisation
def tokenize(batch):
    return tokenizer(batch['text'], truncation=True, padding='max_length')

tokenized = train.map(tokenize, batched=True, batch_size=256, num_proc=4)

# Opérations sur les colonnes
tokenized = tokenized.remove_columns(['text'])
ds = ds.rename_column('label', 'labels')

# Mélanger et sélectionner
ds = ds.shuffle(seed=42).select(range(10000))

Conversion vers d’autres formats

Publier votre propre jeu de données sur le Hub

Après exécution huggingface-cli login, poussez n’importe quelDataset ou DatasetDict objet directement :

from datasets import Dataset, DatasetDict
import pandas as pd

df = pd.read_csv('my_data.csv')
ds = Dataset.from_pandas(df)

ds.push_to_hub('votre-utilisateur/mon-jeu-de-donnees', private=False)

Pour pousser simultanément les sous-ensembles d’entraînement et de test :

split = ds.train_test_split(test_size=0.1)
DatasetDict({'train': split['train'], 'test': split['test']}).push_to_hub('votre-utilisateur/mon-jeu-de-donnees')

Le Hub stocke les jeux de données sous forme de fichiers Parquet fragmentés et génère automatiquement un visualiseur d’aperçu. Ajoutez une README.md fiche de jeu de données (Dataset Card) avec un en-tête YAML afin de rendre votre jeu de données filtrable par tâche, langue et licence dans l’interface de recherche du Hub.

Remarques relatives à la plateforme

Chemins du cache

Windows

Windows utilise la méthode de démarragespawn pour le traitement parallèle, ce qui exige que le point d’entrée de votre script soit placé à l’intérieur d’une structure if __name__ == '__main__': Sans cela,.map(num_proc=4) risque soit de bloquer indéfiniment, soit de déclencher une RuntimeError. Si vous exécutez le code dans un notebook Jupyter, utilisez soit num_proc=1 soit installez le packagemultiprocess aux côtés de datasets, que la bibliothèque privilégiera par rapport au module standard multiprocessing .

Espace disque

Les jeux de données volumineux (Common Crawl, RedPajama, LAION) occupent des centaines de gigaoctets une fois entièrement mis en cache. Utilisez streaming=True pour éviter les téléchargements. Pour afficher le contenu de votre cache, exécutez python -c "from datasets import inspect_dataset; print(inspect_dataset.__doc__)" ou explorez directement le répertoire du cache. Les jeux de données mis en cache sont stockés sous forme de fichiers Arrow organisés par nom et hachage du jeu de données ; supprimez manuellement les sous-dossiers pour libérer de l’espace.

Utiliser les jeux de données pour l’ajustement fin (fine-tuning) et l’évaluation

Le pipeline standard d’ajustement fin est le suivant : chargement du jeu de données → tokenisation via.map(batched=True) → définition du format sur 'torch' → transmission à un objetTrainer ou à une boucle d’entraînement personnalisée. La classe transformers de Hugging Face accepte directement un objet Trainer en tant qu’argument Dataset train_dataset et et eval_dataset .

Lors de l'évaluation des modèles sur des jeux de données de référence, le Classement des grands modèles linguistiques (LLM) fournit des scores sur des ensembles d'évaluation courants — une information utile pour déterminer quel jeu de données cibler dans le cadre de votre propre évaluation. Si vous hésitez entre l'ajustement fin et l'hébergement local d’un modèle ou l’appel à une API, le Calculateur de seuil de rentabilité entre hébergement local et utilisation d’une API peut modéliser le point de basculement des coûts en fonction du volume de requêtes. Pour connaître le coût brut par jeton d’une API selon les fournisseurs, utilisez le Calculateur de coûts d’API. Et si vous envisagez d’exécuter localement un modèle ajusté finement, la mémoire vidéo (VRAM) constitue la contrainte matérielle principale — le Calculateur de VRAM estime les besoins en mémoire GPU à partir de la taille du modèle et de la précision de la quantification.

Questions fréquemment posées

Quelle est la différence entre un Dataset et un DatasetDict ?

A Dataset est une seule partition — un tableau unique de lignes et de colonnes. Un DatasetDict est un conteneur semblable à un dictionnaire qui regroupe plusieurs partitions, et constitue le type de retour par défaut de load_dataset() lorsque vous omettez l’argument split . Accédez aux partitions individuelles à l’aide de leur clé : ds['train'], ds['test'], etc. Si vous spécifiezsplit='train', vous obtenez directement un objet Dataset brut.

Comment charger un jeu de données privé depuis le Hub ?

Authentifiez-vous d’abord avec huggingface-cli login, ou définissez la variable d’environnement HF_TOKEN sur votre jeton d’accès. Ensuite, appelez load_dataset('org/private-dataset', token=True). Le bloc Le paramètre doit être défini comme secret dans les pipelines CI/CD afin d’éviter l’étape interactive de connexion. HF_TOKEN Pourquoi load_dataset() prend-il tant de temps lors du premier appel ?

Le premier appel télécharge les fichiers bruts, les convertit au format Apache Arrow et écrit le cache sur le disque. Pour les jeux de données volumineux, cette opération peut prendre plusieurs minutes, voire davantage. Les appels ultérieurs sur la même machine récupèrent presque instantanément les fichiers Arrow mis en cache. Si vous disposez d’une connexion lente ou d’un espace disque limité, passez l’argument

pour traiter les données à la volée sans les mettre en cache localement. streaming=True Puis-je utiliser les jeux de données Hugging Face hors ligne ?

Oui. Une fois qu’un jeu de données est mis en cache, définissez la variable d’environnement

HF_DATASETS_OFFLINE=1 lit alors exclusivement le cache local, sans effectuer aucune requête réseau. Cette option est particulièrement utile pour les serveurs isolés (« air-gapped »), les exécutions hors ligne reproductibles ou les grappes HPC dont les nœuds de calcul n’ont pas accès à Internet mais partagent un système de fichiers réseau contenant le répertoire de cache. etload_dataset() Quel format de fichier le Hub utilise-t-il en interne ?

Les jeux de données hébergés sur le Hub sont servis sous forme de fichiers Apache Parquet, découpés en fragments (shards). La bibliothèque

télécharge ces fragments et les convertit en fichiers Apache Arrow ( datasets .arrow) pour la mise en cache locale. Vous pouvez contourner entièrement la bibliothèque et accéder directement aux fragments Parquet via le navigateur de fichiers du Hub ou à l’aide de la fonctionhuggingface_hub.hf_hub_download() Quelle taille peut atteindre un jeu de données Hugging Face ?.

Aucune limite de taille n’est imposée ; des jeux de données de plusieurs téraoctets existent déjà sur le Hub (par exemple, les paires image-texte LAION-5B ou d’importants extraits de Common Crawl). Pour les jeux de données supérieurs à quelques gigaoctets, le Hub stocke les données sous forme de multiples fragments Parquet plutôt que dans un seul fichier. Utilisez la fonctionnalité

dans la bibliothèque streaming=True pour travailler avec ces jeux de données sans les télécharger intégralement, ou téléchargez des fragments spécifiques à l’aide de l’argument datasets data_files . argument.