Configurer Experiments

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

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

La propriété wandb.Run.config facilite l’analyse de vos expériences et la reproduction de votre travail par la suite. Vous pouvez regrouper vos données selon les valeurs de configuration dans l’application W&B, comparer les configurations de différents runs W&B et évaluer l’effet de chaque configuration d’entraînement sur les résultats. La propriété config est un objet de type dictionnaire qui peut être construit à partir de plusieurs objets de type dictionnaire.

Pour enregistrer les métriques de sortie ou des variables dépendantes comme la perte et l’accuracy, utilisez wandb.Run.log() plutôt que wandb.Run.config.

Configurer la configuration d’une expérience

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

Définir la configuration à l’initialisation

Passez un dictionnaire au début de votre script lorsque vous appelez l’API wandb.init() pour créer un processus en arrière-plan chargé de synchroniser et de journaliser les données dans un run W&B. L’extrait de code suivant montre comment définir un dictionnaire Python avec des valeurs de configuration et comment passer ce dictionnaire en argument lorsque vous initialisez un run W&B.

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,
}

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

Si vous passez un dictionnaire imbriqué comme config, W&B aplatit les noms en utilisant des points. Accédez aux valeurs du dictionnaire comme à celles de tout autre dictionnaire en Python :

# Accéder aux valeurs avec 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() du dictionnaire Python
hidden_layer_sizes = run.config.get("hidden_layer_sizes")
kernel_sizes = run.config.get("kernel_sizes")
activation = run.config.get("activation")

Tout au long du Guide du développeur et des exemples, nous copions les valeurs de configuration dans des variables distinctes. Cette étape est facultative. Cela est fait pour plus de lisibilité.

Définir la configuration avec argparse

Vous pouvez définir votre configuration avec un objet argparse. argparse, abréviation de « analyseur d’arguments », est un module de la bibliothèque standard de Python 3.2 et versions ultérieures qui facilite l’écriture de scripts tirant parti de toute la flexibilité et de la puissance des arguments en ligne de commande. Cela est utile pour suivre les résultats de scripts lancés en ligne de commande. Le script Python suivant montre comment créer un objet parser afin de définir et de 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 à des fins de 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 la journalisation des valeurs vers 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éfinissez la configuration au fil de votre script

Vous pouvez ajouter d’autres paramètres à votre objet de configuration au fil 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,
}

# Passer 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 après l'initialisation de W&B
    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,
    )

Assurez-vous de définir allow_val_change=True si vous souhaitez mettre à jour la valeur d’une clé existante. Si vous ne définissez pas ce paramètre, W&B renverra une erreur si vous essayez de mettre à jour la valeur d’une clé existante.

Définissez 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 entité, le nom du projet et l’ID du run. Vous trouverez ces informations dans l’objet Run ou dans la W&B App :

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

# Trouvez les valeurs suivantes dans l'objet Run s'il a été initié depuis le
# script ou le notebook actuel, 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 wandb.init().
api = wandb.Api()
api_run = api.run(f"{username}/{project}/{run_id}")
api_run.config["bar"] = 32
api_run.update()

Mettre en avant 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 utilisez un tableau de bord Grafana pour surveiller des runs d’entraînement, 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:
    # Ajouter la clé de configuration "grafana_url" à la section References.
    run.pin_config_keys(["grafana_url"])

Afficher les valeurs de configuration

Accédez à vos valeurs de configuration dans W&B App, pendant l’exécution d’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

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

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

Le format JSON brut est utile pour écrire des expressions qui permettent de créer ou de transformer des graphiques en courbes à partir de valeurs de configuration, de métriques enregistrées ou de valeurs de synthèse. Voir Expressions pour plus de détails.

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 dictionnaire contenant les paires clé-valeur de configuration.L’exemple suivant montre comment accéder aux valeurs de configuration d’un run pendant son exécution. Remplacez les valeurs du dictionnaire config par vos propres hyperparamètres, l’architecture de votre modèle, le nom du jeu de données et d’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 à quoi peut ressembler la sortie de 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 précédemment enregistré. Transmettez l’entité, le nom du projet et l’ID du run à wandb.Api.run(), puis accédez à la configuration du run via la propriété wandb.Api.Run.config.Remplacez "<entity>", "<project>" et "<run_id>" dans l’exemple suivant par votre entité 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, utilisez wandb.Api.runs() pour récupérer les 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 à quoi peut ressembler la sortie de 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 d’un run dans le fichier config.yaml du répertoire du run. Pour lire les valeurs de configuration localement, ouvrez le fichier config.yaml.Par défaut, le répertoire du run se trouve à l’emplacement ./wandb/run-<timestamp>-<run_id>.

Configurations basées sur des fichiers

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

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

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

import wandb

# Surcharger 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 config

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é optimizer de la configuration de run :

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

Dans les contextes qui référencent les valeurs de configuration par chemin, comme les filtres de l’API publique ou les expressions de graphiques en courbes, utilisez la notation par points. 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 pour chaque époque d’entraînement. Il utilise ensuite l’API publique pour trouver les runs dont le taux d’apprentissage est de 1e-4 et affiche le nom et le taux d’apprentissage de chaque run.

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, vous utilisez généralement des scripts distincts pour créer les runs, puis pour les interroger ultérieurement à l’aide de filtres.

Exemple d’utilisation de configurations basées sur des fichiers

Supposons que vous disposiez d’un fichier YAML contenant des métadonnées sur 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 de TensorFlow v1

Vous pouvez transmettre directement les 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

Guides

Intégrations

Référence

Configurer la configuration d’une expérience

Définir la configuration à l’initialisation

Définir la configuration avec argparse

Définissez la configuration au fil de votre script

Définissez la configuration une fois votre run terminé

Mettre en avant les valeurs de configuration

Afficher les valeurs de configuration

Configurations basées sur des fichiers

Dictionnaires imbriqués dans config

Exemple d’utilisation de configurations basées sur des fichiers

Flags de TensorFlow v1

​Configurer la configuration d’une expérience

​Définir la configuration à l’initialisation

​Définir la configuration avec argparse

​Définissez la configuration au fil de votre script

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

​Mettre en avant les valeurs de configuration

​Afficher les valeurs de configuration

​Configurations basées sur des fichiers

​Dictionnaires imbriqués dans config

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

​Flags de TensorFlow v1

Configurer la configuration d’une expérience

Définir la configuration à l’initialisation

Définir la configuration avec argparse

Définissez la configuration au fil de votre script

Définissez la configuration une fois votre run terminé

Mettre en avant les valeurs de configuration

Afficher les valeurs de configuration

Configurations basées sur des fichiers

Dictionnaires imbriqués dans config

Exemple d’utilisation de configurations basées sur des fichiers

Flags de TensorFlow v1