Ajouter W&B à une bibliothèque Python

Bonnes pratiques pour intégrer Weights & Biases dans votre bibliothèque Python afin d’assurer le suivi des expériences, la surveillance du système et la gestion des modèles.

Ce guide explique comment intégrer Weights & Biases (W&B) à une bibliothèque Python.

Suivez ces recommandations si vous intégrez W&B à une base de code complexe, comme un framework d’entraînement, un SDK ou une bibliothèque réutilisable.

Si vous débutez avec W&B, consultez les guides essentiels (par exemple, Suivi des expériences) avant de continuer.

Vous trouverez ci-dessous des conseils et bonnes pratiques pour les cas où la base de code sur laquelle vous travaillez est plus complexe qu’un simple script d’entraînement Python ou qu’un notebook Jupyter.

​

Déterminez comment les utilisateurs installent W&B

Avant de commencer, déterminez si W&B doit être une dépendance obligatoire ou une fonctionnalité facultative de votre bibliothèque.

​

Exiger W&B comme dépendance

Si W&B est au cœur des fonctionnalités de votre bibliothèque, ajoutez le SDK Python de W&B (wandb) à vos dépendances :

torch==1.8.0 
...
wandb==0.13.*

​

Rendre W&B facultatif à l’installation

Si W&B est une fonctionnalité facultative, permettez à votre bibliothèque de fonctionner sans que W&B soit installé.

Vous pouvez soit importer wandb conditionnellement en Python, soit le déclarer comme dépendance facultative dans pyproject.toml.

Python

Détectez si wandb est disponible et renvoyez une erreur claire si un utilisateur active des fonctionnalités W&B sans l’avoir installé :

try:
    import wandb
    _WANDB_AVAILABLE = True
except ImportError:
    _WANDB_AVAILABLE = False

pyproject.toml

Déclarez wandb comme dépendance facultative dans votre fichier pyproject.toml :

[project]
name = "my_awesome_lib"
version = "0.1.0"
dependencies = [
    "torch",
    "sklearn"
]

[project.optional-dependencies]
dev = [
    "wandb"
]

​

Authentifiez les utilisateurs

W&B utilise des clés API pour authentifier les utilisateurs et les machines.

​

Créer une clé API

Une clé API permet d’authentifier un client ou une machine auprès de W&B. Vous pouvez générer une clé API depuis votre profil utilisateur.

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.

1. Cliquez sur l’icône de votre profil utilisateur dans le coin supérieur droit.
2. Sélectionnez Paramètres utilisateur, puis faites défiler la page jusqu’à la section API Keys.

​

Installez W&B et connectez-vous

Pour installer la bibliothèque wandb localement et vous connecter :

Ligne de commande

1. Définissez la variable d’environnement WANDB_API_KEY avec votre clé API :

   export WANDB_API_KEY=<your_api_key>
   

2. Installez la bibliothèque wandb, puis connectez-vous :

   pip install wandb
   
   wandb login
   

Python

1. Ouvrez votre terminal et installez le SDK Python.

   pip install wandb
   

2. Connectez-vous à W&B depuis votre script ou notebook Python. Vous serez invité à saisir votre clé API.

   import wandb
   wandb.login()
   

Python notebook

Copiez-collez l’extrait de code suivant dans une cellule de votre notebook Jupyter, puis exécutez-le. Vous serez invité à saisir votre clé API.

!pip install wandb

import wandb
wandb.login()

​

Lancer un run

Un run représente une seule unité de calcul, comme une expérience d’entraînement. La plupart des bibliothèques créent un run par tâche d’entraînement. Pour en savoir plus sur les runs, voir W&B Runs.

Initialisez un run avec wandb.init() et indiquez le nom de votre projet et de votre entité d’équipe (nom de l’équipe). Si vous ne spécifiez pas de projet, W&B stocke votre run dans un projet par défaut appelé “uncategorized”.:

with wandb.init(project="<project_name>", entity="<entity>") as run:
    ...

W&B recommande d’utiliser un gestionnaire de contexte pour s’assurer que votre run est correctement fermé, même en cas d’erreur. Si vous n’utilisez pas de gestionnaire de contexte, vous devez appeler run.finish() pour fermer le run et enregistrer toutes les données dans W&B.

Quand appeler wandb.init

Appelez wandb.init() le plus tôt possible. W&B capture stdout, stderr et les messages d’erreur, ce qui facilite le débogage.

Placez l’ensemble de votre boucle d’entraînement dans un gestionnaire de contexte wandb.init afin de vous assurer que toutes les informations pertinentes sont bien capturées dans le run. Cela inclut les messages d’erreur, qui peuvent être essentiels pour le débogage.

​

Définir wandb comme dépendance facultative

Si vous souhaitez rendre wandb facultatif pour les utilisateurs de votre bibliothèque, vous pouvez soit :

