Aperçu

Découvrez comment créer des fichiers de configuration pour les balayages.

Un balayage W&B combine une stratégie d’exploration des valeurs d’hyperparamètres avec le code qui les évalue. Cette stratégie peut être aussi simple que d’essayer chaque option, ou aussi complexe que l’optimisation bayésienne et Hyperband (BOHB).

Définissez la configuration de votre balayage soit dans un dictionnaire Python, soit dans un fichier YAML. La façon de définir cette configuration dépend de la manière dont vous souhaitez gérer votre balayage.

Définissez la configuration de votre balayage dans un fichier YAML si vous souhaitez initialiser un balayage et démarrer un agent de balayage depuis la ligne de commande. Définissez votre balayage dans un dictionnaire Python si vous initialisez un balayage et démarrez un agent de balayage entièrement dans un script ou notebook Python.

Le guide suivant décrit comment formater la configuration de votre balayage. Voir Sweep configuration options pour une liste complète des clés de configuration de balayage de premier niveau.

​

Structure de base

Les deux formats de configuration de balayage (YAML et dictionnaire Python) utilisent des paires clé-valeur et des structures imbriquées.

Utilisez les clés de premier niveau de votre configuration de balayage pour définir les propriétés de votre recherche, comme le nom du balayage (clé name), les paramètres à explorer (clé parameters), la méthode de recherche dans l’espace des paramètres (clé method), etc.

Par exemple, les extraits de code ci-dessous montrent la même configuration de balayage définie dans un fichier YAML et dans un dictionnaire Python. Cette configuration comporte cinq clés de premier niveau : program, name, method, metric et parameters.

CLI

Définissez une configuration de balayage dans un fichier YAML si vous souhaitez gérer des balayages de manière interactive depuis la ligne de commande (CLI)

config.yaml

program: train.py
name: sweepdemo
method: bayes
metric:
  goal: minimize
  name: validation_loss
parameters:
  learning_rate:
    min: 0.0001
    max: 0.1
  batch_size:
    values: [16, 32, 64]
  epochs:
    values: [5, 10, 15]
  optimizer:
    values: ["adam", "sgd"]

Python script or notebook

Définissez un balayage dans un dictionnaire Python si vous définissez l’algorithme d’entraînement dans un script ou notebook Python.

L’extrait de code suivant stocke une configuration de balayage dans une variable nommée sweep_configuration :

train.py

sweep_configuration = {
    "name": "sweepdemo",
    "method": "bayes",
    "metric": {"goal": "minimize", "name": "validation_loss"},
    "parameters": {
        "learning_rate": {"min": 0.0001, "max": 0.1},
        "batch_size": {"values": [16, 32, 64]},
        "epochs": {"values": [5, 10, 15]},
        "optimizer": {"values": ["adam", "sgd"]},
    },
}

Dans la clé parameters de premier niveau, les clés suivantes sont imbriquées : learning_rate, batch_size, epoch et optimizer. Pour chacune des clés imbriquées que vous définissez, vous pouvez fournir une ou plusieurs valeurs, une distribution, une probabilité, etc. Pour plus d’informations, voir la section parameters de Sweep configuration options.

​

Paramètres imbriqués sur deux niveaux

Les configurations de balayage prennent en charge les paramètres imbriqués. Pour définir un paramètre imbriqué, ajoutez une clé parameters supplémentaire sous le nom du paramètre de niveau supérieur.

L’exemple suivant montre une configuration de balayage avec trois paramètres imbriqués : nested_category_1, nested_category_2 et nested_category_3. Chaque paramètre imbriqué contient deux paramètres supplémentaires : momentum et weight_decay.

nested_category_1, nested_category_2 et nested_category_3 sont des espaces réservés. Remplacez-les par des noms adaptés à votre cas d’usage.

Les extraits de code suivants montrent comment définir des paramètres imbriqués dans un fichier YAML et dans un dictionnaire Python.

CLI

program: sweep_nest.py
name: nested_sweep
method: random
metric:
  name: loss
  goal: minimize
parameters:
  optimizer:
    values: ['adam', 'sgd']
  fc_layer_size:
    values: [128, 256, 512]
  dropout:
    values: [0.3, 0.4, 0.5]
  epochs:
    value: 1
  learning_rate:
    distribution: uniform
    min: 0
    max: 0.1
  batch_size:
    distribution: q_log_uniform_values
    q: 8
    min: 32
    max: 256
  nested_category_1:
    parameters:
      momentum:
        distribution: uniform
        min: 0.0
        max: 0.9
      weight_decay:
        values: [0.0001, 0.0005, 0.001]
  nested_category_2:
    parameters:
      momentum:
        distribution: uniform
        min: 0.0
        max: 0.9
      weight_decay:
        values: [0.1, 0.2, 0.3]
  nested_category_3:
    parameters:
      momentum:
        distribution: uniform
        min: 0.5
        max: 0.7
      weight_decay:
        values: [0.2, 0.3, 0.4]

