Configurer des expériences

Utilisez la propriété config d’un run pour enregistrer votre configuration d’entraînement :

hyperparamètres
paramètres d’entrée, comme le nom du dataset ou le type de modèle
toute autre variable indépendante de vos expériences.

La propriété wandb.Run.config facilite l’analyse de vos expériences et la reproductibilité de vos travaux. Dans la W&B App, vous pouvez regrouper les données par valeurs de configuration, comparer les configurations de différents runs W&B et évaluer l’influence de chaque configuration d’entraînement sur la sortie. La propriété config est un objet de type dictionnaire qui peut être composé de plusieurs objets de type dictionnaire.

Pour journaliser des métriques de sortie ou des variables dépendantes comme la perte et la précision, utilisez wandb.Run.log() plutôt que wandb.Run.config.

Définir la configuration d’une expérience

Les configurations sont généralement définies au début d’un script d’entraînement. Les flux de travail de machine learning pouvant toutefois varier, vous n’êtes pas tenu de définir une configuration au début de votre script d’entraînement. Utilisez des tirets (-) ou des caractères de soulignement (_) plutôt que des points (.) dans les noms de vos variables de configuration. Si votre script accède à des clés de wandb.Run.config situées sous la racine, utilisez la syntaxe d’accès par dictionnaire ["key"]["value"] plutôt que la syntaxe d’accès par attribut config.key.value. Les sections suivantes présentent plusieurs scénarios courants de définition de la configuration de vos expériences.

Définir la configuration à l’initialisation

Transmettez un dictionnaire au début de votre script lorsque vous appelez l’API wandb.init(), qui génère un processus en arrière-plan chargé de synchroniser et de journaliser les données sous forme de run W&B. L’extrait de code suivant montre comment définir un dictionnaire Python contenant des valeurs de configuration, puis comment transmettre ce dictionnaire en argument lors de l’initialisation d’un run W&B.

import wandb

# Définir un dictionnaire de configuration
config = {
    "hidden_layer_sizes": [32, 64],
    "kernel_sizes": [3],
    "activation": "ReLU",
    "pool_sizes": [2],
    "dropout": 0.5,
    "num_classes": 10,
}

# Transmettre le dictionnaire de configuration lors de l’initialisation de W&B
with wandb.init(project="config_example", config=config) as run:
    ...

Si vous transmettez un dictionnaire imbriqué comme config, W&B aplatit les noms en les séparant par des points. Accédez aux valeurs du dictionnaire comme vous le feriez pour n’importe quel autre dictionnaire en Python :

# Accéder aux valeurs en utilisant la clé comme index
hidden_layer_sizes = run.config["hidden_layer_sizes"]
kernel_sizes = run.config["kernel_sizes"]
activation = run.config["activation"]

# Méthode get() des dictionnaires Python
hidden_layer_sizes = run.config.get("hidden_layer_sizes")
kernel_sizes = run.config.get("kernel_sizes")
activation = run.config.get("activation")

Dans l’ensemble du guide du développeur et des exemples, nous copions les valeurs de configuration dans des variables distinctes. Cette étape est facultative et sert uniquement à améliorer la lisibilité.

Définir la configuration avec argparse

Vous pouvez définir votre configuration avec un objet argparse. argparse, abréviation de « argument parser », est un module de la bibliothèque standard de Python 3.2 et versions ultérieures qui facilite l’écriture de scripts exploitant toute la souplesse et la puissance des arguments de ligne de commande. Cette approche est utile pour assurer le suivi des résultats de scripts lancés depuis la ligne de commande. Le script Python suivant montre comment utiliser un objet parser pour définir et renseigner la configuration de votre expérience. Les fonctions train_one_epoch et evaluate_one_epoch sont fournies pour simuler une boucle d’entraînement dans le cadre de cette démonstration :

# config_experiment.py
import argparse
import random

import numpy as np
import wandb


# Code de démonstration pour l’entraînement et l’évaluation
def train_one_epoch(epoch, lr, bs):
    acc = 0.25 + ((epoch / 30) + (random.random() / 10))
    loss = 0.2 + (1 - ((epoch - 1) / 10 + random.random() / 5))
    return acc, loss


def evaluate_one_epoch(epoch):
    acc = 0.1 + ((epoch / 20) + (random.random() / 10))
    loss = 0.25 + (1 - ((epoch - 1) / 10 + random.random() / 6))
    return acc, loss