• Définir une option wandb, par exemple :

Python

trainer = my_trainer(..., use_wandb=True)

Bash

python train.py ... --use-wandb

• Ou définir wandb sur disabled dans wandb.init :

Python

wandb.init(mode="disabled")

Bash

export WANDB_MODE=disabled

ou

wandb disabled

• Ou définir wandb en mode hors ligne — notez que wandb s’exécutera quand même, mais n’essaiera simplement pas de communiquer avec W&B via Internet :

Variable d'environnement

export WANDB_MODE=offline

ou

os.environ['WANDB_MODE'] = 'offline'

Bash

wandb offline

​

Définir une configuration de run

Fournissez un dictionnaire de configuration lorsque vous initialisez votre run afin d’enregistrer les hyperparamètres et d’autres métadonnées dans W&B.

Utilisez l’application W&B pour comparer les runs en fonction de leurs paramètres de configuration et les filtrer dans le tableau Runs. Vous pouvez également utiliser ces paramètres pour regrouper des runs dans l’application W&B.

Par exemple, dans l’image suivante, la taille de lot (bathch_size) a été définie comme paramètre de configuration et est visible (voir la première colonne) dans le tableau Runs. Cela permet aux utilisateurs de filtrer et de comparer les runs en fonction de leur taille de lot :

Les valeurs typiques des paramètres de configuration incluent :

• Le nom du modèle, sa version, les paramètres d’architecture et les hyperparamètres.
• Le nom du jeu de données, sa version, le nombre d’exemples d’entraînement ou de validation.
• Les paramètres d’entraînement tels que le taux d’apprentissage, la taille de lot et l’optimiseur.

L’extrait de code suivant montre comment enregistrer une configuration :

config = {"batch_size": 32, ...}
with wandb.init(..., config=config) as run:
    ...

​

Mettre à jour la configuration de run

Si certaines valeurs ne sont pas disponibles au moment de l’initialisation, mettez à jour la configuration plus tard avec wandb.Run.config.update. Par exemple, il se peut que vous souhaitiez ajouter les paramètres d’un modèle après son instanciation :

with wandb.init(...) as run:
    model = MyModel(...)
    run.config.update({"model_parameters": 3500})

Pour plus de détails, voir Configurer Experiments.

​

Journaliser les métriques et les données

​

Journaliser des métriques

Créez un dictionnaire dans lequel la clé correspond au nom de la métrique. Passez ce dictionnaire à wandb.Run.log() pour le journaliser dans W&B :

NUM_EPOCHS = 10

for epoch in range(NUM_EPOCHS):
    for input, ground_truth in data: 
        prediction = model(input) 
        loss = loss_fn(prediction, ground_truth) 
        metrics = { "loss": loss } 
        run.log(metrics)

Utilisez des préfixes de noms de métriques pour regrouper les métriques associées dans l’application W&B. Les préfixes courants incluent train/ et val/ pour les métriques d’entraînement et de validation, respectivement, mais vous pouvez utiliser n’importe quel préfixe adapté à votre cas d’usage.

Cela créera des sections distinctes dans l’espace de travail de votre projet pour vos métriques d’entraînement et de validation, ou pour d’autres types de métriques que vous souhaitez séparer :

with wandb.init(...) as run:
    metrics = {
        "train/loss": 0.4,
        "train/learning_rate": 0.4,
        "val/loss": 0.5, 
        "val/accuracy": 0.7
    }
    run.log(metrics)

Voir wandb.Run.log() pour en savoir plus.

​

Contrôler l’axe x

Si vous effectuez plusieurs appels à wandb.Run.log() pour la même étape d’entraînement, le SDK wandb incrémente un compteur interne à chaque appel à wandb.Run.log(). Ce compteur peut ne pas correspondre à l’étape d’entraînement de votre boucle d’entraînement.

Pour éviter cette situation, définissez explicitement l’étape de l’axe x avec run.define_metric, une seule fois, immédiatement après avoir appelé wandb.init :

with wandb.init(...) as run:
    run.define_metric("*", step_metric="global_step")

Le motif glob * signifie que chaque métrique utilisera global_step sur l’axe des x de vos graphiques. Si vous souhaitez que seules certaines métriques soient enregistrées en fonction de global_step, vous pouvez les spécifier à la place :

run.define_metric("train/loss", step_metric="global_step")

À présent, journalisez vos métriques, votre métrique step et votre global_step chaque fois que vous appelez wandb.Run.log() :

for step, (input, ground_truth) in enumerate(data):
    ...
    run.log({"global_step": step, "train/loss": 0.1})
    run.log({"global_step": step, "eval/loss": 0.2})

