Ajouter W&B à une bibliothèque Python

Ce guide explique comment intégrer W&B à une bibliothèque Python afin que vos utilisateurs puissent suivre les expériences, surveiller les métriques système et gérer des modèles lorsqu’ils utilisent votre code. Il s’adresse aux auteurs et mainteneurs de bibliothèques qui souhaitent exposer les fonctionnalités de W&B via leur propre framework, SDK ou code d’entraînement réutilisable. Suivez ces recommandations si vous intégrez W&B dans une base de code complexe (comme un framework d’entraînement, un SDK ou une bibliothèque réutilisable), c’est-à-dire lorsque cette base de code va au-delà d’un simple script d’entraînement Python ou d’un notebook Jupyter.

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

Les sections suivantes présentent, dans l’ordre, les principales décisions d’intégration : comment installer W&B, comment vous authentifier, comment démarrer et configurer des exécutions, comment consigner des métriques et des artefacts, et comment prendre en charge l’entraînement distribué et les Sweeps d’hyperparamètres.

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. Ce choix a une incidence sur la façon dont vous importez le SDK Python W&B (wandb), documentez l’installation et gérez les environnements dans lesquels wandb n’est pas présent.

Exiger W&B comme dépendance

Si W&B est au cœur des fonctionnalités de votre bibliothèque, ajoutez wandb à vos dépendances afin qu’il soit installé automatiquement avec votre bibliothèque :

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é, afin que les utilisateurs qui n’ont pas besoin du suivi des expériences puissent quand même utiliser votre code. Vous pouvez soit importer wandb conditionnellement en Python, soit le déclarer comme dépendance facultative dans pyproject.toml.

Python
pyproject.toml

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

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. Avant que les utilisateurs puissent enregistrer des runs depuis votre bibliothèque, ils doivent générer une clé API et la rendre disponible pour le client wandb.

Créer une clé API

Une clé API permet d’authentifier un client ou une machine auprès de W&B. Générez une clé API depuis votre profil utilisateur afin de pouvoir l’utiliser pour les étapes de connexion qui suivent.

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.

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

Installez W&B et connectez-vous

Une fois que vous avez une clé API, installez la bibliothèque wandb localement et connectez-vous afin que les runs suivants puissent s’authentifier auprès de W&B. Choisissez l’onglet correspondant à votre environnement.

Ligne de commande
Python
Python notebook

Définissez la variable d’environnement WANDB_API_KEY avec votre clé API. Remplacez les valeurs entre <> par les vôtres :
export WANDB_API_KEY=<your_api_key>
Installez la bibliothèque wandb, puis connectez-vous :
pip install wandb wandb login

Ouvrez votre terminal et installez le SDK Python.
pip install wandb
Connectez-vous à W&B depuis votre script ou notebook Python. W&B vous invitera à saisir votre clé API.
import wandb wandb.login()

Copiez-collez l’extrait de code suivant dans une cellule de votre notebook Jupyter, puis exécutez-le. W&B vous invitera à saisir votre clé API.

!pip install wandb

import wandb
wandb.login()

Lancer un run

Après avoir configuré l’authentification, l’étape suivante consiste à lancer un run W&B afin que votre bibliothèque ait un emplacement où consigner des métriques, des configurations et des artéfacts. 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”. Remplacez les valeurs entre <> par les vôtres :

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 journaliser toutes les données dans W&B. La fermeture du run garantit que toutes les métriques, configurations et artefacts sont téléversés avant que le processus ne se termine.

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 à l’exécution, afin que les utilisateurs puissent exécuter votre bibliothèque sans produire de runs W&B, utilisez l’une des approches suivantes :

Définir une option wandb.
Définir wandb sur disabled dans wandb.init().
Définir wandb en mode hors ligne. wandb s’exécute toujours, mais ne communique pas avec W&B via Internet.

Définissez une option wandb, par exemple :

Python
Bash

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

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

Définissez wandb sur disabled dans wandb.init() :

Python
Bash

wandb.init(mode="disabled")

export WANDB_MODE=disabled

wandb disabled

Définissez wandb en mode hors ligne :

Variable d'environnement
Bash

export WANDB_MODE=offline

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

wandb offline

Définir une configuration de run

Après avoir initialisé un run, vous pouvez y joindre un dictionnaire de configuration qui enregistre les hyperparamètres et les autres métadonnées associés à ce run. La journalisation d’une configuration facilite la comparaison, le filtrage et la reproduction ultérieure des runs. 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 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 W&B. Par exemple, dans l’image suivante, la taille de lot (batch_size) est 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

Certaines valeurs de configuration, comme le nombre de paramètres du modèle, peuvent ne pas être connues lorsque vous appelez wandb.init(). 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 d’informations, voir Configurer les expériences.

Consigner des métriques et des données

Une fois le run démarré et configuré, vous pouvez commencer à consigner des métriques et d’autres données afin que W&B les enregistre pour ce run.

Journaliser des métriques

Pour journaliser des métriques scalaires telles que la perte ou la précision, créez un dictionnaire dans lequel chaque clé correspond au nom d’une 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 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ée 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)

Pour plus d’informations, voir wandb.Run.log().

Contrôler l’axe x