def main(args):
    # Démarrer un run W&B
    with wandb.init(project="config_example", config=args) as run:
        # Accéder aux valeurs du dictionnaire de configuration et les stocker
        # dans des variables pour plus de lisibilité
        lr = run.config["learning_rate"]
        bs = run.config["batch_size"]
        epochs = run.config["epochs"]

        # Simuler l’entraînement et journaliser les valeurs dans W&B
        for epoch in np.arange(1, epochs):
            train_acc, train_loss = train_one_epoch(epoch, lr, bs)
            val_acc, val_loss = evaluate_one_epoch(epoch)

            run.log(
                {
                    "epoch": epoch,
                    "train_acc": train_acc,
                    "train_loss": train_loss,
                    "val_acc": val_acc,
                    "val_loss": val_loss,
                }
            )


if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        formatter_class=argparse.ArgumentDefaultsHelpFormatter
    )

    parser.add_argument("-b", "--batch_size", type=int, default=32, help="Batch size")
    parser.add_argument(
        "-e", "--epochs", type=int, default=50, help="Number of training epochs"
    )
    parser.add_argument(
        "-lr", "--learning_rate", type=float, default=0.001, help="Learning rate"
    )

    args = parser.parse_args()
    main(args)

Définir la configuration au fil de votre script

Vous pouvez ajouter des paramètres à votre objet de configuration à n’importe quel endroit de votre script. L’extrait de code suivant montre comment ajouter de nouvelles paires clé-valeur à un objet de configuration existant :

import wandb

# Définir un objet dictionnaire de configuration
config = {
    "hidden_layer_sizes": [32, 64],
    "kernel_sizes": [3],
    "activation": "ReLU",
    "pool_sizes": [2],
    "dropout": 0.5,
    "num_classes": 10,
}

# Transmettre le dictionnaire de configuration lors de l’initialisation de W&B
with wandb.init(project="config_example", config=config) as run:
    # Mettre à jour la configuration une fois W&B initialisé
    run.config["epochs"] = 4
    run.config["batch_size"] = 32

Vous pouvez ajouter plusieurs valeurs à la fois. L’extrait de code suivant montre comment mettre à jour plusieurs paires clé-valeur dans un objet de configuration existant :

# Définir un objet dictionnaire de configuration
config = {
    "channels": 24,
    "lr": 1.0,
}

with wandb.init(project="config_example", config=config) as run:
    run.config.update(
        {
            "lr": 0.1,
            "channels": 16,
        },
        allow_val_change=True,
    )

Veillez à définir allow_val_change=True si vous souhaitez modifier la valeur d’une clé existante. Si ce paramètre n’est pas défini, W&B génère une erreur lorsque vous essayez de modifier la valeur d’une clé existante.

Définir la configuration une fois votre run terminé

Utilisez l’API publique de W&B pour mettre à jour la configuration d’un run terminé. Vous devez fournir à l’API votre entity, le nom de votre projet et l’ID du run. Ces informations sont disponibles dans l’objet Run ou dans la W&B App :

with wandb.init() as run:
    ...

# Récupérez les valeurs suivantes dans l’objet Run s’il a été initialisé depuis le
# script ou le notebook en cours, ou copiez-les depuis l’interface de l’application W&B.
username = run.entity
project = run.project
run_id = run.id

# Notez que api.run() renvoie un type d’objet différent de celui renvoyé par wandb.init().
api = wandb.Api()
api_run = api.run(f"{username}/{project}/{run_id}")
api_run.config["bar"] = 32
api_run.update()

Mettre en évidence les valeurs de configuration

Épinglez des clés de configuration dans la section References en haut de la page d’aperçu d’un run. Utilisez wandb.Run.pin_config_keys pour épingler une ou plusieurs clés de configuration avec le SDK Python. Par exemple, si vous surveillez vos runs d’entraînement dans un tableau de bord Grafana, ajoutez l’URL du tableau de bord à votre configuration et épinglez la clé grafana_url :

config = {
    "hidden_layer_sizes": [32, 64],
    "kernel_sizes": [3],
    "activation": "ReLU",
    "pool_sizes": [2],
    "dropout": 0.5,
    "num_classes": 10,
    "grafana_url": "[Grafana dashboard](https://my-grafana-instance.com/)"
}

with wandb.init(config=config) as run:
    # Ajoute la clé de configuration « grafana_url » à la section References.
    run.pin_config_keys(["grafana_url"])

Afficher les valeurs de configuration

Vous pouvez accéder à vos valeurs de configuration dans la W&B App, pendant un run ou à partir de runs existants. Vous pouvez également y accéder depuis votre système de fichiers local.

