Ajouter W&B à une bibliothèque Python

Ce guide présente des approches pour intégrer W&B dans une bibliothèque, un framework ou un SDK Python. Il couvre la gestion des dépendances, l’authentification, la journalisation facultative, l’initialisation des runs, les artifacts, l’optimisation des hyperparamètres et l’exécution distribuée. Utilisez ce guide lorsque votre intégration porte sur du code de bibliothèque réutilisable plutôt que sur un simple script d’entraînement ou un notebook. Pour une introduction à W&B, consultez Suivi des expériences.

Concevoir l’intégration

Avant d’ajouter W&B à votre bibliothèque, déterminez les points suivants :

Si wandb est une dépendance obligatoire ou facultative.
Si les utilisateurs peuvent exécuter votre bibliothèque sans enregistrer ni téléverser de données W&B.
Quelles valeurs de configuration, quelles métriques et quels artifacts votre bibliothèque journalise.
Si vous souhaitez prendre en charge l’optimisation des hyperparamètres avec W&B Sweeps.
Si vous souhaitez partager des artifacts, tels que des modèles et des jeux de données, via le registre de votre organisation.
Comment votre bibliothèque gère l’entraînement distribué et les processus multiples.

Ces choix déterminent la manière dont votre bibliothèque importe W&B, gère le cycle de vie des runs et se comporte lorsque W&B n’est pas disponible.

Choisir le mode d’installation de W&B

Choisissez entre installer W&B automatiquement avec votre bibliothèque ou le proposer comme fonctionnalité facultative.

Déclarer W&B comme dépendance obligatoire

Si W&B joue un rôle central dans votre bibliothèque, ajoutez wandb à ses dépendances. Pour un fichier requirements.txt :

requirements.txt

torch
wandb

Pour un fichier pyproject.toml :

pyproject.toml

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

Envisagez de spécifier une plage de versions compatibles en fonction des fonctionnalités de W&B qu’utilise votre intégration.

Faire de W&B une dépendance facultative

Si W&B est une fonctionnalité facultative, faites en sorte que votre bibliothèque puisse être installée sans wandb. Déclarez W&B comme dépendance facultative dans pyproject.toml :

pyproject.toml

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

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

Installez ensuite l’intégration avec la commande suivante :

pip install "my_awesome_lib[wandb]"

Authentifier les utilisateurs

W&B utilise des clés API pour authentifier les utilisateurs et les machines. Avant de pouvoir journaliser des runs depuis votre bibliothèque, vous devez générer une clé API et la mettre à la disposition du client wandb. W&B prend en charge l’authentification via la CLI, les variables d’environnement et wandb.login().

Créer une clé API

Pour plus de simplicité, accédez aux Paramètres utilisateur et créez une clé API. Copiez immédiatement la clé API et enregistrez-la dans un emplacement sécurisé, par exemple un gestionnaire de mots de passe.

S’authentifier depuis la ligne de commande

Dans votre terminal, exécutez :

wandb login

W&B vous invite à saisir une clé API. Vous pouvez aussi définir la variable d’environnement WANDB_API_KEY :

export WANDB_API_KEY="<api_key>"

Pour plus d’informations, voir Variables d’environnement.

S’authentifier depuis Python

Dans un environnement Python interactif ou un notebook, appelez :

import wandb

wandb.login()

Évitez d’appeler automatiquement wandb.login() depuis le code d’une bibliothèque réutilisable, car cela peut interrompre les flux de travail non interactifs.

Rendre la journalisation W&B facultative

Choisissez si W&B enregistre ou téléverse les données du run.

Mode	Comportement
`disabled`	Désactive la journalisation W&B. W&B n’enregistre ni ne téléverse les données du run. Les appels aux méthodes W&B sont sans effet.
`offline`	Enregistre les données du run en local sans les téléverser. Vous pourrez téléverser le run plus tard avec `wandb sync`.

Utilisez disabled si vous ne souhaitez pas enregistrer les données du run. Utilisez offline si vous souhaitez enregistrer les données en local pour les téléverser plus tard.

Utiliser le mode `disabled`

Passez mode="disabled" à wandb.init() :

with wandb.init(mode="disabled") as run:
    # Logique d’entraînement.

Vous pouvez aussi définir WANDB_MODE dans l’environnement :

export WANDB_MODE=disabled

Vous pouvez également définir le mode à l’aide de la CLI W&B :

wandb disabled

Utiliser le mode `offline`

Passez mode="offline" à wandb.init() :

with wandb.init(mode="offline") as run:
    # Logique d’entraînement.

