Passer au contenu principal
La bibliothèque Hugging Face Transformers simplifie l’utilisation de modèles NLP comme BERT et de techniques d’entraînement comme la précision mixte et le gradient checkpointing. L’intégration W&B ajoute le suivi des expériences et la gestion des versions des modèles à des tableaux de bord centralisés. Ce guide vous montre comment connecter le Trainer de Hugging Face à W&B. Vos run d’entraînement consigneront alors automatiquement les métriques, les points de contrôle du modèle et les sorties d’évaluation dans un tableau de bord centralisé. À la fin, vous serez en mesure de comparer les run, d’enregistrer et de recharger des points de contrôle du modèle depuis W&B Artifacts, et de personnaliser la journalisation pour vos propres flux de travail. Ce guide suppose que vous êtes déjà familiarisé avec l’entraînement de modèles à l’aide du Trainer de Hugging Face Transformers.

Démarrage rapide

tableau de bord Hugging Face
Si vous préférez passer directement à du code prêt à l’emploi, consultez ce Google Colab.

Premiers pas : suivre les expériences

Cette section explique comment vous authentifier auprès de W&B, installer la bibliothèque cliente, donner un nom à votre projet et activer la journalisation dans votre Trainer afin que votre premier run d’entraînement s’affiche dans le tableau de bord W&B.

Inscrivez-vous et créez une clé API

Une clé API permet d’authentifier votre machine auprès de W&B. Vous pouvez générer une clé API depuis votre profil.
Pour une méthode plus directe, accédez aux Paramètres utilisateur et créez une clé API. Copiez immédiatement la clé API et conservez-la dans un endroit sûr, par exemple dans un gestionnaire de mots de passe.
  1. Cliquez sur l’icône de votre profil dans le coin supérieur droit.
  2. Sélectionnez Paramètres utilisateur, puis faites défiler jusqu’à la section Clés API.

Installez la bibliothèque wandb et connectez-vous

Pour installer la bibliothèque wandb localement et vous connecter :
  1. Définissez la variable d’environnement WANDB_API_KEY sur votre clé API. Remplacez les valeurs entre <> par les vôtres :
  2. Installez la bibliothèque wandb et connectez-vous.
Si vous utilisez W&B pour la première fois, consultez le démarrage rapide.

Nommez le projet

Un projet W&B stocke tous les graphiques, les données et les modèles enregistrés à partir de runs liés. Donner un nom à votre projet vous aide à organiser votre travail et à regrouper au même endroit toutes les informations relatives à un même projet. Pour ajouter un run à un projet, définissez la variable d’environnement WANDB_PROJECT sur le nom de votre projet. Le WandbCallback récupère cette variable d’environnement de nom de projet et l’utilise lors de la configuration de votre run.
Assurez-vous de définir le nom du projet avant d’initialiser le Trainer.
Si vous ne spécifiez pas de nom de projet, le nom du projet est huggingface par défaut.

Enregistrez vos runs d’entraînement dans W&B

Lorsque vous définissez les arguments d’entraînement de votre Trainer, dans votre code ou en ligne de commande, définissez report_to sur "wandb" afin d’activer la journalisation avec W&B. Sans ce paramètre, le Trainer n’envoie aucune donnée à W&B. L’argument logging_steps dans TrainingArguments contrôle la fréquence à laquelle les métriques d’entraînement sont envoyées à W&B pendant l’entraînement. Vous pouvez aussi donner un nom au run d’entraînement dans W&B à l’aide de l’argument run_name. C’est tout. Désormais, vos modèles journalisent les pertes, les métriques d’évaluation, l’architecture du modèle et les gradients dans W&B pendant leur entraînement.
Vous utilisez TensorFlow ? Remplacez le Trainer de PyTorch par le TFTrainer de TensorFlow.

Activez l’enregistrement des points de contrôle du modèle