Python script or notebook

{
  "program": "sweep_nest.py",
  "name": "nested_sweep",
  "method": "random",
  "metric": {
    "name": "loss",
    "goal": "minimize"
  },
  "parameters": {
    "optimizer": {
      "values": ["adam", "sgd"]
    },
    "fc_layer_size": {
      "values": [128, 256, 512]
    },
    "dropout": {
      "values": [0.3, 0.4, 0.5]
    },
    "epochs": {
      "value": 1
    },
    "learning_rate": {
      "distribution": "uniform",
      "min": 0,
      "max": 0.1
    },
    "batch_size": {
      "distribution": "q_log_uniform_values",
      "q": 8,
      "min": 32,
      "max": 256
    },
    "nested_category_1": {
      "parameters": {
        "momentum": {
          "distribution": "uniform",
          "min": 0.0,
          "max": 0.9
        },
        "weight_decay": {
          "values": [0.0001, 0.0005, 0.001]
        }
      }
    },
    "nested_category_2": {
      "parameters": {
        "momentum": {
          "distribution": "uniform",
          "min": 0.0,
          "max": 0.9
        },
        "weight_decay": {
          "values": [0.1, 0.2, 0.3]
        }
      }
    },
    "nested_category_3": {
      "parameters": {
        "momentum": {
          "distribution": "uniform",
          "min": 0.5,
          "max": 0.7
        },
        "weight_decay": {
          "values": [0.2, 0.3, 0.4]
        }
      }
    }
  }
}

Les paramètres imbriqués définis dans la configuration du balayage écrasent les clés spécifiées dans une configuration de run W&B.

Par exemple, supposons que vous ayez un script train.py qui initialise un run avec une valeur imbriquée par défaut :

def main():
    with  wandb.init(config={"nested_param": {"manual_key": 1}}) as run:
        # Votre code d'entraînement ici

Votre configuration de balayage définit des paramètres imbriqués sous une clé racine "parameters" :

sweep_configuration = {
    "method": "grid",
    "metric": {"name": "score", "goal": "minimize"},
    "parameters": {
        "top_level_param": {"value": 0},
        "nested_param": {
            "parameters": {
                "learning_rate": {"value": 0.01},
                "double_nested_param": {
                    "parameters": {"x": {"value": 0.9}, "y": {"value": 0.8}}
                },
            }
        },
    },
}

sweep_id = wandb.sweep(sweep=sweep_configuration, project="<project>")
wandb.agent(sweep_id, function=main, count=4)

Lors d’un run de balayage, run.config["nested_param"] reflète le sous-arbre défini par la configuration du balayage (learning_rate, double_nested_param) et n’inclut pas manual_key défini dans wandb.init(config=...).

​

Modèle de configuration de balayage

Le modèle suivant montre comment configurer des paramètres et définir des contraintes de recherche. Remplacez hyperparameter_name par le nom de votre hyperparamètre, ainsi que chaque valeur indiquée entre <>.

config.yaml

program: <insert>
method: <insert>
parameter:
  hyperparameter_name0:
    value: 0  
  hyperparameter_name1: 
    values: [0, 0, 0]
  hyperparameter_name: 
    distribution: <insert>
    value: <insert>
  hyperparameter_name2:  
    distribution: <insert>
    min: <insert>
    max: <insert>
    q: <insert>
  hyperparameter_name3: 
    distribution: <insert>
    values:
      - <list_of_values>
      - <list_of_values>
      - <list_of_values>
early_terminate:
  type: hyperband
  s: 0
  eta: 0
  max_iter: 0
command:
- ${Command macro}
- ${Command macro}
- ${Command macro}
- ${Command macro}      

Pour exprimer une valeur numérique en notation scientifique, ajoutez l’opérateur YAML !!float, qui convertit la valeur en nombre à virgule flottante. Par exemple, min: !!float 1e-5. Voir Exemple de commande.

​

Exemples de configuration de balayage

CLI

config.yaml

program: train.py
method: random
metric:
  goal: minimize
  name: loss
parameters:
  batch_size:
    distribution: q_log_uniform_values
    max: 256 
    min: 32
    q: 8
  dropout: 
    values: [0.3, 0.4, 0.5]
  epochs:
    value: 1
  fc_layer_size: 
    values: [128, 256, 512]
  learning_rate:
    distribution: uniform
    max: 0.1
    min: 0
  optimizer:
    values: ["adam", "sgd"]

Python script or notebook

train.py