Si vous n’avez pas accès à la variable d’étape indépendante, par exemple si “global_step” n’est pas disponible pendant votre boucle de validation, la valeur précédemment enregistrée pour “global_step” est automatiquement utilisée par wandb. Dans ce cas, assurez-vous d’enregistrer une valeur initiale pour la métrique afin qu’elle soit définie au moment voulu.

​

Journaliser des médias et des données structurées

Outre les scalaires, vous pouvez consigner des images, des tableaux, du texte, de l’audio, de la vidéo, etc.

Voici quelques points à prendre en compte lorsque vous enregistrez des données :

• À quelle fréquence la métrique doit-elle être enregistrée ? Doit-elle être facultative ?
• Quel type de données peut être utile pour la visualisation ?
  • Pour les images, vous pouvez enregistrer des exemples de prédictions, des masques de segmentation, etc., afin d’observer leur évolution au fil du temps.
  • Pour le texte, vous pouvez enregistrer des tableaux d’exemples de prédictions pour les explorer plus tard.

Voir Journaliser des objets et des médias pour des exemples.

​

Prise en charge de l’entraînement distribué

Pour les frameworks compatibles avec les environnements distribués, vous pouvez adapter l’un des flux de travail suivants :

• Journalisez uniquement depuis le processus principal (recommandé).
• Journalisez depuis chaque processus et regroupez les runs à l’aide d’un nom group partagé.

Voir Journaliser des Experiments d’entraînement distribué pour plus de détails.

​

Suivre les modèles et les Datasets avec Artifacts

Utilisez W&B Artifacts pour suivre les modèles et les Datasets et en assurer la gestion des versions. Artifacts fournissent le stockage et la gestion des versions des ressources de machine learning, et assurent automatiquement la traçabilité afin de montrer comment les données et les modèles sont liés.

Tenez compte des points suivants lorsque vous intégrez Artifacts à votre bibliothèque :

• Déterminez s’il faut journaliser les points de contrôle du modèle ou les Datasets en tant qu’Artifacts (si vous souhaitez rendre cela facultatif).
• Références d’entrée d’Artifacts (par exemple, entity/project/artifact).
• Fréquence de journalisation des points de contrôle du modèle ou des Datasets. Par exemple, à chaque époque, toutes les 500 étapes, etc.

​

Journaliser les points de contrôle du modèle

Journalisez les points de contrôle du modèle dans W&B. Une approche courante consiste à journaliser les points de contrôle comme des artifacts, en utilisant le run ID unique généré par W&B dans le nom de l’artifact.

metadata = {"eval/accuracy": 0.8, "train/steps": 800} 

artifact = wandb.Artifact(
                name=f"model-{run.id}", 
                metadata=metadata, 
                type="model"
                ) 
artifact.add_dir("output_model") # répertoire local où sont stockés les poids du modèle

aliases = ["best", "epoch_10"] 
run.log_artifact(artifact, aliases=aliases)

L’extrait de code précédent montre comment enregistrer un point de contrôle du modèle en tant qu’artifact et ajouter des métadonnées telles que la précision de l’évaluation et les étapes d’entraînement. L’artifact se voit attribuer un nom qui inclut le run ID unique, et il est étiqueté avec des alias personnalisés pour s’y référer facilement.

​

Journaliser les artifacts en entrée

Journalisez les Datasets ou les modèles préentraînés utilisés en entrée :

dataset = wandb.Artifact(name="flowers", type="dataset")
dataset.add_file("flowers.npy")
run.use_artifact(dataset)

L’extrait de code précédent crée un artifact pour un jeu de données nommé “flowers” et y ajoute un fichier. L’artifact est ensuite associé au run en cours à l’aide de run.use_artifact(), ce qui permet à W&B de suivre la traçabilité du jeu de données utilisé dans le run.

​

Télécharger des Artifacts

Téléchargez des Artifacts déjà enregistrés dans W&B afin de les utiliser dans votre code d’entraînement ou d’inférence.

Si vous disposez d’un contexte de run, utilisez wandb.Run.use_artifact() pour faire référence à un artifact dans W&B, puis appelez wandb.Artifact.download() pour le télécharger dans un répertoire local.

with wandb.init(...) as run:
    artifact = run.use_artifact("user/project/artifact:latest")
    local_path = artifact.download()

Utilisez l’API publique W&B pour référencer et télécharger un artifact sans initialiser un run. C’est utile dans des scénarios tels que les environnements distribués ou les workflows d’inférence, lorsque vous ne souhaitez pas créer de nouveau run.

import wandb
artifact = wandb.Api().artifact("user/project/artifact:latest")
local_path = artifact.download()

Voir Télécharger et utiliser des Artifacts pour en savoir plus.

​

Ajuster les hyperparamètres

Si votre bibliothèque prend en charge l’ajustement des hyperparamètres, vous pouvez intégrer W&B Sweeps pour gérer et visualiser les expériences.