Vous pouvez aussi définir WANDB_MODE dans l’environnement :

export WANDB_MODE=offline

En Python, définissez la variable d’environnement avant d’appeler wandb.init() :

import os

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

Vous pouvez également définir le mode à l’aide de la CLI W&B :

wandb offline

Pour téléverser ultérieurement un run hors ligne, utilisez :

wandb sync <run_directory>

Initialiser un run

Une fois authentifié, initialisez un run pour consigner des métriques, des valeurs de configuration et des artifacts depuis votre bibliothèque. Appelez wandb.init() en indiquant le projet et l’entity d’équipe. Si vous omettez le projet, W&B enregistre le run dans le projet par défaut "uncategorized". Utilisez wandb.init() comme gestionnaire de contexte autour de la boucle d’entraînement. À la sortie du bloc, W&B termine le run et traite les données en attente avant la fin du processus. Par exemple, supposons que votre bibliothèque contienne la boucle d’entraînement suivante :

Python

import random # Pour simuler des données

def model(training_data: int) -> int:
    """Model simulation for demonstration purposes."""
    return training_data * 2 + random.randint(-1, 1)  

# Simuler les poids et le bruit
weights = random.random() # Initialiser des poids aléatoires
noise = random.random() / 5  # Léger bruit aléatoire pour simuler du bruit

for epoch in range(epochs):
    xb = weights + noise  # Données d’entraînement d’entrée simulées
    yb = weights + noise * 2  # Sortie cible simulée (double du bruit d’entrée)
    
    y_pred = model(xb)  # Prédiction du modèle
    loss = (yb - y_pred) ** 2  # Perte : erreur quadratique moyenne (MSE)

    print(f"epoch={epoch}, loss={loss}")

Pour intégrer W&B, initialisez un run à l’aide d’un gestionnaire de contexte, transmettez les valeurs de configuration à wandb.init() et consignez des métriques avec wandb.Run.log() :

Python

import random # Pour simuler des données
import wandb

def model(training_data: int) -> int:
    """Model simulation for demonstration purposes."""
    return training_data * 2 + random.randint(-1, 1)  

# Simuler les poids et le bruit
weights = random.random() # Initialiser des poids aléatoires
noise = random.random() / 5  # Faible bruit aléatoire pour simuler du bruit

# Hyperparamètres et configuration
config = {
    "epochs": 10,  # Nombre d’époques d’entraînement
    "learning_rate": 0.01,  # Taux d’apprentissage de l’optimiseur
}

# Utiliser un gestionnaire de contexte pour initialiser et fermer les runs W&B
with wandb.init(entity="your-entity", project="your-project-name", config=config) as run:    
    # Simuler la boucle d’entraînement
    for epoch in range(config["epochs"]):
        xb = weights + noise  # Données d’entraînement simulées (entrée)
        yb = weights + noise * 2  # Sortie cible simulée (bruit d’entrée doublé)
        
        y_pred = model(xb)  # Prédiction du modèle
        loss = (yb - y_pred) ** 2  # Perte par erreur quadratique moyenne (MSE)

        print(f"epoch={epoch}, loss={loss}")
        # Journaliser l’époque et la perte dans W&B
        run.log({
            "epoch": epoch,
            "loss": loss,
        })

Quand appeler wandb.init()Appelez wandb.init() avant le code que vous souhaitez faire surveiller par W&B. Utilisez-le comme gestionnaire de contexte englobant toute la boucle d’entraînement, afin que le run capture la sortie standard, l’erreur standard et les messages d’erreur utiles au débogage.

La section suivante explique en détail comment consigner les valeurs de configuration et les métriques depuis votre bibliothèque.

Journaliser la configuration et les métriques

Journalisez les valeurs de configuration et les métriques dans W&B afin que vous et les membres de votre équipe puissiez comparer, filtrer, regrouper et reproduire vos expériences.

Journaliser les valeurs de configuration

Transmettez un dictionnaire de configuration à wandb.init() pour enregistrer les hyperparamètres et d’autres métadonnées. Utilisez des clés descriptives et des valeurs sérialisables en JSON :

config = {
    "batch_size": 32,
    "learning_rate": 0.001,
    "optimizer": "adam",
    "model": {
        "type": "resnet",
        "depth": 50,
    },
    "dataset": {
        "name": "CIFAR-10",
        "num_classes": 10,
    },
}

Transmettez le dictionnaire à wandb.init() :

with wandb.init(entity="your-entity", project="your-project-name", config=config) as run:
    # Logique d’entraînement.

Certaines valeurs ne sont pas forcément disponibles au démarrage du run. Ajoutez-les ultérieurement avec wandb.Run.config.update() :