sweep_config = {
    "method": "random",
    "metric": {"goal": "minimize", "name": "loss"},
    "parameters": {
        "batch_size": {
            "distribution": "q_log_uniform_values",
            "max": 256,
            "min": 32,
            "q": 8,
        },
        "dropout": {"values": [0.3, 0.4, 0.5]},
        "epochs": {"value": 1},
        "fc_layer_size": {"values": [128, 256, 512]},
        "learning_rate": {"distribution": "uniform", "max": 0.1, "min": 0},
        "optimizer": {"values": ["adam", "sgd"]},
    },
}

​

Exemple avec Bayes Hyperband

program: train.py
method: bayes
metric:
  goal: minimize
  name: val_loss
parameters:
  dropout:
    values: [0.15, 0.2, 0.25, 0.3, 0.4]
  hidden_layer_size:
    values: [96, 128, 148]
  layer_1_size:
    values: [10, 12, 14, 16, 18, 20]
  layer_2_size:
    values: [24, 28, 32, 36, 40, 44]
  learn_rate:
    values: [0.001, 0.01, 0.003]
  decay:
    values: [1e-5, 1e-6, 1e-7]
  momentum:
    values: [0.8, 0.9, 0.95]
  epochs:
    value: 27
early_terminate:
  type: hyperband
  s: 2
  eta: 3
  max_iter: 27

Les onglets ci-dessous montrent comment spécifier un nombre minimal ou maximal d’itérations pour early_terminate :

Nombre maximal d'itérations

Les paliers de cet exemple sont : [3, 3*eta, 3*eta*eta, 3*eta*eta*eta], ce qui correspond à [3, 9, 27, 81].

early_terminate:
  type: hyperband
  min_iter: 3

Nombre minimal d'itérations

Les paliers de cet exemple sont [27/eta, 27/eta/eta], ce qui correspond à [9, 3].

early_terminate:
  type: hyperband
  max_iter: 27
  s: 2

​

Exemple de macros et d’arguments de ligne de commande personnalisés

Pour des arguments de ligne de commande plus complexes, vous pouvez utiliser des macros pour transmettre des variables d’environnement, l’interpréteur Python et des arguments supplémentaires. W&B prend en charge des macros prédéfinies ainsi que des arguments de ligne de commande personnalisés que vous pouvez définir dans votre configuration de balayage.

Par exemple, la configuration de balayage suivante (sweep.yaml) définit une commande qui exécute un script Python (run.py), les macros ${env}, ${interpreter} et ${program} étant remplacées par les valeurs appropriées lors de l’exécution du balayage.

Les arguments --batch_size=${batch_size}, --test=True et --optimizer=${optimizer} utilisent des macros personnalisées pour transmettre les valeurs des paramètres batch_size, test et optimizer définis dans la configuration de balayage.

sweep.yaml

program: run.py
method: random
metric:
  name: validation_loss
parameters:
  learning_rate:
    min: 0.0001
    max: 0.1
command:
  - ${env}
  - ${interpreter}
  - ${program}
  - "--batch_size=${batch_size}"
  - "--optimizer=${optimizer}"
  - "--test=True"

Le script Python associé (run.py) peut ensuite analyser ces arguments de la ligne de commande à l’aide du module argparse.

run.py

# run.py  
import wandb
import argparse

parser = argparse.ArgumentParser()
parser.add_argument('--batch_size', type=int)
parser.add_argument('--optimizer', type=str, choices=['adam', 'sgd'], required=True)
parser.add_argument('--test', type=str2bool, default=False)
args = parser.parse_args()

# Initialiser un Run W&B
with wandb.init('test-project') as run:
    run.log({'validation_loss':1})

Voir la section Macros de commande de Sweep configuration options pour consulter la liste des macros prédéfinies que vous pouvez utiliser dans votre configuration de balayage.

​

Arguments booléens

Le module argparse ne prend pas en charge les arguments booléens par défaut. Pour définir un argument booléen, vous pouvez utiliser le paramètre action ou une fonction personnalisée pour convertir la représentation sous forme de chaîne de la valeur booléenne en type booléen.

Par exemple, vous pouvez utiliser l’extrait de code suivant pour définir un argument booléen. Passez store_true ou store_false comme argument à ArgumentParser.

import wandb
import argparse

parser = argparse.ArgumentParser()
parser.add_argument('--test', action='store_true')
args = parser.parse_args()

args.test  # Sera True si --test est passé, sinon False

Vous pouvez également définir une fonction personnalisée pour convertir la représentation textuelle d’une valeur booléenne en type booléen. Par exemple, l’extrait de code suivant définit la fonction str2bool, qui convertit une chaîne en valeur booléenne.

def str2bool(v: str) -> bool:
  """Convert a string to a boolean. This is required because
  argparse does not support boolean arguments by default.
  """
  if isinstance(v, bool):
      return v
  return v.lower() in ('yes', 'true', 't', '1')