La bibliothèque Hugging Face Transformers simplifie l’utilisation de modèles NLP de pointe comme BERT et de techniques d’entraînement comme la précision mixte et le gradient checkpointing. L’intégration W&B ajoute un suivi des expériences riche et flexible ainsi que la gestion des versions des modèles dans des tableaux de bord centralisés interactifs, sans rien sacrifier à cette simplicité d’utilisation.
Journalisation avancée en quelques lignes
os.environ["WANDB_PROJECT"] = "<my-amazing-project>" # nommez votre projet W&B
os.environ["WANDB_LOG_MODEL"] = "checkpoint" # journalisez tous les points de contrôle du modèle
from transformers import TrainingArguments, Trainer
args = TrainingArguments(..., report_to="wandb") # activez le logging W&B
trainer = Trainer(..., args=args)
Si vous préférez passer directement à du code prêt à l’emploi, consultez ce Google Colab. Premiers pas : suivre les expériences
Inscrivez-vous et créez une clé API
Pour une méthode plus directe, créez une clé API en accédant directement aux Paramètres utilisateur. Copiez immédiatement la clé API nouvellement créée et conservez-la dans un endroit sûr, par exemple dans un gestionnaire de mots de passe.
- Cliquez sur l’icône de votre profil dans le coin supérieur droit.
- Sélectionnez Paramètres utilisateur, puis faites défiler jusqu’à la section Clés API.
Installez la bibliothèque wandb et connectez-vous
wandb localement et vous connecter :
Ligne de commande
Python
Python notebook
-
Définissez la variable d’environnement
WANDB_API_KEY sur votre clé API.
export WANDB_API_KEY=<your_api_key>
-
Installez la bibliothèque
wandb et connectez-vous.
pip install wandb
wandb login
import wandb
wandb.login()
!pip install wandb
import wandb
wandb.login()
WANDB_PROJECT sur le nom de votre projet. Le WandbCallback récupérera cette variable d’environnement et l’utilisera lors de la configuration de votre run.
Ligne de commande
Python
Python notebook
WANDB_PROJECT=amazon_sentiment_analysis
import os
os.environ["WANDB_PROJECT"]="amazon_sentiment_analysis"
%env WANDB_PROJECT=amazon_sentiment_analysis
Assurez-vous de définir le nom du projet avant d’initialiser le Trainer.
huggingface par défaut.
Enregistrez vos runs d’entraînement dans W&B
Trainer, dans votre code ou en ligne de commande, l’étape la plus importante consiste à définir report_to sur "wandb" afin d’activer la journalisation avec 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 journaliseront les pertes, les métriques d’évaluation, l’architecture du modèle et les gradients dans W&B pendant leur entraînement.
python run_glue.py \ # exécutez votre script Python
--report_to wandb \ # activez le logging vers W&B
--run_name bert-base-high-lr \ # nom du run W&B (facultatif)
# autres arguments de ligne de commande ici
from transformers import TrainingArguments, Trainer
args = TrainingArguments(
# autres args et kwargs ici
report_to="wandb", # active le logging vers W&B
run_name="bert-base-high-lr", # nom du run W&B (facultatif)
logging_steps=1, # fréquence d'envoi des logs à W&B
)
trainer = Trainer(
# autres args et kwargs ici
args=args, # vos arguments d'entraînement
)
trainer.train() # démarre l'entraînement et le logging vers W&B
Vous utilisez TensorFlow ? Remplacez simplement le Trainer de PyTorch par le TFTrainer de TensorFlow.
Activez l’enregistrement des points de contrôle du modèle
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.
Ligne de commande
Python
Python notebook
WANDB_LOG_MODEL="checkpoint"
import os
os.environ["WANDB_LOG_MODEL"] = "checkpoint"
%env WANDB_LOG_MODEL="checkpoint"
Trainer Transformers que vous initialisez à partir de maintenant téléverseront des modèles dans votre projet W&B. Les points de contrôle du modèle que vous journalisez seront visibles dans l’interface Artifacts et incluront la traçabilité complète du modèle (voir un exemple de point de contrôle du modèle dans l’interface ici).
Par défaut, votre modèle sera 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 sera enregistré sous la forme model-{run_name} ou checkpoint-{run_name}. Visualiser les sorties d’évaluation pendant l’entraînement
Terminez votre run W&B (Notebook uniquement)
run.finish().
run = wandb.init()
trainer.train() # démarrer l'entraînement et la journalisation dans W&B
# analyse post-entraînement, tests, autre code journalisé
run.finish()
Fonctionnalités avancées et FAQ
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.
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. Il vous suffit ensuite de les recharger dans la même architecture Hugging Face que celle utilisée précédemment.
# Créer un nouveau run
with wandb.init(project="amazon_sentiment_analysis") as run:
# Transmettre le nom et la version de l'Artifact
my_model_name = "model-bert-base-high-lr:latest"
my_model_artifact = run.use_artifact(my_model_name)
# Télécharger les poids du modèle dans un dossier et retourner le chemin
model_dir = my_model_artifact.download()
# Charger votre modèle Hugging Face depuis ce dossier
# en utilisant la même classe de modèle
model = AutoModelForSequenceClassification.from_pretrained(
model_dir, num_labels=num_labels
)
# Effectuer un entraînement supplémentaire ou lancer une inférence
WANDB_LOG_MODEL='checkpoint', vous pouvez également reprendre l’entraînement en utilisant model_dir comme valeur de l’argument model_name_or_path dans vos TrainingArguments, puis en passant resume_from_checkpoint=True à Trainer.
last_run_id = "xxxxxxxx" # récupérez le run_id depuis votre wandb workspace
# reprendre le run wandb à partir du run_id
with wandb.init(
project=os.environ["WANDB_PROJECT"],
id=last_run_id,
resume="must",
) as run:
# Connecter un Artifact au run
my_checkpoint_name = f"checkpoint-{last_run_id}:latest"
my_checkpoint_artifact = run.use_artifact(my_model_name)
# Télécharger le checkpoint dans un dossier et retourner le chemin
checkpoint_dir = my_checkpoint_artifact.download()
# réinitialiser votre modèle et votre trainer
model = AutoModelForSequenceClassification.from_pretrained(
"<model_name>", num_labels=num_labels
)
# vos arguments d'entraînement ici.
training_args = TrainingArguments()
trainer = Trainer(model=model, args=training_args)
# assurez-vous d'utiliser le répertoire du checkpoint pour reprendre l'entraînement depuis le checkpoint
trainer.train(resume_from_checkpoint=checkpoint_dir)
Trainer de Transformers est assurée par le WandbCallback de la bibliothèque Transformers. Si vous devez personnaliser votre journalisation Hugging Face, vous pouvez modifier ce callback en créant une sous-classe de WandbCallback et en ajoutant des fonctionnalités supplémentaires qui s’appuient sur d’autres méthodes de la classe Trainer.
Vous trouverez ci-dessous le schéma général pour ajouter ce nouveau callback au Trainer HF, puis plus bas un exemple de code complet pour journaliser les sorties d’évaluation dans un tableau W&B :
# Instancier le Trainer normalement
trainer = Trainer()
# Instancier le nouveau callback de journalisation, en lui passant l'objet Trainer
evals_callback = WandbEvalsCallback(trainer, tokenizer, ...)
# Ajouter le callback au Trainer
trainer.add_callback(evals_callback)
# Lancer l'entraînement du Trainer normalement
trainer.train()
Afficher des échantillons d’évaluation pendant l’entraînement
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. Nous le faisons tous les eval_steps en utilisant la méthode on_evaluate du callback du Trainer.
Ici, nous avons écrit une fonction decode_predictions pour décoder les prédictions et les labels à partir de la sortie du modèle à l’aide du tokenizer.
Ensuite, nous créons un dataframe pandas à partir des prédictions et des labels, puis nous ajoutons une colonne epoch au dataframe.
Enfin, nous créons un wandb.Table à partir du dataframe et le journalisons dans wandb.
De plus, nous pouvons contrôler la fréquence de la journalisation en journalisant les prédictions toutes les freq époques.
Remarque : 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.
from transformers.integrations import WandbCallback
import pandas as pd
def decode_predictions(tokenizer, predictions):
labels = tokenizer.batch_decode(predictions.label_ids)
logits = predictions.predictions.argmax(axis=-1)
prediction_text = tokenizer.batch_decode(logits)
return {"labels": labels, "predictions": prediction_text}
class WandbPredictionProgressCallback(WandbCallback):
"""WandbCallback personnalisé pour journaliser les prédictions du modèle pendant l'entraînement.
Ce callback journalise les prédictions et les étiquettes du modèle dans un wandb.Table à chaque
étape de journalisation pendant l'entraînement. Il permet de visualiser les
prédictions du modèle au fur et à mesure de la progression de l'entraînement.
Attributes:
trainer (Trainer): L'instance Hugging Face Trainer.
tokenizer (AutoTokenizer): Le tokenizer associé au modèle.
sample_dataset (Dataset): Un sous-ensemble du jeu de données de validation
pour générer des prédictions.
num_samples (int, optional): Nombre d'échantillons à sélectionner dans
le jeu de données de validation pour générer des prédictions. Par défaut : 100.
freq (int, optional): Fréquence de journalisation. Par défaut : 2.
"""
def __init__(self, trainer, tokenizer, val_dataset, num_samples=100, freq=2):
"""Initialise l'instance WandbPredictionProgressCallback.
Args:
trainer (Trainer): L'instance Hugging Face Trainer.
tokenizer (AutoTokenizer): Le tokenizer associé
au modèle.
val_dataset (Dataset): Le jeu de données de validation.
num_samples (int, optional): Nombre d'échantillons à sélectionner dans
le jeu de données de validation pour générer des prédictions.
Par défaut : 100.
freq (int, optional): Fréquence de journalisation. Par défaut : 2.
"""
super().__init__()
self.trainer = trainer
self.tokenizer = tokenizer
self.sample_dataset = val_dataset.select(range(num_samples))
self.freq = freq
def on_evaluate(self, args, state, control, **kwargs):
super().on_evaluate(args, state, control, **kwargs)
# contrôler la fréquence de journalisation en enregistrant les prédictions
# toutes les `freq` époques
if state.epoch % self.freq == 0:
# générer des prédictions
predictions = self.trainer.predict(self.sample_dataset)
# décoder les prédictions et les étiquettes
predictions = decode_predictions(self.tokenizer, predictions)
# ajouter les prédictions à un wandb.Table
predictions_df = pd.DataFrame(predictions)
predictions_df["epoch"] = state.epoch
records_table = self._wandb.Table(dataframe=predictions_df)
# enregistrer le tableau dans wandb
self._wandb.log({"sample_predictions": records_table})
# Commencer par instancier le Trainer
trainer = Trainer(
model=model,
args=training_args,
train_dataset=lm_datasets["train"],
eval_dataset=lm_datasets["validation"],
)
# Instancier le WandbPredictionProgressCallback
progress_callback = WandbPredictionProgressCallback(
trainer=trainer,
tokenizer=tokenizer,
val_dataset=lm_dataset["validation"],
num_samples=10,
freq=2,
)
# Ajouter le callback au trainer
trainer.add_callback(progress_callback)
Quels paramètres W&B supplémentaires sont disponibles ?
Trainer en définissant des variables d’environnement. Une liste complète des variables d’environnement W&B est disponible ici.
| Variable d’environnement | Utilisation |
|---|
WANDB_PROJECT | Donnez un nom à votre projet (huggingface par défaut) |
WANDB_LOG_MODEL | Enregistre le point de contrôle du modèle en tant qu’Artifact W&B (false par défaut) false (par défaut) : aucun point de contrôle du modèle checkpoint : un point de contrôle sera téléversé tous les args.save_steps (défini dans les TrainingArguments de Trainer). end : le point de contrôle final du modèle sera téléversé à la fin de l’entraînement.
|
WANDB_WATCH | Définit si vous souhaitez enregistrer, pour vos modèles, les gradients, les paramètres ou aucun des deux false (par défaut) : aucune journalisation des gradients ni des paramètres gradients : enregistre des histogrammes des gradients all : enregistre des histogrammes des gradients et des paramètres
|
WANDB_DISABLED | Définissez true pour désactiver complètement la journalisation (false par défaut) |
WANDB_QUIET. | Définissez true pour limiter la sortie standard aux seuls messages critiques (false par défaut) |
WANDB_SILENT | Définissez true pour supprimer la sortie affichée par wandb (false par défaut) |
Ligne de commande
Notebook
WANDB_WATCH=all
WANDB_SILENT=true
%env WANDB_WATCH=all
%env WANDB_SILENT=true
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()“.
wandb.init(
project="amazon_sentiment_analysis",
name="bert-base-high-lr",
tags=["baseline", "high-lr"],
group="bert",
)
Ressources supplémentaires
Obtenir de l’aide ou suggérer des fonctionnalités
