Ajouter W&B à une bibliothèque Python

Ce guide décrit différentes 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 artefacts, 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 seul script d’entraînement ou 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 :

Si wandb est une dépendance requise 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, métriques et quels artefacts votre bibliothèque journalise.
S’il faut prendre en charge l’optimisation des hyperparamètres avec les balayages W&B.
S’il faut partager des artefacts, tels que des modèles et des jeux de données, via le Registry W&B de votre organisation.
Comment votre bibliothèque gère l’entraînement distribué et plusieurs processus.

Ces choix déterminent la façon 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.

Choisissez comment installer W&B

Choisissez d’installer automatiquement W&B avec votre bibliothèque ou de l’exposer comme fonctionnalité facultative.

Inclure W&B comme dépendance

Si W&B est au cœur de 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 compatible en fonction des fonctionnalités W&B utilisées par votre intégration.

Faites de W&B une dépendance facultative

Si W&B est une fonctionnalité facultative, permettez l’installation de votre bibliothèque sans wandb. Déclarez W&B en tant que 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 :

pip install "my_awesome_lib[wandb]"

Authentifiez les utilisateurs

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

Créer une clé API

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.

S’authentifier depuis la ligne de commande

Dans votre terminal, exécutez :

wandb login

W&B vous invite à saisir une clé API. Vous pouvez également 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() dans du code de 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 de run.

Mode	Comportement
`disabled`	Désactive la journalisation W&B. W&B n’enregistre ni ne téléverse les données de run. Les appels aux méthodes W&B n’ont aucun effet.
`offline`	Enregistre les données de run localement sans les téléverser. Vous pourrez téléverser le run ultérieurement avec `wandb sync`.

Utilisez disabled si vous ne souhaitez pas enregistrer les données de run. Utilisez offline si vous souhaitez enregistrer les données localement pour les téléverser ultérieurement.

Utiliser le mode `disabled`

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

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

Ou définissez WANDB_MODE dans l’environnement :

export WANDB_MODE=disabled

Vous pouvez également définir le mode avec la CLI W&B :

wandb disabled

Utiliser le mode `offline`

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

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

Ou définissez 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

Téléversez ultérieurement un run hors ligne avec :

wandb sync <run_directory>

Initialiser un run

Après vous être authentifié, initialisez un run pour consigner des métriques, des valeurs de configuration et des artefacts à partir de votre bibliothèque. Appelez wandb.init() et spécifiez le projet et l’entité d’équipe. Si vous omettez le projet, W&B stocke le run dans le projet "uncategorized" par défaut. Utilisez wandb.init() comme gestionnaire de contexte autour de la boucle d’entraînement. À la sortie du bloc, W&B finalise 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  # Faible 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 (le double du bruit d'entrée)
    
    y_pred = model(xb)  # Prédiction du modèle
    loss = (yb - y_pred) ** 2  # Perte d'erreur quadratique moyenne

    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 les 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 clôturer 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 d'entrée simulées
        yb = weights + noise * 2  # Sortie cible simulée (le double du bruit d'entrée)
        
        y_pred = model(xb)  # Prédiction du modèle
        loss = (yb - y_pred) ** 2  # Perte : erreur quadratique moyenne

        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 surveiller avec W&B. Utilisez-le comme gestionnaire de contexte autour de toute la boucle d’entraînement afin que le run capture les sorties standard et d’erreur, ainsi que les messages d’erreur pertinents pour le débogage.

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

Enregistrez la configuration et les métriques

Enregistrez les valeurs de configuration et les métriques dans W&B afin de pouvoir, avec les membres de votre équipe, comparer, filtrer, regrouper et reproduire des expériences.

Enregistrer 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 explicites et des valeurs sérialisables au format 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 peuvent ne pas être 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 les 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 où chaque clé correspond au nom d’une métrique et chaque valeur à sa valeur. Transmettez ce dictionnaire à wandb.Run.log(). L’extrait de code suivant consigne les 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 en savoir plus sur la journalisation des types de données pris en charge, des données suivies automatiquement et les bonnes pratiques, voir Consigner des métriques et des données. Pour suivre les modèles et les jeux de données, voir la section Suivre les modèles et les jeux de données avec des artefacts.

Définir un axe personnalisé pour le journal

Par défaut, W&B représente les métriques enregistrées en fonction d’une étape incrémentée automatiquement. Chaque appel à wandb.Run.log() incrémente l’étape. Utilisez wandb.Run.define_metric() pour représenter une métrique en fonction d’une autre valeur, telle qu’une époque ou une étape globale. L’exemple suivant définit x_axis_squared comme axe X pour validation_loss. À chaque itération de la boucle, x_axis_squared correspond au carré de l’index i et validation_loss à 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 artefacts

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 les runs. Utilisez W&B Artifacts pour gérer les versions des modèles, des jeux de données et des autres fichiers que votre bibliothèque produit ou consomme. Avant d’ajouter la prise en charge des artefacts, déterminez :