Par défaut, le SDK Python de W&B gère son propre compteur d’étapes, qui peut ne pas correspondre à la logique des étapes de votre boucle d’entraînement. 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 wandb.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 utilise global_step sur l’axe des x de vos graphiques. Si vous souhaitez que seules certaines métriques soient journalisé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, global_step n’est pas disponible pendant votre boucle de validation), la valeur précédemment journalisée pour global_step est automatiquement utilisée par W&B. Dans ce cas, assurez-vous de journaliser 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. La journalisation des médias avec les métriques aide les utilisateurs à examiner le comportement qualitatif du modèle au fil du temps. 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 et des masques de segmentation 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.

Pour plus d’informations, voir Journaliser des objets et des médias.

Prise en charge de l’entraînement distribué

Si votre bibliothèque peut exécuter l’entraînement sur plusieurs processus ou machines, décidez comment W&B doit se comporter dans ce contexte afin que les journaux soient cohérents et non dupliqués. 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é.

Pour plus d’informations, voir Journaliser des expériences d’entraînement distribué.

Suivre les modèles et les Datasets avec des artefacts

En plus des métriques, vous pouvez conserver les modèles et les Datasets que votre bibliothèque produit ou consomme afin que les utilisateurs puissent reproduire et comparer les runs. Utilisez W&B Artefacts pour suivre les modèles et les Datasets et en assurer la gestion des versions. Les artefacts 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.

Datasets stockés et points de contrôle du modèle dans W&B

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

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

Journaliser les points de contrôle du modèle

La journalisation des points de contrôle du modèle en tant qu’artefacts permet aux utilisateurs de récupérer, de versionner et de partager les poids entraînés. Une approche courante consiste à journaliser les points de contrôle comme des artefacts, en utilisant le run ID unique généré par W&B dans le nom de l’artefact.

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ù les poids du modèle sont stockés

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

L’extrait précédent journalise un point de contrôle du modèle en tant qu’artefact avec des métadonnées telles que la précision de l’évaluation et les étapes d’entraînement. Le nom de l’artefact inclut le run ID unique, et il est étiqueté avec des alias personnalisés pour s’y référer rapidement.

Journaliser les artefacts en entrée

Pour capturer la traçabilité entre les données et les modèles, journalisez les datasets ou les modèles préentraînés qu’un run utilise 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 artefact pour un dataset nommé “flowers” et y ajoute un fichier. L’appel à wandb.Run.use_artifact() associe l’artefact au run en cours afin que W&B puisse suivre la traçabilité du dataset utilisé dans le run.

Télécharger des artefacts

Après avoir enregistré des artefacts, vous pouvez télécharger des artefacts précédemment enregistrés depuis W&B afin de les utiliser dans votre code d’entraînement ou d’inférence. La bonne approche dépend du fait que vous disposiez déjà ou non d’un run actif. Si vous disposez d’un contexte de run, utilisez wandb.Run.use_artifact() pour faire référence à un artefact dans W&B, puis appelez wandb.Artifact.download() pour le télécharger dans un répertoire local. L’utilisation de wandb.Run.use_artifact() enregistre également l’artefact comme entrée du run actuel, ce qui préserve la traçabilité.

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 artefact sans initialiser un run. C’est utile dans des scénarios tels que les environnements distribués ou lorsque vous effectuez de l’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()

Pour plus d’informations, voir Télécharger et utiliser des artefacts.

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. Les balayages coordonnent plusieurs runs dans un espace de recherche défini et affichent les résultats dans W&B afin que les utilisateurs puissent comparer les configurations côte à côte.

Guides

Intégrations

Référence

Déterminez comment les utilisateurs installent W&B

Exiger W&B comme dépendance

Rendre W&B facultatif à l’installation

Authentifiez les utilisateurs

Créer une clé API

Installez W&B et connectez-vous

Lancer un run

Définir `wandb` comme dépendance facultative

Définir une configuration de run

Mettre à jour la configuration de run

Consigner des métriques et des données

Journaliser des métriques

Contrôler l’axe x

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

Prise en charge de l’entraînement distribué

Suivre les modèles et les Datasets avec des artefacts

Journaliser les points de contrôle du modèle

Journaliser les artefacts en entrée

Télécharger des artefacts

Ajuster les hyperparamètres

​Déterminez comment les utilisateurs installent W&B

​Exiger W&B comme dépendance

​Rendre W&B facultatif à l’installation

​Authentifiez les utilisateurs

​Créer une clé API

​Installez W&B et connectez-vous

​Lancer un run

​Définir wandb comme dépendance facultative

​Définir une configuration de run

​Mettre à jour la configuration de run

​Consigner des métriques et des données

​Journaliser des métriques

​Contrôler l’axe x

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

​Prise en charge de l’entraînement distribué

​Suivre les modèles et les Datasets avec des artefacts

​Journaliser les points de contrôle du modèle

​Journaliser les artefacts en entrée

​Télécharger des artefacts

​Ajuster les hyperparamètres

Déterminez comment les utilisateurs installent W&B

Exiger W&B comme dépendance

Rendre W&B facultatif à l’installation

Authentifiez les utilisateurs

Créer une clé API

Installez W&B et connectez-vous

Lancer un run

Définir `wandb` comme dépendance facultative

Définir une configuration de run

Mettre à jour la configuration de run

Consigner des métriques et des données

Journaliser des métriques

Contrôler l’axe x

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

Prise en charge de l’entraînement distribué

Suivre les modèles et les Datasets avec des artefacts

Journaliser les points de contrôle du modèle

Journaliser les artefacts en entrée

Télécharger des artefacts

Ajuster les hyperparamètres