En plus de consigner des métriques, vous pouvez enregistrer les poids du modèle entraîné eux-mêmes dans W&B afin qu’ils puissent être versionnés, téléchargés et partagés au sein de votre équipe. Avec Artifacts, vous pouvez stocker gratuitement jusqu’à 100 Go de modèles et de jeux de données, puis utiliser le registre. Avec le registre, vous pouvez enregistrer des modèles pour les explorer et les évaluer, les préparer pour la préproduction ou les déployer dans votre environnement de production. Pour journaliser les points de contrôle de votre modèle Hugging Face dans Artifacts, définissez la variable d’environnement WANDB_LOG_MODEL sur l’une des valeurs suivantes :
  • checkpoint : Téléverse un point de contrôle tous les args.save_steps à partir de TrainingArguments.
  • end : Téléverse le modèle à la fin de l’entraînement, si load_best_model_at_end est également défini.
  • false : Ne téléverse pas le modèle.
Tous les Trainer Transformers que vous initialisez à partir de maintenant téléversent des modèles dans votre projet W&B. Les points de contrôle du modèle que vous journalisez sont visibles dans l’interface Artifacts et incluent la traçabilité complète du modèle. Voir un exemple de point de contrôle du modèle dans l’interface Artifacts.
Par défaut, votre modèle est enregistré dans W&B Artifacts sous la forme model-{run_id} lorsque WANDB_LOG_MODEL est défini sur end, ou checkpoint-{run_id} lorsque WANDB_LOG_MODEL est défini sur checkpoint. Cependant, si vous transmettez un run_name dans vos TrainingArguments, le modèle est enregistré sous la forme model-{run_name} ou checkpoint-{run_name}.

W&B registre

Après avoir enregistré vos point de contrôle du modèle dans Artifacts, vous pouvez enregistrer les point de contrôle du modèle de vos meilleurs modèles et les centraliser au sein de votre équipe avec registre. Avec le registre, vous pouvez organiser vos meilleurs modèles par tâche, gérer le cycle de vie des modèles, suivre et auditer l’ensemble du cycle de vie du machine learning, et automatiser les actions en aval. Pour lier un Artifact de modèle, reportez-vous à registre.

Visualiser les sorties d’évaluation pendant l’entraînement

Visualiser les sorties de votre modèle pendant l’entraînement ou l’évaluation est souvent essentiel pour comprendre comment il apprend. Examiner des prédictions concrètes en parallèle des courbes de perte vous aide à repérer des problèmes de qualité que des métriques agrégées peuvent masquer. Grâce au système de callbacks du Transformers Trainer, vous pouvez journaliser des données plus utiles dans les tableaux W&B. Cela inclut les sorties de génération de texte de vos modèles ou d’autres prédictions. Pour obtenir un guide complet sur la façon de journaliser les sorties d’évaluation pendant l’entraînement dans un tableau W&B comme celui ci-dessous, voir Journaliser et afficher des échantillons d’évaluation pendant l’entraînement.
Affiche un tableau W&B avec des sorties d’évaluation

Terminez votre run W&B (notebook uniquement)

Si votre entraînement est encapsulé dans un script Python, le run W&B se termine à la fin de l’exécution du script. Si vous utilisez un notebook Jupyter ou Google Colab, appelez run.finish() pour indiquer que l’entraînement est terminé.

Visualisez vos résultats

Après avoir journalisé vos résultats d’entraînement, vous pouvez les explorer dans le tableau de bord W&B. Vous pouvez comparer des run, examiner de plus près vos observations et explorer vos données à l’aide de visualisations interactives. À ce stade, vous disposez d’une intégration fonctionnelle : votre Trainer journalise des métriques dans un projet spécifié, enregistre éventuellement des points de contrôle du modèle dans Artifacts et affiche les sorties d’évaluation dans le tableau de bord W&B.

Fonctionnalités avancées et FAQ

Les sections suivantes abordent des tâches complémentaires courantes, comme l’enregistrement du meilleur modèle, la reprise de l’entraînement à partir d’un point de contrôle, la personnalisation des callbacks de journalisation et la configuration du comportement de W&B via des variables d’environnement.

Enregistrer le meilleur modèle