run.config.update(
    {
        "model_parameters": 3500,
    }
)

Pour plus d’informations, voir Configurer des expériences.

Consigner des métriques

Consignez des métriques telles que la perte ou la précision pendant l’entraînement. Créez un dictionnaire dans lequel chaque clé correspond au nom d’une métrique et chaque valeur à la valeur de cette métrique. Passez ce dictionnaire à wandb.Run.log(). L’extrait de code suivant consigne des métriques d’entraînement et de validation dans W&B :

Python

import wandb

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

Utilisez des préfixes tels que train/ et val/ pour regrouper les métriques associées. Pour obtenir des conseils sur la journalisation des types de données pris en charge, les données suivies automatiquement et les bonnes pratiques, consultez Consigner des métriques et des données. Pour suivre des modèles et des jeux de données, consultez la section Suivre des modèles et des jeux de données avec des artifacts.

Définir un axe de journalisation personnalisé

Par défaut, W&B trace les métriques journalisées en fonction d’un step incrémenté automatiquement. Chaque appel à wandb.Run.log() incrémente le step. Utilisez wandb.Run.define_metric() pour tracer une métrique en fonction d’une autre valeur, comme une époque ou un step global. L’exemple suivant définit x_axis_squared comme axe X pour validation_loss. À chaque itération de la boucle, x_axis_squared vaut le carré de l’index i, et validation_loss est une valeur générée aléatoirement :

Python

import wandb
import random

with wandb.init() as run:
    run.define_metric(step_metric = "x_axis_squared", name = "validation_loss")

    for i in range(10):
        log_dict = {
            "x_axis_squared": i**2,
            "validation_loss": random.random(),
        }
        run.log(log_dict)

Pour plus d’informations, voir Définir un axe de journalisation personnalisé.

Suivre les modèles et les jeux de données avec des artifacts

En plus des métriques, vous pouvez conserver les modèles et les jeux de données que votre bibliothèque produit ou consomme, afin que vous et les membres de votre équipe puissiez reproduire et comparer des runs. Utilisez W&B Artifacts pour versionner les modèles, les jeux de données et les autres fichiers que votre bibliothèque produit ou consomme. Avant d’ajouter la prise en charge des artifacts, déterminez :

les fichiers à journaliser ;
si la journalisation des artifacts doit être facultative ;
la fréquence de journalisation des points de contrôle ;
la manière de nommer les artifacts et les alias ;
les artifacts qui représentent les entrées et les sorties des runs.

Journaliser les points de contrôle du modèle

Journalisez les points de contrôle du modèle sous forme d’artifacts afin de pouvoir récupérer, versionner et partager les poids entraînés. Incluez l’ID du run dans le nom de l’artifact pour associer chaque point de contrôle à son run d’origine. L’exemple suivant journalise un point de contrôle toutes les 10 époques. Il crée un artifact dont le nom inclut l’ID du run, y ajoute les poids du modèle à partir d’un répertoire local, puis journalise l’artifact avec un alias personnalisé.

Python

import wandb
with wandb.init(entity="your-entity", project="your-project-name") as run:

    # Placez ici les données d'entraînement et la logique d'entraînement du modèle

    if epoch % 10 == 0: # Journaliser un point de contrôle du modèle toutes les 10 époques

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

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

        run.log_artifact(artifact, aliases=f"epoch_{epoch}")

Suivre les entrées d’un run

Utilisez wandb.Run.use_artifact() lorsqu’un run utilise un artifact, par exemple un jeu de données ou un point de contrôle de modèle. W&B enregistre l’artifact comme entrée du run. Indiquez le nom de l’artifact et, si vous le souhaitez, un alias pour cibler une version précise de cet artifact. Le nom de l’artifact se présente au format artifact_name:version ou artifact_name:alias.

Python

import wandb

# Initialiser un run
with wandb.init(entity="your-entity", project="your-project") as run:
  # Obtenir l’artifact et le marquer comme dépendance
  artifact = run.use_artifact(artifact_or_name="artifact_name:alias_or_version")

Suivre les sorties d’un run

Utilisez wandb.Run.log_artifact() pour journaliser un artifact comme sortie d’un run.

Créez un artifact avec wandb.Artifact().
Ajoutez un ou plusieurs fichiers à l’artifact.
Journalisez l’artifact avec wandb.Run.log_artifact().

import wandb

