Aperçu

Un balayage 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). Ce guide vous montre comment définir une configuration de balayage qui précise quels hyperparamètres rechercher, quelle stratégie de recherche utiliser et comment évaluer chaque run. Utilisez-le lorsque vous configurez un nouveau balayage ou adaptez une configuration existante à une autre méthode de recherche ou à un autre espace de paramètres. 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.

Les sections suivantes décrivent 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 configurations de balayage sont définies soit à l’aide de YAML, soit d’un dictionnaire Python, avec 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 name du balayage, les parameters à explorer et la method de recherche. 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. La configuration de balayage spécifie cinq clés de premier niveau : program, name, method, metric et parameters.

CLI
Script Python ou notebook

Pour gérer des balayages de manière interactive depuis la ligne de commande, définissez une configuration de balayage dans un fichier YAML.

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"]

Définissez un balayage dans un dictionnaire Python si vous définissez votre 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"]},
    },
}

La clé parameters de premier niveau contient les clés imbriquées suivantes : learning_rate, batch_size, epochs 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

Utilisez des paramètres imbriqués lorsque vous souhaitez regrouper des hyperparamètres associés ou lorsque votre code d’entraînement attend une structure de configuration imbriquée. Pour définir un paramètre imbriqué, ajoutez une clé parameters supplémentaire sous le nom du paramètre de premier niveau. L’exemple suivant montre une configuration de balayage avec les paramètres imbriqués nested_category_1, nested_category_2 et nested_category_3, chacun contenant les paramètres supplémentaires momentum et weight_decay. Les exemples de code suivants montrent la configuration dans un fichier YAML et dans un dictionnaire Python :

CLI
Script Python ou 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]

{
  "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é "parameters" de premier niveau :

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 et double_nested_param). Il n’inclut pas manual_key, qui est défini dans wandb.init(config=...).

Modèle de configuration d’un balayage

Utilisez ce modèle comme point de départ pour une nouvelle configuration de balayage. Il illustre les modèles de paramètre et d’arrêt anticipé les plus courants. Remplacez hyperparameter_name par le nom de votre hyperparamètre, ainsi que par toutes les valeurs entre crochets.

config.yaml

program: [INSERT]
method: [INSERT]
parameters:
  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: [INSERT]
  eta: [INSERT]
  max_iter: [INSERT]
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. Pour plus d’informations, voir Exemple d’arguments de macro et de commande personnalisée.

Exemples de configuration de balayage

Les configurations de balayage suivantes illustrent des scénarios courants. Utilisez-les comme références lorsque vous adaptez un balayage à votre propre script d’entraînement.

CLI
Script Python ou notebook

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"]

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

L’exemple suivant combine la recherche bayésienne avec l’arrêt anticipé Hyperband afin d’interrompre rapidement les runs les moins performants et de préserver les ressources pour des configurations plus prometteuses.

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 minimal d'itérations
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

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

Cet exemple montre comment construire la commande que l’agent de balayage exécute pour chaque essai lorsque vous avez besoin d’un contrôle plus précis que celui fourni par l’invocation par défaut. 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


def str2bool(v: str) -> bool:
    """Convert a string such as "True" to a boolean, because argparse
    doesn't support boolean arguments by default.
    """
    if isinstance(v, bool):
        return v
    return v.lower() in ('yes', 'true', 't', '1')


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(project="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

Si votre balayage transmet des indicateurs booléens via des arguments de commande, votre script d’entraînement nécessite une gestion supplémentaire, car argparse n’interprète pas les chaînes booléennes par défaut. 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  # Vaudra True si --test est fourni, 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 doesn't support boolean arguments by default.
  """
  if isinstance(v, bool):
      return v
  return v.lower() in ('yes', 'true', 't', '1')

Guides

Intégrations

Référence

Structure de base

Paramètres imbriqués sur deux niveaux

Modèle de configuration d’un balayage

Exemples de configuration de balayage

Exemple avec Bayes Hyperband

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

Arguments booléens

​Structure de base

​Paramètres imbriqués sur deux niveaux

​Modèle de configuration d’un balayage

​Exemples de configuration de balayage

​Exemple avec Bayes Hyperband

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

​Arguments booléens

Structure de base

Paramètres imbriqués sur deux niveaux

Modèle de configuration d’un balayage

Exemples de configuration de balayage

Exemple avec Bayes Hyperband

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

Arguments booléens