Si vous transmettez TrainingArguments avec load_best_model_at_end=True à votre Trainer, W&B enregistre le point de contrôle du modèle le plus performant dans Artifacts. Si vous enregistrez les points de contrôle de votre modèle dans Artifacts, vous pouvez les promouvoir vers le registre. Dans le registre, vous pouvez :
  • Organiser les versions de votre meilleur modèle par tâche de ML.
  • Centraliser les modèles et les partager avec votre équipe.
  • Préparer les modèles pour la production ou les marquer pour une évaluation plus approfondie.
  • Déclencher des processus CI/CD en aval.

Charger un modèle enregistré

Si vous avez enregistré votre modèle dans W&B Artifacts avec WANDB_LOG_MODEL, vous pouvez télécharger les poids de votre modèle pour poursuivre l’entraînement ou effectuer de l’inférence. Rechargez-les dans la même architecture Hugging Face que celle utilisée précédemment.

Reprendre l’entraînement à partir d’un point de contrôle

Si vous définissez WANDB_LOG_MODEL='checkpoint', vous pouvez reprendre l’entraînement en utilisant model_dir comme valeur de l’argument model_name_or_path dans vos TrainingArguments et en passant resume_from_checkpoint=True à Trainer.

Journaliser et afficher des échantillons d’évaluation pendant l’entraînement

Le WandbCallback de la bibliothèque Transformers gère la journalisation dans W&B via le Trainer de Transformers. Vous pouvez personnaliser ce callback pour journaliser les prédictions du modèle, des matrices de confusion ou d’autres données personnalisées. Pour ce faire, créez une sous-classe de WandbCallback et ajoutez des fonctionnalités qui utilisent des méthodes supplémentaires de la classe Trainer. Vous trouverez ci-dessous le schéma général pour ajouter ce nouveau callback au Hugging Face Trainer, suivi d’un exemple de code complet pour journaliser les sorties d’évaluation dans un tableau W&B :

Afficher des échantillons d’évaluation pendant l’entraînement

La section suivante montre comment personnaliser le WandbCallback pour exécuter les prédictions du modèle et journaliser des échantillons d’évaluation dans un tableau W&B pendant l’entraînement. Cela s’exécute tous les eval_steps en utilisant la méthode on_evaluate du callback du Trainer. La fonction decode_predictions décode les prédictions et les labels à partir de la sortie du modèle à l’aide du tokenizer. Ensuite, le code crée un dataframe pandas à partir des prédictions et des labels, puis ajoute une colonne epoch au dataframe. Enfin, le code crée un wandb.Table à partir du dataframe et le journalise dans W&B. Vous pouvez contrôler la fréquence de la journalisation en journalisant les prédictions toutes les freq époques.
Contrairement au WandbCallback standard, ce callback personnalisé doit être ajouté au trainer après l’instanciation du Trainer, et non pendant l’initialisation du Trainer. Cela s’explique par le fait que l’instance Trainer est transmise au callback lors de l’initialisation.
Pour un exemple plus détaillé, voir ce Colab.

Paramètres W&B supplémentaires

Vous pouvez affiner la configuration de ce qui est enregistré avec Trainer en définissant des variables d’environnement. Pour obtenir une liste complète des variables d’environnement W&B, voir la référence des variables d’environnement.

Personnaliser wandb.init()

Le WandbCallback utilisé par Trainer appelle wandb.init() en interne lors de l’initialisation de Trainer. Vous pouvez aussi configurer vos runs manuellement en appelant wandb.init() avant l’initialisation de Trainer. Cela vous donne un contrôle total sur la configuration de votre run W&B. Voici un exemple de ce que vous pouvez passer à init. Pour plus de détails sur wandb.init(), voir la référence wandb.init().

Ressources supplémentaires

Pour aller plus loin, voici six articles sur Transformers et W&B.

Obtenir de l’aide ou suggérer des fonctionnalités

Pour tout problème, toute question ou toute demande de fonctionnalité concernant l’intégration W&B de Hugging Face, publiez dans ce fil de discussion sur les forums Hugging Face ou ouvrez une issue dans le dépôt GitHub Transformers de Hugging Face.