Quels fichiers journaliser.
Si la journalisation des artefacts est facultative.
À quelle fréquence journaliser les points de contrôle.
Comment nommer les artefacts et les alias.
Quels artefacts 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’artefacts afin de pouvoir récupérer, versionner et partager les poids entraînés. Incluez l’ID du run dans le nom de l’artefact afin d’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 artefact dont le nom inclut l’ID du run, y ajoute les poids du modèle depuis un répertoire local et journalise l’artefact avec un alias personnalisé.

Python

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

    # Données d'entraînement et logique d'entraînement du modèle ici

    if epoch % 10 == 0: # Journalise 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 où sont stockés 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 artefact, tel qu’un jeu de données ou un point de contrôle de modèle. W&B enregistre l’artefact comme entrée du run. Indiquez le nom de l’artefact et, éventuellement, un alias pour faire référence à une version spécifique de cet artefact. Le nom de l’artefact utilise le 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:
  # Récupérer l'artefact et le marquer comme dépendance
  artifact = run.use_artifact(artifact_or_name="artifact_name:alias_or_version")

Suivre les sorties d’une exécution

Utilisez wandb.Run.log_artifact() pour consigner un artefact en tant que sortie d’une exécution.

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

import wandb

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

  # Journaliser l'artefact en tant que sortie du run
  run.log_artifact(artifact_or_path = artifact)

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

Télécharger des artefacts

Utilisez l’API publique W&B pour télécharger un artefact sans créer de run ni enregistrer de relation entre un run et une entrée.

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 artefacts.

Lier des artefacts au W&B Registry

Utilisez le W&B Registry pour partager et gérer des versions d’artefacts entre équipes. Avant de lier une version d’artefact, déterminez :

Quelles versions d’artefacts partager.
Auxquelles des collections les lier.
Dans quel registre les publier.

Le registre de destination doit déjà exister.

L’exemple suivant journalise un artefact et le lie à une collection dans un registre :

import wandb
import random

# Indiquez le nom de la collection et du registry
# dans lesquels publier l'artefact
COLLECTION_NAME = "collection-name"
REGISTRY_NAME = "registry-name"

# Initialisez un W&B Run pour suivre l'artefact
with wandb.init(project="project-name") as run:
    # Créez un fichier de modèle simulé afin de pouvoir l'enregistrer
    with open("my_model.txt", "w") as f:
        f.write("Model: " + str(random.random()))

    # Enregistrez l'artefact dans W&B
    logged_artifact = run.log_artifact(
        artifact_or_path="./my_model.txt", 
        name="artifact-name",
        type="artifact-type" # Spécifie le type d'artefact
    )

    # Liez l'artefact au registry
    run.link_artifact(
        artifact=logged_artifact, 
        target_path=f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}"
    )

Pour plus d’informations, voir Associer une version d’artefact à une collection.

Ajuster les hyperparamètres

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

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

Pour plus d’informations, voir Sweeps.

Prise en charge de l’entraînement distribué

Si votre bibliothèque prend en charge plusieurs processus ou machines, définissez quels processus doivent créer des runs et consigner des données. Les approches courantes comprennent :

Journalisez uniquement depuis le processus principal. Cette approche évite les doublons de métriques et d’artefacts.
Créez un run pour chaque processus et regroupez les runs à l’aide d’une valeur group partagée.

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

Guides

Intégrations

Référence

Concevoir l’intégration

Choisissez comment installer W&B

Inclure W&B comme dépendance

Faites de W&B une dépendance facultative

Authentifiez 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

Enregistrez la configuration et les métriques

Enregistrer les valeurs de configuration

Consigner des métriques

Définir un axe personnalisé pour le journal

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

Journaliser les points de contrôle du modèle

Suivre les entrées d’un run

Suivre les sorties d’une exécution

Télécharger des artefacts

Lier des artefacts au W&B Registry

Ajuster les hyperparamètres

Prise en charge de l’entraînement distribué

​Concevoir l’intégration

​Choisissez comment installer W&B

​Inclure W&B comme dépendance

​Faites de W&B une dépendance facultative

​Authentifiez 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

​Enregistrez la configuration et les métriques

​Enregistrer les valeurs de configuration

​Consigner des métriques

​Définir un axe personnalisé pour le journal

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

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

​Suivre les entrées d’un run

​Suivre les sorties d’une exécution

​Télécharger des artefacts

​Lier des artefacts au W&B Registry

​Ajuster les hyperparamètres

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

Concevoir l’intégration

Choisissez comment installer W&B

Inclure W&B comme dépendance

Faites de W&B une dépendance facultative

Authentifiez 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

Enregistrez la configuration et les métriques

Enregistrer les valeurs de configuration

Consigner des métriques

Définir un axe personnalisé pour le journal

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

Journaliser les points de contrôle du modèle

Suivre les entrées d’un run

Suivre les sorties d’une exécution

Télécharger des artefacts

Lier des artefacts au W&B Registry

Ajuster les hyperparamètres

Prise en charge de l’entraînement distribué