W&B App
Pendant un run
Run existant
Système de fichiers local

Pour afficher la configuration d’un run dans la W&B App :

Accédez à votre projet dans la W&B App.
Sélectionnez le run que vous souhaitez afficher.
Sélectionnez l’onglet Overview.
Faites défiler jusqu’à la section Config.
Facultatif : cliquez sur View raw data pour afficher la configuration au format JSON.

Le format JSON brut est utile lorsque vous écrivez des expressions pour créer ou transformer des graphiques en courbes à partir de valeurs de configuration, de métriques journalisées ou de valeurs de synthèse. Pour plus de détails, consultez Expressions.

Utilisez la propriété wandb.Run.config pour accéder aux valeurs de configuration d’un run pendant son exécution. wandb.Run.config renvoie un objet dictionnaire contenant les paires clé-valeur de la configuration.L’exemple suivant montre comment accéder aux valeurs de configuration d’un run pendant son exécution. Remplacez les valeurs du dictionnaire de configuration par vos propres hyperparamètres, architecture de modèle, nom du dataset et autres paramètres. Remplacez "<my-project>" par le nom de votre projet W&B :

import wandb

config = {
    "epochs": 100,
    "learning_rate": 0.001,
    "model_type": "CNN",
    "dataset_id": "cats-0192"
}

with wandb.init(project="<my-project>", config=config) as run:
  print(dict(run.config))

L’extrait suivant montre un exemple de sortie possible dans votre terminal lorsque vous exécutez le code ci-dessus :

{'_runtime': 0.0970615, '_step': 97, 'accuracy': 0.9746484067793967, 'loss': 0.025044765547545846, '_timestamp': 1785255343.65151}

Utilisez l’API publique de W&B pour accéder à la configuration d’un run déjà journalisé. Transmettez l’entity, le nom du projet et l’ID du run à wandb.Api.run(), puis accédez à la configuration du run avec la propriété wandb.Api.Run.config.Dans l’exemple suivant, remplacez "<entity>", "<project>" et "<run_id>" par votre entity W&B, le nom de votre projet et l’ID du run.

import wandb

api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")

print(run.name)
print(run.config)

Pour accéder aux valeurs de configuration de plusieurs runs d’un projet, récupérez les runs avec wandb.Api.runs(), puis parcourez les objets Run renvoyés :

import wandb

api = wandb.Api()
runs = api.runs("<entity>/<project>")

for run in runs:
    print(f"Run name: {run.name}")
    print(f"Run ID: {run.id}")
    print(f"Run config: {run.config}")
    print("----------")

L’extrait suivant montre un exemple de sortie possible dans votre terminal lorsque vous exécutez le code ci-dessus :

Run name: clean-oath-11
Run ID: mt2dasoz
Run config: {'epochs': 1000, 'learning_rate': 0.1, 'model_type': 'Multivariate_neural_network_classifier'}
----------

Run name: zesty-snowball-7
Run ID: qne08r7u
Run config: {'epochs': 1000, 'learning_rate': 0.1, 'model_type': 'Multivariate_neural_network_classifier'}
----------

W&B stocke les valeurs de configuration du run dans le fichier config.yaml du répertoire du run. Pour consulter ces valeurs localement, ouvrez le fichier config.yaml.Par défaut, le répertoire du run se trouve à l’emplacement ./wandb/run-<timestamp>-<run_id>.

Configurations à partir de fichiers

Si vous placez un fichier nommé config-defaults.yaml dans le même répertoire que votre script de run, le run récupère automatiquement les paires clé-valeur définies dans ce fichier et les transmet à wandb.Run.config. L’extrait de code suivant présente un exemple de fichier YAML config-defaults.yaml :

batch_size:
  desc: Size of each mini-batch
  value: 32

Vous pouvez remplacer les valeurs par défaut chargées automatiquement depuis config-defaults.yaml en indiquant de nouvelles valeurs dans l’argument config de wandb.init(). Par exemple :

import wandb

# Remplacer les valeurs de config-defaults.yaml en passant des valeurs personnalisées
with wandb.init(config={"epochs": 200, "batch_size": 64}) as run:
    ...

Pour charger un fichier de configuration autre que config-defaults.yaml, utilisez l’argument --configs command-line et indiquez le chemin du fichier :

python train.py --configs other-config.yaml

Dictionnaires imbriqués dans la configuration

