> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

# Aperçu

Un sweep associe une stratégie d’exploration des valeurs d’hyperparamètres au code qui les évalue. Cette stratégie peut être aussi simple que d’essayer chaque option, ou aussi complexe que l’optimisation bayésienne combinée à Hyperband ([BOHB](https://arxiv.org/abs/1807.01774)).

Ce guide explique comment définir une configuration de sweep qui précise les hyperparamètres à explorer, la stratégie de recherche à utiliser et la manière d’évaluer chaque run. Reportez-vous-y lorsque vous configurez un nouveau sweep ou que vous adaptez une configuration existante à une autre méthode de recherche ou à un autre espace de paramètres.

Définissez une configuration de sweep dans un [dictionnaire Python](https://docs.python.org/3/tutorial/datastructures.html#dictionaries) ou dans un fichier [YAML](https://yaml.org/). Le choix dépend de la manière dont vous souhaitez gérer votre sweep.

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

Les sections suivantes décrivent comment formater votre configuration de sweep. Consultez [Options de configuration de sweep](/fr/products/wandb/sweeps/sweep-config-keys) pour obtenir la liste complète des clés de premier niveau de la configuration de sweep.

<h2 id="basic-structure">
  Structure de base
</h2>

Les configurations de sweep se définissent en YAML ou à l’aide d’un dictionnaire Python, avec des paires clé-valeur et des structures imbriquées.

Utilisez des clés de premier niveau dans votre configuration de sweep pour définir les caractéristiques de la recherche effectuée par votre sweep, comme le nom du sweep ([`name`](/fr/products/wandb/sweeps/sweep-config-keys)), les paramètres à explorer ([`parameters`](/fr/products/wandb/sweeps/sweep-config-keys#parameters)) et la méthode de recherche ([`method`](/fr/products/wandb/sweeps/sweep-config-keys#method)).

Par exemple, les extraits de code suivants présentent la même configuration de sweep, définie dans un fichier YAML puis dans un dictionnaire Python. Cette configuration de sweep spécifie cinq clés de premier niveau : `program`, `name`, `method`, `metric` et `parameters`.

<Tabs>
  <Tab title="CLI">
    Pour gérer des sweeps de manière interactive depuis la ligne de commande, définissez une configuration de sweep dans un fichier YAML.

    ```yaml title="config.yaml" theme={"system"}
    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"]
    ```
  </Tab>

  <Tab title="Script Python ou notebook">
    Si vous définissez votre algorithme d’entraînement dans un script Python ou un notebook, définissez votre sweep dans un dictionnaire Python.

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

    ```python title="train.py" theme={"system"}
    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"]},
        },
    }
    ```
  </Tab>
</Tabs>

La clé de premier niveau `parameters` contient les clés imbriquées suivantes : `learning_rate`, `batch_size`, `epochs` et `optimizer`. Pour chaque clé imbriquée que vous spécifiez, vous pouvez fournir une ou plusieurs valeurs, une distribution, une probabilité, etc. Pour plus d’informations, voir la section [parameters](/fr/products/wandb/sweeps/sweep-config-keys#parameters) de la page [Options de configuration de sweep](/fr/products/wandb/sweeps/sweep-config-keys).

<h2 id="double-nested-parameters">
  Paramètres doublement imbriqués
</h2>

Utilisez des paramètres imbriqués pour regrouper des hyperparamètres apparenté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 présente une configuration de sweep comportant les paramètres imbriqués `nested_category_1`, `nested_category_2` et `nested_category_3`, qui contiennent chacun les paramètres supplémentaires `momentum` et `weight_decay`. Les exemples de code ci-dessous présentent cette configuration sous forme de fichier YAML et de dictionnaire Python :

<Tabs>
  <Tab title="CLI">
    ```yaml theme={"system"}
    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]
    ```
  </Tab>

  <Tab title="Script Python ou notebook">
    ```python theme={"system"}
    {
      "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]
            }
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Warning>
  Les paramètres imbriqués définis dans la configuration de sweep écrasent les clés spécifiées dans la configuration d’un run W\&B.

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

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

  Votre configuration de sweep définit des paramètres imbriqués sous une clé `"parameters"` de premier niveau :

  ```python theme={"system"}
  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)
  ```

  Pendant un run de sweep, `run.config["nested_param"]` contient la sous-arborescence définie par la configuration de sweep (`learning_rate` et `double_nested_param`), mais pas `manual_key`, défini dans `wandb.init(config=...)`.
</Warning>

<h2 id="sweep-configuration-template">
  Modèle de configuration de sweep
</h2>

Utilisez ce modèle comme point de départ pour une nouvelle configuration de sweep. Il présente les schémas les plus courants pour la définition des paramètres et l’arrêt anticipé. Remplacez `hyperparameter_name` par le nom de votre hyperparamètre, ainsi que toutes les valeurs entre crochets.

```yaml title="config.yaml" theme={"system"}
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](#macro-and-custom-command-arguments-example).

<h2 id="sweep-configuration-examples">
  Exemples de configuration de sweep
</h2>

Les configurations de sweep suivantes illustrent des scénarios courants. Inspirez-vous-en pour adapter un sweep à votre propre script d’entraînement.

<Tabs>
  <Tab title="CLI">
    ```yaml title="config.yaml" theme={"system"}
    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"]
    ```
  </Tab>

  <Tab title="Script Python ou notebook">
    ```python title="train.py" theme={"system"}
    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"]},
        },
    }
    ```
  </Tab>
</Tabs>

<h3 id="bayes-hyperband-example">
  Exemple Bayes avec Hyperband
</h3>

L’exemple suivant combine la recherche bayésienne et l’arrêt anticipé Hyperband afin d’interrompre tôt les runs peu performants et de réserver les ressources aux configurations plus prometteuses.

```yaml theme={"system"}
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 suivants montrent comment spécifier un nombre minimum ou maximum d’itérations pour `early_terminate` :

<Tabs>
  <Tab title="Nombre minimum d’itérations">
    Dans cet exemple, les paliers (brackets) sont `[3, 3*eta, 3*eta*eta, 3*eta*eta*eta]`, soit `[3, 9, 27, 81]`.

    ```yaml theme={"system"}
    early_terminate:
      type: hyperband
      min_iter: 3
    ```
  </Tab>

  <Tab title="Nombre maximum d’itérations">
    Dans cet exemple, les paliers (brackets) sont `[27/eta, 27/eta/eta]`, soit `[9, 3]`.

    ```yaml theme={"system"}
    early_terminate:
      type: hyperband
      max_iter: 27
      s: 2
    ```
  </Tab>
</Tabs>

<h3 id="macro-and-custom-command-arguments-example">
  Exemple de macros et d’arguments de commande personnalisés
</h3>

Cet exemple montre comment construire la commande que l’agent de sweep exécute pour chaque essai lorsque vous avez besoin d’un contrôle plus fin que celui offert par l’invocation par défaut.

Pour des arguments de ligne de commande plus complexes, vous pouvez utiliser des macros afin de transmettre des variables d’environnement, l’interpréteur Python et des arguments supplémentaires. [W\&B prend en charge des macros prédéfinies](/fr/products/wandb/sweeps/sweep-config-keys#command-macros) ainsi que des arguments de ligne de commande personnalisés, que vous pouvez spécifier dans votre configuration de sweep.

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

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

```yaml title="sweep.yaml" theme={"system"}
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 ligne de commande à l’aide du module `argparse` :

```python title="run.py" theme={"system"}
# 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})
```

Consultez la section [Macros de commande](/fr/products/wandb/sweeps/sweep-config-keys#command-macros) de la page [Options de configuration de sweep](/fr/products/wandb/sweeps/sweep-config-keys) pour obtenir la liste des macros prédéfinies que vous pouvez utiliser dans votre configuration de sweep.

<h4 id="boolean-arguments">
  Arguments booléens
</h4>

Si votre sweep transmet des flags booléens via les arguments de commande, votre script d'entraînement nécessite une gestion supplémentaire, car `argparse` n'interprète pas par défaut les chaînes booléennes.

Par défaut, le module `argparse` ne prend pas en charge les arguments booléens. Pour définir un argument booléen, utilisez le paramètre [`action`](https://docs.python.org/3/library/argparse.html#action) ou une fonction personnalisée qui convertit la représentation textuelle 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` :

```python theme={"system"}
import wandb
import argparse

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

args.test  # Vaut True si --test est fourni, sinon False
```

Vous pouvez également définir une fonction personnalisée pour convertir la représentation sous forme de chaîne de caractères 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 :

```python theme={"system"}
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')
```