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

# Configurer un moteur d’optimisation

Choisissez un moteur d’optimisation pour Weights & Biases Sweeps. Utilisez le moteur intégré de Weights & Biases pour une recherche aléatoire, par grille ou bayésienne, ou bien Optuna ou Ax pour tirer parti de leurs algorithmes de recherche et de leurs options de personnalisation.

Le moteur, l’ordonnanceur et les agents de sweep fonctionnent de concert :

| Composant | Rôle |
| - | - |
| Moteur d’optimisation | Propose des configurations d’hyperparamètres et, selon la stratégie de recherche, s’appuie sur les résultats des runs pour orienter la recherche. |
| Ordonnanceur de sweeps | Demande des configurations au moteur, les soumet à Weights & Biases et transmet les résultats des runs au moteur. |
| Agent de sweep | Récupère auprès de Weights & Biases les configurations qui lui sont attribuées et exécute votre code d’entraînement. |

Cette page explique comment configurer un moteur pour un ordonnanceur exécuté dans votre propre environnement. Pour des exemples YAML complets, voir [Exemples d’ordonnanceur de sweeps](https://docs.coreweave.com/fr/products/wandb/sweeps/define-sweep-configuration.md#sweep-scheduler-examples).

## Choisir un moteur

Choisissez un moteur en fonction des méthodes de recherche et des options de personnalisation dont vous avez besoin :

| Moteur | Description |
| - | - |
| Weights & Biases (intégré) | Recherche aléatoire, par grille ou bayésienne, configurée à l’aide des clés de la configuration de sweep. |
| [Optuna](https://optuna.org/) | Framework open source d’optimisation des hyperparamètres, doté d’échantillonneurs et d’élagueurs configurables. |
| [Ax](https://ax.dev/) | Plateforme open source d’expérimentation adaptative, dotée de stratégies de génération et d’arrêt configurables. |

Utilisez Optuna ou Ax pour :

* [Définir plusieurs objectifs](#define-multiple-objectives) et optimiser ainsi plusieurs métriques.
* [Définir une fonction d’arrêt personnalisée au niveau du sweep](#stop-the-sweep) pour contrôler le moment où l’ordonnanceur cesse de proposer de nouveaux runs.

Avec Optuna, vous pouvez également [définir un espace de recherche conditionnel](#define-a-conditional-search-space) pour sélectionner des paramètres en fonction des choix précédents au sein d’un même essai.

## Installer les dépendances

Installez la version 0.31.0 ou ultérieure du SDK Python de Weights & Biases avec les dépendances supplémentaires propres à votre moteur. Lancez la commande d’installation dans l’environnement où s’exécute l’ordonnanceur.

> [tab] Weights & Biases
>
> Utilisez Python 3.10 ou une version ultérieure. Installez le SDK avec l’extra `sweeps` afin d’inclure `sweeps>=0.2.0` dans l’environnement de l’ordonnanceur :
>
> ```bash theme={"system"}
> pip install "wandb[sweeps]>=0.31.0"
> ```

> [tab] Optuna
>
> Utilisez Python 3.10 ou une version ultérieure. Installez le SDK avec l’extra `optuna` afin d’inclure `optuna>=4.0.0` dans l’environnement de l’ordonnanceur :
>
> ```bash theme={"system"}
> pip install "wandb[optuna]>=0.31.0"
> ```
>
> Pour utiliser l’exemple OptunaHub Terminator présenté sur cette page, installez également `optunahub` :
>
> ```bash theme={"system"}
> pip install optunahub
> ```

> [tab] Ax
>
> Utilisez Python 3.11 ou une version ultérieure. Installez le SDK avec l’extra `ax` afin d’inclure `ax-platform>=1.3.1` dans l’environnement de l’ordonnanceur :
>
> ```bash theme={"system"}
> pip install "wandb[ax]>=0.31.0"
> ```

## Configurer l’optimisation

Configurez la stratégie de recherche, les objectifs et l’espace de recherche de votre moteur. Le moteur Weights & Biases intégré utilise la configuration de sweep. Pour Optuna et Ax, vous pouvez fournir une fonction Python qui configure une étude Optuna ou un client Ax.

### Configurer la stratégie de recherche

Définissez `scheduler.engine` sur `wandb`, `optuna` ou `ax`.

Pour Optuna et Ax, les fonctions d’optimiseur personnalisées sont facultatives. Vous pouvez changer de moteur en modifiant `scheduler.engine`, tout en utilisant l’espace de recherche et les objectifs définis dans la configuration de sweep, y compris les objectifs multiples définis avec `metrics`.

Pour utiliser une fonction d’optimiseur personnalisée, définissez `scheduler.source` sur le nom de votre fichier Python et `scheduler.optimizer` sur le nom de la fonction. Pour Optuna, vous pouvez également définir un espace de recherche personnalisé avec `scheduler.search_space`.

> [tab] Weights & Biases
>
> Configurez le moteur intégré de Weights & Biases à l’aide d’une configuration de sweep.
>
> Définissez `method` sur `random`, `grid` ou `bayes`. Le moteur s’appuie sur `method`, `metric` et `parameters` pour sélectionner les configurations des runs du sweep.
>
> Par exemple, pour configurer une recherche bayésienne avec le moteur intégré de Weights & Biases :
>
> ```yaml title="sweep.yaml" theme={"system"}
> program: train.py
> method: bayes
> metric:
>   name: validation_loss
>   goal: minimize
> parameters:
>   learning_rate:
>     min: 0.0001
>     max: 0.01
>   batch_size:
>     values: [16, 32, 64]
> scheduler:
>   engine: wandb
> ```
>
> Pour en savoir plus sur chaque méthode de recherche, consultez [Méthodes de recherche](https://docs.coreweave.com/fr/products/wandb/sweeps/sweep-config-keys.md#method).

> [tab] Optuna
>
> Pour personnaliser l’optimiseur, définissez une fonction qui accepte un argument `SweepInfo` et renvoie un objet `Study` Optuna.
>
> Par exemple, supposons que vous disposiez de la configuration de sweep suivante :
>
> ```yaml title="sweep.yaml" theme={"system"}
> program: train.py
>
> # Requis par le schéma de sweep W&B, mais l’ordonnanceur Optuna
> # contrôle la stratégie de recherche.
> method: random
>
> metric:
>   name: val_loss
>   goal: minimize
>
> parameters:
>   n_estimators:
>     min: 20
>     max: 200
>   max_depth:
>     min: 2
>     max: 20
>   min_samples_split:
>     min: 0.01
>     max: 0.5
>
> # Arrêter après 100 runs au maximum, même si le Terminator
> # n’a pas détecté la convergence avant.
> run_cap: 100
>
> scheduler:
>   engine: optuna
>   source: optimizer.py
>   optimizer: create_optimizer
> ```
>
> Dans `optimizer.py`, créez une étude avec un échantillonneur TPE, puis renvoyez-la avec la fonction d’arrêt du Terminator :
>
> ```python title="optimizer.py" theme={"system"}
> import optuna
> import optunahub
>
> terminator_module = optunahub.load_module("callbacks/terminator")
>
> EMMREvaluator = terminator_module.EMMREvaluator
> MedianErrorEvaluator = terminator_module.MedianErrorEvaluator
> Terminator = terminator_module.Terminator
>
>
> def create_optimizer(sweep_info):
>     study = optuna.create_study(
>         direction="minimize",
>         sampler=optuna.samplers.TPESampler(seed=42),
>     )
>
>     improvement_evaluator = EMMREvaluator()
>     error_evaluator = MedianErrorEvaluator(improvement_evaluator)
>
>     terminator = Terminator(
>         improvement_evaluator=improvement_evaluator,
>         error_evaluator=error_evaluator,
>         min_n_trials=20,
>     )
>
>     return study, terminator.should_terminate
> ```
>
> L’exemple précédent configure deux composants de l’intégration Optuna :
>
> * Un `TPESampler`, qui propose des configurations d’hyperparamètres.
>
> * Un [OptunaHub Terminator](https://hub.optuna.org/callbacks/terminator/), qui arrête le sweep lorsqu’une amélioration supplémentaire devient peu probable.
>
> > [!NOTE]
> >
> > N'appelez pas `study.optimize()` dans votre fonction d'optimisation. Le planificateur utilise les méthodes `ask()` et `tell()` d'Optuna pour demander des essais et transmettre les résultats. Cette intégration n'expose pas l'interface de fonction de rappel de `Study.optimize()`.

> [tab] Ax
>
> Pour personnaliser l’optimiseur, définissez une fonction qui accepte un argument `SweepInfo` et renvoie un `Client` Ax.
>
> Importez les fonctions d’assistance d’Ax pour configurer l’espace de recherche et les objectifs du client à partir de la configuration de sweep :
>
> | Fonction d’assistance | Description |
> | - | - |
> | `sweep_config_to_search_space(config)` | Convertit `parameters` en configurations de paramètres acceptées par `Client.configure_experiment(parameters=...)`. |
> | `configure_sweep_objective(client, config)` | Configure l’optimisation à partir de `metric` ou de `metrics`. Cette fonction conserve tels quels les noms de métriques contenant des caractères comme les traits d’union, que l’analyseur d’expressions d’Ax risque de mal interpréter. Pour ces noms, nous recommandons d’utiliser cette fonction d’assistance plutôt que `Client.configure_optimization()`. |
>
> Si les noms ou les directions des objectifs ne correspondent pas, la validation échoue au démarrage de l’ordonnanceur.
>
> Par exemple, la fonction suivante crée un client Ax et le configure à partir de `sweep_info.config` :
>
> ```python title="optimizer.py" theme={"system"}
> from ax.api.client import Client
> from wandb.sdk.sweeps.scheduler.ax import (
>     configure_sweep_objective,
>     sweep_config_to_search_space,
> )
>
> def create_optimizer(sweep_info):
>     client = Client()
>     client.configure_experiment(
>         parameters=sweep_config_to_search_space(sweep_info.config)
>     )
>     configure_sweep_objective(client, sweep_info.config)
>     return client
> ```
>
> Dans `sweep.yaml`, définissez `scheduler.source` sur `optimizer.py` et `scheduler.optimizer` sur `create_optimizer` :
>
> ```yaml title="sweep.yaml" theme={"system"}
> program: train.py
> method: custom
> metric:
>   name: validation_loss
>   goal: minimize
> parameters:
>   learning_rate:
>     min: 0.0001
>     max: 0.01
>   batch_size:
>     values: [16, 32, 64]
> scheduler:
>   engine: ax
>   source: optimizer.py
>   optimizer: create_optimizer
> ```

Pour les options d’arrêt au niveau de chaque run et au niveau du sweep, consultez [Configurer l’arrêt](#configure-stopping).

### Définir plusieurs objectifs

Si vous utilisez Optuna ou Ax, vous pouvez utiliser [`metrics`](https://docs.coreweave.com/fr/products/wandb/sweeps/sweep-config-keys#metrics) (au pluriel) pour définir plusieurs objectifs.

Lorsque vous créez un sweep avec `wandb sweep`, Weights & Biases stocke la configuration de sweep. Au démarrage, l’ordonnanceur récupère cette configuration et la transmet à votre fonction d’optimiseur personnalisée dans un objet `SweepInfo`.

Utilisez `sweep_info.config` pour accéder à la configuration de sweep stockée.

> [!NOTE]
>
> Le moteur intégré de Weights & Biases ne prend en charge qu’un seul objectif, défini avec `metric`.

Une fonction d’optimiseur personnalisée n’est pas nécessaire pour utiliser plusieurs objectifs. Les exemples suivants montrent comment configurer les objectifs si vous en fournissez une.

> [tab] Optuna
>
> Pour un sweep multiobjectif avec Optuna, définissez chaque objectif dans la liste `metrics`. Utilisez la fonction utilitaire `sweep_directions()` de `wandb.sdk.sweeps.scheduler.optuna` pour convertir les objectifs en directions d’étude Optuna dans le même ordre.
>
> Par exemple, le sweep suivant minimise la perte de validation et maximise la précision :
>
> ```yaml title="sweep.yaml" theme={"system"}
> name: optuna-multi-objective
> program: train.py
>
> scheduler:
>   engine: optuna
>   source: optimizer.py
>   optimizer: create_optimizer
>
> metrics:
>   - name: validation_loss
>     goal: minimize
>   - name: accuracy
>     goal: maximize
>
> parameters:
>   learning_rate:
>     min: 0.0001
>     max: 0.01
>   batch_size:
>     values: [16, 32, 64]
> ```
>
> Le script de démonstration suivant lit les valeurs suggérées pour `learning_rate` et `batch_size`, calcule deux valeurs d’objectif synthétiques et les journalise dans le run. Les valeurs finales enregistrées figurent dans la synthèse du run, où l’ordonnanceur peut les récupérer.
>
> ```python title="train.py" theme={"system"}
> import math
> import wandb
>
> with wandb.init() as run:
>     learning_rate = run.config["learning_rate"]
>     batch_size = run.config["batch_size"]
>
>     # Remplacez ces calculs par l’entraînement et l’évaluation du modèle.
>     validation_loss = (
>         abs(math.log10(learning_rate) + 3)
>         + 16 / batch_size
>     )
>     accuracy = min(
>         1.0,
>         0.8 - abs(math.log10(learning_rate) + 2.5) * 0.05 + batch_size / 1000,
>     )
>
>     run.log(
>         {
>             "validation_loss": validation_loss,
>             "accuracy": accuracy,
>         }
>     )
> ```
>
> Dans votre fichier `optimizer.py`, transmettez la configuration de sweep stockée, issue de `sweep_info.config`, à `sweep_directions()` lors de la création de l’étude Optuna :
>
> ```python title="optimizer.py" theme={"system"}
> import optuna
> from wandb.sdk.sweeps.scheduler.optuna import sweep_directions
>
> def create_optimizer(sweep_info):
>     return optuna.create_study(
>         directions=sweep_directions(sweep_info.config),
>     )
> ```
>
> L’étude ainsi obtenue minimise `validation_loss` et maximise `accuracy`.

> [tab] Ax
>
> Pour un sweep multi-objectif avec Ax, utilisez la fonction utilitaire `configure_sweep_objective()` de `wandb.sdk.sweeps.scheduler.ax` afin de configurer le client avec le nom et le sens d’optimisation de chaque entrée de `metrics`.
>
> Par exemple, le sweep suivant minimise la perte de validation et maximise la précision :
>
> ```yaml title="sweep.yaml" theme={"system"}
> name: ax-multi-objective
> program: train.py
>
> scheduler:
>   engine: ax
>   source: optimizer.py
>   optimizer: create_optimizer
>
> metrics:
>   - name: validation_loss
>     goal: minimize
>   - name: accuracy
>     goal: maximize
>
> parameters:
>   learning_rate:
>     min: 0.0001
>     max: 0.01
>   batch_size:
>     values: [16, 32, 64]
> ```
>
> Le script de démonstration suivant lit les valeurs suggérées pour `learning_rate` et `batch_size`, calcule deux valeurs d’objectif synthétiques et les journalise dans le run. Les valeurs finales enregistrées apparaissent dans la synthèse du run, où l’ordonnanceur peut les récupérer.
>
> ```python title="train.py" theme={"system"}
> import math
> import wandb
>
> with wandb.init() as run:
>     learning_rate = run.config["learning_rate"]
>     batch_size = run.config["batch_size"]
>
>     # Remplacez ces calculs par l’entraînement et l’évaluation du modèle.
>     validation_loss = (
>         abs(math.log10(learning_rate) + 3)
>         + 16 / batch_size
>     )
>     accuracy = min(
>         1.0,
>         0.8 - abs(math.log10(learning_rate) + 2.5) * 0.05 + batch_size / 1000,
>     )
>
>     run.log(
>         {
>             "validation_loss": validation_loss,
>             "accuracy": accuracy,
>         }
>     )
> ```
>
> Dans `optimizer.py`, créez un client Ax et configurez son espace de recherche et ses objectifs à partir de la configuration de sweep enregistrée. Utilisez `sweep_config_to_search_space()` pour convertir `parameters` en définitions de paramètres Ax, et `configure_sweep_objective()` pour configurer les objectifs définis dans `metrics`.
>
> ```python title="optimizer.py" theme={"system"}
> from ax.api.client import Client
> from wandb.sdk.sweeps.scheduler.ax import (
>     configure_sweep_objective,
>     sweep_config_to_search_space,
> )
>
>
> def create_optimizer(sweep_info):
>     client = Client()
>     client.configure_experiment(
>         parameters=sweep_config_to_search_space(sweep_info.config)
>     )
>     configure_sweep_objective(client, sweep_info.config)
>     return client
> ```
>
> Dans cet exemple, `configure_sweep_objective()` configure Ax de façon à minimiser `validation_loss` et à maximiser `accuracy`.

### Définir un espace de recherche conditionnel

> [!NOTE]
>
> Seul le moteur Optuna prend en charge `scheduler.search_space`.

Avec Optuna, utilisez `scheduler.search_space` pour définir des paramètres conditionnels en Python. Vous pouvez par exemple définir des hyperparamètres différents selon le type de modèle, ou faire varier le nombre de paramètres en fonction de choix antérieurs.

Attribuez à `scheduler.search_space` le nom d’une fonction définie dans le fichier indiqué par `scheduler.source`. L’ordonnanceur transmet un essai Optuna à cette fonction et utilise le dictionnaire renvoyé comme configuration de run.

> [!TIP]
>
> Pour un espace de recherche fixe, définissez `parameters` dans la configuration de sweep.

Lorsque vous définissez `scheduler.search_space`, l’ordonnanceur ignore les définitions `parameters` de premier niveau. Définissez donc dans la fonction Python chaque paramètre à transmettre au run.

Supposons par exemple que vous disposiez de la configuration de sweep suivante :

```yaml title="sweep.yaml" theme={"system"}
metric:
  name: validation_loss
  goal: minimize

parameters: {}

scheduler:
  engine: optuna
  source: search.py
  search_space: define_search_space
```

Pour chaque essai, l’ordonnanceur appelle `define_search_space(trial)` et utilise le dictionnaire renvoyé comme configuration de run :

```python title="search.py" theme={"system"}
def define_search_space(trial):
    model = trial.suggest_categorical("model", ["linear", "transformer"])

    config = {
        "model": model,
        "learning_rate": trial.suggest_float(
            "learning_rate", 1e-5, 1e-2, log=True
        ),
    }

    if model == "transformer":
        config["num_layers"] = trial.suggest_int("num_layers", 2, 12)
        config["num_heads"] = trial.suggest_categorical(
            "num_heads", [4, 8, 16]
        )
    else:
        config["regularization"] = trial.suggest_float(
            "regularization", 0.0, 1.0
        )

    return config
```

Chaque run reçoit `model` et `learning_rate`. Les runs pour lesquels `model="transformer"` reçoivent en outre `num_layers` et `num_heads`. Les runs pour lesquels `model="linear"` reçoivent plutôt `regularization`.

## Configurer l’arrêt

L’arrêt peut porter sur un run individuel ou sur l’ensemble du sweep. L’arrêt anticipé au niveau du run interrompt les runs peu susceptibles de produire un résultat utile. L’arrêt au niveau du sweep empêche l’ordonnanceur de proposer de nouveaux runs dès qu’une condition est remplie.

### Arrêter des runs individuels

Pour évaluer la progression d’un run, journalisez des valeurs intermédiaires de la métrique cible tout au long de l’entraînement. Chaque moteur dispose de son propre mécanisme pour décider s’il convient d’arrêter un run.

> [!NOTE]
>
> La clé de premier niveau `early_terminate` s’applique uniquement au moteur intégré de Weights & Biases. Pour Optuna ou Ax, configurez le mécanisme d’arrêt anticipé natif du moteur.

> [tab] Weights & Biases
>
> Utilisez [Hyperband](https://arxiv.org/abs/1603.06560) pour optimiser les hyperparamètres avec un arrêt anticipé basé sur les résultats intermédiaires.
>
> Définissez `early_terminate.type` sur `hyperband` et utilisez `min_iter` pour définir le nombre minimum d’itérations.
>
> Par exemple, la configuration de sweep suivante utilise Hyperband pour l’arrêt anticipé avec un minimum de 3 itérations :
>
> ```yaml title="sweep.yaml" theme={"system"}
> program: train.py
> method: bayes
> metric:
>   name: validation_loss
>   goal: minimize
> parameters:
>   learning_rate:
>     min: 0.0001
>     max: 0.01
>   batch_size:
>     values: [16, 32, 64]
> early_terminate:
>   type: hyperband
>   min_iter: 3
> scheduler:
>   engine: wandb
> ```
>
> Consultez [`early_terminate`](https://docs.coreweave.com/fr/products/wandb/sweeps/sweep-config-keys#early_terminate) pour connaître les options de configuration disponibles.

> [tab] Optuna
>
> Dans Optuna, un [pruner](https://optuna.readthedocs.io/en/stable/reference/pruners.html) détermine, en fonction des résultats intermédiaires, s’il faut arrêter un essai de manière anticipée.
>
> Par exemple, supposons que vous disposiez de la configuration de sweep suivante et que vous souhaitiez appliquer un arrêt anticipé avec Optuna :
>
> ```yaml title="sweep.yaml" theme={"system"}
> name: optuna-pruning-demo
> program: train.py
> method: grid
> run_cap: 2
>
> metric:
>   name: loss
>   goal: minimize
>
> parameters:
>   loss:
>     values: [0.2, 0.9]
>
> scheduler:
>   engine: optuna
>   source: optimizer.py
>   optimizer: make_study
> ```
>
> Dans `optimizer.py`, créez une étude avec un échantillonneur par grille et un élagueur à seuil. L’élagueur recommande d’arrêter les essais dont la perte intermédiaire dépasse 0,5 :
>
> ```python title="optimizer.py" theme={"system"}
> import optuna
>
> def make_study(sweep_info):
>     """Create a study with a grid sampler and a threshold pruner."""
>     return optuna.create_study(
>         direction="minimize",
>         sampler=optuna.samplers.GridSampler(
>             {"loss": [0.2, 0.9]},
>         ),
>         # Arrêter tout run dont la perte intermédiaire dépasse 0,5.
>         pruner=optuna.pruners.ThresholdPruner(
>             upper=0.5,
>             n_warmup_steps=0,
>         ),
>     )
> ```
>
> Dans `train.py`, journalisez la perte configurée à chaque step afin que le planificateur puisse transmettre les résultats intermédiaires à l’élagueur :
>
> ```python title="train.py" theme={"system"}
> import time
> import wandb
>
> with wandb.init() as run:
>     loss = run.config["loss"]
>
>     for step in range(30):
>         run.log({"loss": loss}, step=step)
>         time.sleep(1)
> ```
>
> > [!NOTE]
> >
> > L’élagage (pruning) d’Optuna n’est pas disponible pour les études multi-objectifs.

> [tab] Ax
>
> Pour activer l’arrêt anticipé de runs individuels avec Ax, appelez `client.set_early_stopping_strategy()` afin de configurer une stratégie d’arrêt anticipé, puis renvoyez le client.
>
> Par exemple, supposons que vous disposiez de la configuration de sweep suivante et que vous souhaitiez appliquer l’arrêt anticipé avec Ax :
>
> ```yaml title="sweep.yaml" theme={"system"}
> name: ax-run-stopping-demo
> program: train.py
>
> # Requis par le schéma de sweep ; Ax gère la génération des paramètres.
> method: random
> run_cap: 2
> metric:
>   name: loss
>   goal: minimize
> parameters:
>   difficulty:
>     values: [0.1, 1.0]
> scheduler:
>   engine: ax
>   source: optimizer.py
>   optimizer: make_client
> ```
>
> Dans `optimizer.py`, configurez le client avec l’espace de recherche, l’objectif et une stratégie d’arrêt anticipé par percentile. Comme l’objectif consiste à minimiser `loss`, la stratégie se fonde sur les valeurs de perte les plus élevées pour identifier les runs les moins performants.
>
> ```python title="optimizer.py" theme={"system"}
> from ax.api.client import Client
> from ax.early_stopping.strategies import PercentileEarlyStoppingStrategy
>
> from wandb.sdk.sweeps.scheduler.ax import (
>     configure_sweep_objective,
>     sweep_config_to_search_space,
> )
>
> def make_client(sweep_info):
>     client = Client()
>     client.configure_experiment(
>         parameters=sweep_config_to_search_space(sweep_info.config),
>     )
>     configure_sweep_objective(client, sweep_info.config)
>
>     client.set_early_stopping_strategy(
>         PercentileEarlyStoppingStrategy(
>             percentile_threshold=50.0,
>             min_progression=2,
>             min_curves=2,
>             seconds_between_polls=0,
>             normalize_progressions=False,
>         )
>     )
>
>     return client
> ```
>
> Dans `train.py`, calculez une perte synthétique à partir de `difficulty` et journalisez-la à chaque étape. Ces valeurs intermédiaires permettent à Ax de comparer la progression des runs :
>
> ```python title="train.py" theme={"system"}
> import time
> import wandb
>
> with wandb.init() as run:
>     difficulty = run.config["difficulty"]
>
>     for step in range(30):
>         # Le run avec difficulty=1.0 est systématiquement moins bon.
>         loss = difficulty + 1.0 / (step + 1)
>
>         run.log(
>             {"loss": loss},
>             step=step,
>         )
>
>         # Maintenir les runs actifs assez longtemps pour que le scheduler puisse les interroger.
>         time.sleep(1)
> ```
>
> Exécutez deux agents de sweep en parallèle afin que le planificateur puisse recueillir les résultats intermédiaires des deux runs. Lorsque Ax recommande d’arrêter un run, le planificateur demande à Weights & Biases de l’arrêter.

### Arrêter le sweep

L’arrêt au niveau du sweep détermine à quel moment l’ordonnanceur cesse de proposer de nouveaux runs. Utilisez `run_cap` pour définir un nombre maximum fixe de runs, quel que soit le moteur. Avec Optuna ou Ax, vous pouvez également renvoyer une fonction d’arrêt qui évalue l’état actuel de l’optimisation.

> [!NOTE]
>
> Dans les exemples suivants, c’est l’ordonnanceur qui contrôle la stratégie de recherche : il ignore donc `method: random`. Le schéma de sweep de Weights & Biases exige toutefois `method`.

Au moment où une condition d’arrêt est remplie, l’ordonnanceur peut avoir déjà des runs mis en file d’attente ou en cours d’exécution. Ces runs peuvent se poursuivre une fois que l’ordonnanceur a cessé d’en proposer de nouveaux.

> [tab] Optuna
>
> Pour activer l’arrêt au niveau du sweep, la fonction d’optimisation que vous indiquez dans `scheduler.optimizer` doit renvoyer une étude Optuna et une fonction d’arrêt sous forme de tuple :
>
> ```python theme={"system"}
> (study, terminator_callback)
> ```
>
> Après le traitement des résultats, l’ordonnanceur transmet l’étude en cours à la fonction d’arrêt. Cette fonction renvoie `True` pour arrêter le sweep, ou `False` pour continuer à proposer de nouveaux runs.
>
> Par exemple, la configuration de sweep suivante effectue une recherche sur `x`, limite le sweep à 20 runs et indique à l’ordonnanceur Optuna d’appeler `make_study()` depuis le fichier `optimizer.py` :
>
> ```yaml title="sweep.yaml" theme={"system"}
> name: optuna-sweep-stopping-demo
> program: train.py
> method: random
> run_cap: 20
>
> metric:
>   name: loss
>   goal: minimize
>
> parameters:
>   x:
>     min: 0
>     max: 10
>
> scheduler:
>   engine: optuna
>   source: optimizer.py
>   optimizer: make_study
> ```
>
> Dans cet exemple, `run_cap` sert de limite de secours si la fonction d'arrêt ne met pas fin au sweep avant.
>
> Définissez ensuite l'étude Optuna et la fonction d'arrêt. `make_study()` configure un échantillonneur aléatoire initialisé avec une graine et renvoie l'étude avec `stop_after_three_completed_trials()` :
>
> ```python title="optimizer.py" theme={"system"}
> import optuna
>
>
> def stop_after_three_completed_trials(study: optuna.Study) -> bool:
>     """Stop the sweep after three completed trials."""
>     completed = sum(
>         trial.state == optuna.trial.TrialState.COMPLETE
>         for trial in study.trials
>     )
>
>     return completed >= 3
>
>
> def make_study(sweep_info):
>     study = optuna.create_study(
>         direction="minimize",
>         sampler=optuna.samplers.RandomSampler(seed=42),
>     )
>
>     return study, stop_after_three_completed_trials
> ```
>
> La fonction d’arrêt ne compte que les essais terminés avec succès. Elle renvoie `True` après le troisième essai terminé, ce qui indique à l’ordonnanceur de cesser de proposer des configurations. Les essais échoués, élagués ou en cours d’exécution ne sont pas comptabilisés.
>
> Enfin, définissez l’objectif évalué par chaque run du sweep. Le script d’entraînement récupère la valeur suggérée de `x`, calcule la perte correspondante et la journalise dans Weights & Biases :
>
> ```python title="train.py" theme={"system"}
> import wandb
>
> with wandb.init() as run:
>     x = run.config["x"]
>     loss = (x - 3) ** 2
>
>     run.log({"loss": loss})
> ```
>
> À la fin de chaque run, l’ordonnanceur transmet la perte journalisée à l’étude Optuna. Dès que trois essais sont terminés, la fonction d’arrêt renvoie `True` et l’ordonnanceur cesse de proposer de nouveaux runs. Les runs déjà mis en file d’attente ou en cours d’exécution peuvent toutefois se terminer.

> [tab] Ax
>
> Pour activer l’arrêt au niveau du sweep, faites en sorte que la fonction spécifiée par `scheduler.optimizer` renvoie un tuple contenant le client Ax et une fonction d’arrêt :
>
> ```python theme={"system"}
> (client, terminator)
> ```
>
> La configuration suivante limite le sweep à 20 runs. La fonction d’arrêt peut l’interrompre plus tôt si l’objectif cesse de s’améliorer :
>
> ```yaml title="sweep.yaml" theme={"system"}
> name: ax-sweep-stopping-example
> program: train.py
> method: random
> run_cap: 20
> metric:
>   name: loss
>   goal: minimize
> parameters:
>   x:
>     min: 0.0
>     max: 1.0
> scheduler:
>   engine: ax
>   source: optimizer.py
>   optimizer: make_client
> ```
>
> Dans `optimizer.py`, créez un client Ax et une fonction d’arrêt. Cet exemple utilise `ImprovementGlobalStoppingStrategy` pour comparer l’amélioration récente à la dispersion des valeurs observées de l’objectif :
>
> ```python title="optimizer.py" theme={"system"}
> from ax.api.client import Client
> from ax.global_stopping.strategies.improvement import (
>     ImprovementGlobalStoppingStrategy,
> )
>
> from wandb.sdk.sweeps.scheduler.ax import (
>     configure_sweep_objective,
>     sweep_config_to_search_space,
> )
>
>
> def make_client(sweep_info):
>     """Create the Ax client and sweep-level stopping callback."""
>
>     client = Client()
>
>     # Convertir les paramètres de sweep.yaml en un espace de recherche Ax.
>     client.configure_experiment(
>         parameters=sweep_config_to_search_space(sweep_info.config),
>     )
>
>     # Définir « loss » comme l’objectif à minimiser par Ax.
>     configure_sweep_objective(client, sweep_info.config)
>
>     client.configure_generation_strategy(
>         method="random_search",
>         initialization_random_seed=7,
>         initialize_with_center=True,
>     )
>
>     stopping_strategy = ImprovementGlobalStoppingStrategy(
>         min_trials=6,
>         window_size=3,
>         improvement_bar=0.01,
>         inactive_when_pending_trials=True,
>     )
>
>     def should_terminate_sweep(client):
>         """Return True when Ax recommends ending the whole sweep."""
>         should_stop, reason = stopping_strategy.should_stop_optimization(
>             experiment=client._experiment,
>         )
>
>         if should_stop:
>             print(f"Ax is stopping the sweep: {reason}")
>
>         return should_stop
>
>     return client, should_terminate_sweep
> ```
>
> Le script d’entraînement suivant évalue un objectif synthétique dont le minimum se situe à `x=0.5`. La stratégie de génération évalue ce point en premier, si bien que les essais suivants ne peuvent pas améliorer le meilleur résultat :
>
> ```python title="train.py" theme={"system"}
> import time
> import wandb
>
> with wandb.init() as run:
>     x = run.config["x"]
>
>     for step in range(5):
>         loss = (x - 0.5) ** 2 + 1.0 / (step + 1)
>
>         run.log(
>             {"loss": loss},
>             step=step,
>         )
>
>         time.sleep(0.5)
> ```
>
> Cette stratégie d’arrêt n’utilise que la valeur finale de l’objectif de chaque run terminé. Le script journalise des valeurs intermédiaires pour simuler l’entraînement ; cet exemple ne configure pas d’arrêt anticipé pour les runs individuels.

## Gérer les redémarrages de l’ordonnanceur

L’ordonnanceur de sweeps agit sur un sweep existant : vous pouvez donc arrêter puis redémarrer l’ordonnanceur sans créer de nouveau sweep. À chaque démarrage, l’ordonnanceur reconstruit l’historique d’optimisation à partir des données des runs existants du sweep, puis reprend la boucle d’optimisation. Il ne restaure pas le moteur à partir d’un point de contrôle d’optimiseur enregistré.

Lorsque l’ordonnanceur démarre ou redémarre, il appelle votre fonction d’optimiseur personnalisée pour créer une nouvelle instance du moteur. Renvoyez une nouvelle étude Optuna ou un nouveau client Ax à chaque exécution de la fonction. Ne chargez pas de point de contrôle d’optimiseur distinct et ne réutilisez pas d’instance de moteur issue d’un processus d’ordonnanceur précédent.

Si vous utilisez un fichier `scheduler.source`, l’ordonnanceur charge son contenu actuel à chaque démarrage. Entre deux démarrages, vous pouvez mettre à jour le fichier pour corriger des bugs ou modifier la fonction personnalisée `optimizer` ou `search_space`. Ces modifications pouvant influer sur les suggestions ultérieures, conservez la version du fichier `source` utilisée pour chaque session de l’ordonnanceur si vous devez reproduire l’optimisation.