Pour stocker des valeurs imbriquées dans une configuration de run, passez un dictionnaire imbriqué à wandb.init(). L’exemple suivant définit les dictionnaires imbriqués optimizer et training dans config :

config = {
    "optimizer": {
        "type": "adamw",
        "learning_rate": 0.0001,
        "weight_decay": 0.01,
    },
    "training": {
        "epochs": 20,
        "batch_size": 64,
    },
}

with wandb.init(project="project", config=config) as run:
    ...

Chaque clé de premier niveau doit contenir un champ value. Attribuez le dictionnaire imbriqué à value :

optimizer:
  value:
    type: adamw
    learning_rate: 0.0001
    weight_decay: 0.01

training:
  value:
    epochs: 20
    batch_size: 64

En Python, utilisez l’indexation de dictionnaire pour accéder aux valeurs imbriquées. L’exemple suivant récupère la valeur learning_rate dans le dictionnaire imbriqué de l’optimiseur de la configuration de run :

with wandb.init(project="project", config=config) as run:
    run.config["optimizer"]["learning_rate"]

Dans les contextes qui font référence aux valeurs de configuration par leur chemin, comme les filtres de l’API publique ou les expressions de graphiques en courbes, utilisez la notation pointée. Par exemple, utilisez config.optimizer.learning_rate dans un filtre de l’API publique et ${config:optimizer.learning_rate} dans une expression de graphique en courbes. L’exemple suivant crée un run avec une configuration imbriquée et journalise la perte à chaque époque d’entraînement. Il utilise ensuite l’API publique pour trouver les runs dont le taux d’apprentissage est de 1e-4, puis affiche le nom et le taux d’apprentissage de chacun d’eux.

import random
import wandb

config = {
    "optimizer": {
        "type": "adamw",
        "learning_rate": 1e-4,
        "weight_decay": 0.01,
    },
    "training": {
        "epochs": 3,
        "batch_size": 64,
    },
}

with wandb.init(project="nested-config-example", config=config) as run:
    lr = run.config["optimizer"]["learning_rate"]

    for epoch in range(run.config["training"]["epochs"]):
        loss = 1.0 / (epoch + 1) + random.random() * 0.05
        run.log({"epoch": epoch, "train/loss": loss})

api = wandb.Api()
runs = api.runs(
    "wandb/nested-config-example",
    filters={"config.optimizer.learning_rate": 1e-4},
)

for run in runs:
    print(run.name, run.config["optimizer"]["learning_rate"])

En pratique, on utilise généralement des scripts distincts pour créer les runs, puis pour les interroger ultérieurement à l’aide de filtres.

Exemple de cas d’usage des configurations basées sur des fichiers

Supposons que vous disposiez d’un fichier YAML contenant des métadonnées pour le run, ainsi que d’un dictionnaire d’hyperparamètres dans votre script Python. Vous pouvez enregistrer les deux dans l’objet config imbriqué :

hyperparameter_defaults = dict(
    dropout=0.5,
    batch_size=100,
    learning_rate=0.001,
)

config_dictionary = dict(
    yaml=my_yaml_file,
    params=hyperparameter_defaults,
)

with wandb.init(config=config_dictionary) as run:
    ...

Flags TensorFlow v1

Vous pouvez transmettre directement des flags TensorFlow à l’objet wandb.Run.config.

with wandb.init() as run:
    run.config.epochs = 4

    flags = tf.app.flags
    flags.DEFINE_string("data_dir", "/tmp/data")
    flags.DEFINE_integer("batch_size", 128, "Batch size.")
    run.config.update(flags.FLAGS)  # ajouter les flags TensorFlow à la configuration

​Définir la configuration d’une expérience

​Définir la configuration à l’initialisation

​Définir la configuration avec argparse

​Définir la configuration au fil de votre script

​Définir la configuration une fois votre run terminé

​Mettre en évidence les valeurs de configuration

​Afficher les valeurs de configuration

​Configurations à partir de fichiers

​Dictionnaires imbriqués dans la configuration

​Exemple de cas d’usage des configurations basées sur des fichiers

​Flags TensorFlow v1

Définir la configuration d’une expérience

Définir la configuration à l’initialisation

Définir la configuration avec argparse

Définir la configuration au fil de votre script

Définir la configuration une fois votre run terminé

Mettre en évidence les valeurs de configuration

Afficher les valeurs de configuration

Configurations à partir de fichiers

Dictionnaires imbriqués dans la configuration

Exemple de cas d’usage des configurations basées sur des fichiers

Flags TensorFlow v1