# Initialiser un run
with wandb.init(entity="your-entity", project="project-name") as run:
  
  # Créer un artifact
  artifact = wandb.Artifact(name = "artifact-name", type = "artifact-type")
  artifact.add_file(local_path = "path/to/file", name="optional-filename") # Ajouter un fichier à l’artifact

  # Journaliser l’artifact comme sortie du run
  run.log_artifact(artifact_or_path = artifact)

Pour en savoir plus sur la création, la gestion et l’utilisation des artifacts, consultez Artifacts.

Télécharger des artifacts

Utilisez l’API publique W&B pour télécharger un artifact sans créer de run ni l’enregistrer comme entrée d’un run.

import wandb

api = wandb.Api()

artifact = api.artifact(
    "<entity>/<project>/<artifact_name>:<alias_or_version>"
)

local_path = artifact.download()

Pour plus d’informations, consultez Télécharger et utiliser des artifacts.

Lier des artifacts au registre

Utilisez Registry pour partager et gérer des versions d’artifact entre équipes. Avant de lier une version d’artifact, déterminez :

les versions d’artifact à partager ;
les collections auxquelles les lier ;
le registre dans lequel les publier.

Le registre de destination doit déjà exister.

L’exemple suivant journalise un artifact et le lie à une collection d’un registre :

import wandb
import random

# Indiquer le nom de la collection et du registre
# dans lesquels vous souhaitez publier l’artifact
COLLECTION_NAME = "collection-name"
REGISTRY_NAME = "registry-name"

# Initialiser un run W&B pour suivre l’artifact
with wandb.init(project="project-name") as run:
    # Créer un fichier de modèle simulé afin de pouvoir le journaliser
    with open("my_model.txt", "w") as f:
        f.write("Model: " + str(random.random()))

    # Journaliser l’artifact dans W&B
    logged_artifact = run.log_artifact(
        artifact_or_path="./my_model.txt", 
        name="artifact-name",
        type="artifact-type" # Indique le type d’artifact
    )

    # Lier l’artifact au registre
    run.link_artifact(
        artifact=logged_artifact, 
        target_path=f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}"
    )

Pour plus d’informations, voir Lier une version d’artifact à une collection.

Optimiser les hyperparamètres

Si votre bibliothèque prend en charge l’optimisation des hyperparamètres, intégrez W&B Sweeps pour effectuer des recherches par grille, aléatoires ou bayésiennes.

W&B recommande de séparer la configuration de sweep de la logique d’entraînement sous-jacente. La fonction d’entraînement doit lire ses paramètres depuis wandb.Run.config plutôt que de dépendre directement d’une logique propre au sweep.

Pour plus d’informations, voir Sweeps.

Prendre en charge l’entraînement distribué

Si votre bibliothèque prend en charge plusieurs processus ou machines, déterminez quels processus créent des runs et journalisent des données. Voici les approches courantes :

Journaliser uniquement depuis le processus principal. Cette approche évite de dupliquer les métriques et les artifacts.
Créer un run par processus et regrouper les runs à l’aide d’une valeur group commune.

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

​Concevoir l’intégration

​Choisir le mode d’installation de W&B

​Déclarer W&B comme dépendance obligatoire

​Faire de W&B une dépendance facultative

​Authentifier les utilisateurs

​Créer une clé API

​S’authentifier depuis la ligne de commande

​S’authentifier depuis Python

​Rendre la journalisation W&B facultative

​Utiliser le mode disabled

​Utiliser le mode offline

​Initialiser un run

​Journaliser la configuration et les métriques

​Journaliser les valeurs de configuration

​Consigner des métriques

​Définir un axe de journalisation personnalisé

​Suivre les modèles et les jeux de données avec des artifacts

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

​Suivre les entrées d’un run

​Suivre les sorties d’un run

​Télécharger des artifacts

​Lier des artifacts au registre

​Optimiser les hyperparamètres

​Prendre en charge l’entraînement distribué

Concevoir l’intégration

Choisir le mode d’installation de W&B

Déclarer W&B comme dépendance obligatoire

Faire de W&B une dépendance facultative

Authentifier les utilisateurs

Créer une clé API

S’authentifier depuis la ligne de commande

S’authentifier depuis Python

Rendre la journalisation W&B facultative

Utiliser le mode `disabled`

Utiliser le mode `offline`

Initialiser un run

Journaliser la configuration et les métriques

Journaliser les valeurs de configuration

Consigner des métriques

Définir un axe de journalisation personnalisé

Suivre les modèles et les jeux de données avec des artifacts

Journaliser les points de contrôle du modèle

Suivre les entrées d’un run

Suivre les sorties d’un run

Télécharger des artifacts

Lier des artifacts au registre

Optimiser les hyperparamètres

Prendre en charge l’entraînement distribué