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

# 最適化エンジンを設定する

Weights & Biases Sweeps で使用する最適化エンジンを選択します。ランダム探索、グリッド探索、ベイズ探索を行う場合は、組み込みの Weights & Biases エンジンを使用します。Optuna または Ax の探索アルゴリズムやカスタマイズオプションを利用する場合は、それぞれのエンジンを使用します。

エンジン、スケジューラー、sweep エージェントは次のように連携します。

| コンポーネント | 役割 |
| - | - |
| 最適化エンジン | ハイパーパラメーターの設定を提案します。探索戦略によっては、run の結果をもとに探索の方向を決定します。 |
| sweep スケジューラー | エンジンに設定をリクエストして Weights & Biases に送信し、run の結果をエンジンに返します。 |
| sweep エージェント | 割り当て済みの設定を Weights & Biases から取得し、トレーニングコードを実行します。 |

このページでは、独自の環境で実行するスケジューラー向けにエンジンを設定する方法を説明します。YAML の完全な例については、[sweep スケジューラーのサンプル](https://docs.coreweave.com/ja/products/wandb/sweeps/define-sweep-configuration.md#sweep-scheduler-examples)を参照してください。

## エンジンを選択する

必要な探索手法とカスタマイズオプションに応じて、エンジンを選択します。

| エンジン | 説明 |
| - | - |
| Weights & Biases (組み込み) | sweep 設定のキーで設定する、ランダム探索、グリッド探索、またはベイズ探索。 |
| [Optuna](https://optuna.org/) | サンプラーとプルーナーを設定できる、オープンソースのハイパーパラメーター最適化フレームワーク。 |
| [Ax](https://ax.dev/) | 生成戦略と停止戦略を設定できる、適応型実験のためのオープンソースプラットフォーム。 |

Optuna または Ax を使用すると、次のことができます。

* [複数の目的を定義](#define-multiple-objectives)して、複数のメトリクスを最適化する。
* [sweep レベルのカスタム停止関数を定義](#stop-the-sweep)して、スケジューラーが新しい run の提案を停止するタイミングを制御する。

Optuna では、[条件付き探索空間を定義](#define-a-conditional-search-space)して、試行内でそれまでに選択した値に応じてパラメーターを選択することもできます。

## 依存関係をインストールする

Weights & Biases Python SDK のバージョン 0.31.0 以降を、使用するエンジンに応じた追加の依存関係とあわせてインストールします。インストールコマンドは、スケジューラーを実行する環境で実行してください。

> [tab] Weights & Biases
>
> Python 3.10 以降を使用してください。`sweeps` extra を指定して SDK をインストールすると、スケジューラーの環境に `sweeps>=0.2.0` が含まれます。
>
> ```bash theme={"system"}
> pip install "wandb[sweeps]>=0.31.0"
> ```

> [tab] Optuna
>
> Python 3.10 以降を使用してください。`optuna` extra を指定して SDK をインストールすると、スケジューラーの環境に `optuna>=4.0.0` が含まれます。
>
> ```bash theme={"system"}
> pip install "wandb[optuna]>=0.31.0"
> ```
>
> このページで紹介する OptunaHub Terminator の例を使用するには、`optunahub` もインストールしてください。
>
> ```bash theme={"system"}
> pip install optunahub
> ```

> [tab] Ax
>
> Python 3.11 以降を使用してください。`ax` extra を指定して SDK をインストールすると、スケジューラーの環境に `ax-platform>=1.3.1` が含まれます。
>
> ```bash theme={"system"}
> pip install "wandb[ax]>=0.31.0"
> ```

## 最適化を設定する

エンジンの探索戦略、目的、探索空間を設定します。組み込みの Weights & Biases エンジンは sweep 設定を使用します。Optuna と Ax では、Optuna の study または Ax クライアントを設定する Python 関数を指定できます。

### 探索戦略を設定する

`scheduler.engine` を `wandb`、`optuna`、または `ax` に設定します。

Optuna と Ax では、カスタムのオプティマイザー関数は省略可能です。`scheduler.engine` を変更するだけでエンジンを切り替えられ、sweep 設定で定義した探索空間と目的 (`metrics` で定義した複数の目的を含む) をそのまま使用できます。

カスタムのオプティマイザー関数を使用するには、`scheduler.source` に Python のファイル名を、`scheduler.optimizer` に関数名を設定します。Optuna では、`scheduler.search_space` でカスタムの探索空間を定義することもできます。

> [tab] Weights & Biases
>
> 組み込みの Weights & Biases エンジンは、sweep 設定で設定します。
>
> `method` を `random`、`grid`、`bayes` のいずれかに設定します。エンジンは `method`、`metric`、`parameters` に基づいて、sweep の各 run で使用する設定を選択します。
>
> たとえば、組み込みの 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
> ```
>
> 各検索メソッドの詳細については、[検索メソッド](https://docs.coreweave.com/ja/products/wandb/sweeps/sweep-config-keys.md#method)を参照してください。

> [tab] Optuna
>
> オプティマイザーをカスタマイズするには、`SweepInfo` 引数を 1 つ受け入れ、Optuna の `Study` を返す関数を定義します。
>
> たとえば、次のような sweep 設定があるとします。
>
> ```yaml title="sweep.yaml" theme={"system"}
> program: train.py
>
> # W&B sweep のスキーマで必須ですが、検索戦略は
> # Optuna スケジューラーが制御します。
> 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
>
> # Terminator が先に収束を検出しない場合でも、
> # run が最大 100 回に達した時点で停止します。
> run_cap: 100
>
> scheduler:
>   engine: optuna
>   source: optimizer.py
>   optimizer: create_optimizer
> ```
>
> `optimizer.py` で TPE サンプラーを使用する study を作成し、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
> ```
>
> 前の例では、Optuna インテグレーションの 2 つの要素を設定しています。
>
> * `TPESampler`：ハイパーパラメーターの設定を提案します。
>
> * [OptunaHub Terminator](https://hub.optuna.org/callbacks/terminator/)：これ以上の改善が見込めない場合に sweep を停止します。
>
> > [!NOTE]
> >
> > オプティマイザー関数内では `study.optimize()` を呼び出さないでください。スケジューラーは Optuna の `ask()` メソッドと `tell()` メソッドを使用して、試行をリクエストし、結果を報告します。このインテグレーションでは、`Study.optimize()` のコールバックインターフェースは公開されていません。

> [tab] Ax
>
> オプティマイザーをカスタマイズするには、`SweepInfo` 引数を 1 つ受け取り、Ax の `Client` を返す関数を定義します。
>
> Ax のヘルパー関数をインポートすると、sweep 設定に基づいてクライアントの探索空間と目的を設定できます。
>
> | ヘルパー関数 | 説明 |
> | - | - |
> | `sweep_config_to_search_space(config)` | `parameters` を、`Client.configure_experiment(parameters=...)` が受け入れる形式のパラメーター設定に変換します。 |
> | `configure_sweep_objective(client, config)` | `metric` または `metrics` に基づいて最適化を設定します。ハイフンなど、Ax の式パーサーが誤って解釈する可能性のある文字を含むメトリクス名も、そのまま保持されます。このような名前を使用する場合は、`Client.configure_optimization()` ではなくこのヘルパーを使用することをお勧めします。 |
>
> 目的の名前または方向が一致しない場合、スケジューラーの起動時に検証が失敗します。
>
> たとえば、次の関数は Ax クライアントを作成し、`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
> ```
>
> `sweep.yaml` で、`scheduler.source` を `optimizer.py` に、`scheduler.optimizer` を `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
> ```

run 単位および sweep 単位の停止オプションについては、[停止の設定](#configure-stopping)を参照してください。

### 複数の目的を定義する

Optuna または Ax を使用する場合は、[`metrics`](https://docs.coreweave.com/ja/products/wandb/sweeps/sweep-config-keys#metrics) (複数形) を使用して複数の目的を定義できます。

`wandb sweep` で sweep を作成すると、Weights & Biases は sweep 設定を保存します。スケジューラーは起動時にその設定を取得し、`SweepInfo` オブジェクトの一部としてカスタムオプティマイザー関数に渡します。

保存された sweep 設定にアクセスするには、`sweep_info.config` を使用します。

> [!NOTE]
>
> Weights & Biases の組み込みエンジンは、`metric` で定義する単一の目的のみをサポートしています。

複数の目的を使用する場合でも、カスタムオプティマイザー関数は必須ではありません。以下の例では、カスタムオプティマイザー関数を提供する場合の目的の設定方法を示します。

> [tab] Optuna
>
> Optuna で多目的 sweep を行う場合は、各目的を `metrics` リストで定義します。`wandb.sdk.sweeps.scheduler.optuna` の `sweep_directions()` ヘルパーを使用すると、各目標を同じ順序のまま Optuna の study の direction に変換できます。
>
> たとえば、次の sweep は検証損失を最小化し、精度を最大化します。
>
> ```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]
> ```
>
> 次のデモスクリプトは、提案された `learning_rate` と `batch_size` の値を読み取り、2 つの合成目的値を計算して run にログします。最終的にログされた値は run の概要に表示され、スケジューラーはそこから値を取得できます。
>
> ```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"]
>
>     # これらの計算を、実際のモデル トレーニングと評価に置き換えてください。
>     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,
>         }
>     )
> ```
>
> `optimizer.py` ファイル内で Optuna の study を作成する際に、`sweep_info.config` に保存されている sweep 設定を `sweep_directions()` に渡します。
>
> ```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),
>     )
> ```
>
> これにより、`validation_loss` を最小化し、`accuracy` を最大化する study が作成されます。

> [tab] Ax
>
> Ax で多目的 sweep を行う場合は、`wandb.sdk.sweeps.scheduler.ax` の `configure_sweep_objective()` ヘルパーを使用して、`metrics` の各エントリの名前と最適化の方向をクライアントに設定します。
>
> たとえば、次の sweep は検証損失を最小化し、精度を最大化します。
>
> ```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]
> ```
>
> 次のデモスクリプトは、提案された `learning_rate` と `batch_size` の値を読み取り、2 つの合成目的値を計算して run にログします。最終的にログされた値は run の概要に表示され、スケジューラーはそこから値を取得できます。
>
> ```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"]
>
>     # これらの計算を、実際のモデル トレーニングと評価の処理に置き換えてください。
>     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,
>         }
>     )
> ```
>
> `optimizer.py` で Ax クライアントを作成し、保存済みの sweep 設定に基づいて探索空間と目的を設定します。`sweep_config_to_search_space()` を使用して `parameters` を Ax のパラメータ定義に変換し、`configure_sweep_objective()` を使用して `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
> ```
>
> この例では、`configure_sweep_objective()` が `validation_loss` を最小化し、`accuracy` を最大化するように Ax を設定します。

### 条件付きの探索空間を定義する

> [!NOTE]
>
> `scheduler.search_space` をサポートしているのは Optuna エンジンのみです。

Optuna では、`scheduler.search_space` を使用して条件付きパラメーターを Python で定義できます。たとえば、モデルのタイプごとに異なるハイパーパラメーターを定義したり、前の段階での選択に基づいてパラメーターの数を変えたりできます。

`scheduler.search_space` には、`scheduler.source` で指定したファイル内の関数名を設定します。スケジューラーは Optuna の試行をその関数に渡し、関数が返す辞書を run 設定として使用します。

> [!TIP]
>
> 固定の探索空間を使用する場合は、sweep 設定で `parameters` を定義してください。

`scheduler.search_space` を設定すると、スケジューラーは top-level の `parameters` の定義を無視します。run に渡すパラメーターはすべて Python 関数内で定義してください。

たとえば、次のような sweep 設定があるとします。

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

parameters: {}

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

各試行で、スケジューラーは `define_search_space(trial)` を呼び出し、返された辞書を 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
```

すべての run は `model` と `learning_rate` を受け取ります。`model="transformer"` の run は、これらに加えて `num_layers` と `num_heads` も受け取ります。`model="linear"` の run は、代わりに `regularization` を受け取ります。

## 停止を設定する

停止は、個々の run と sweep 全体のどちらにも適用できます。run 単位の早期停止では、有用な結果が得られる見込みの低い run を終了します。sweep レベルの停止では、条件が満たされると、スケジューラーは新しい run を提案しなくなります。

### 個々の run を停止する

run の進捗を評価するには、トレーニング中に目的メトリクスの中間値をログします。run を停止するかどうかを判断する仕組みは、エンジンごとに異なります。

> [!NOTE]
>
> top-level の `early_terminate` キーは、組み込みの Weights & Biases エンジンにのみ適用されます。Optuna または Ax を使用する場合は、そのエンジン固有の早期停止の仕組みを設定してください。

> [tab] Weights & Biases
>
> 中間結果に基づいて早期停止を行うハイパーパラメーター最適化には、[Hyperband](https://arxiv.org/abs/1603.06560) を使用します。
>
> `early_terminate.type` を `hyperband` に設定し、`min_iter` で反復処理の最小回数を指定します。
>
> たとえば、次の sweep 設定では、Hyperband を使用して早期停止を行い、反復処理の最小回数を 3 回に設定しています。
>
> ```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
> ```
>
> 設定オプションについては、[`early_terminate`](https://docs.coreweave.com/ja/products/wandb/sweeps/sweep-config-keys#early_terminate) を参照してください。

> [tab] Optuna
>
> Optuna では、[pruner](https://optuna.readthedocs.io/en/stable/reference/pruners.html) が中間結果に基づいて、試行を早期に停止するかどうかを判断します。
>
> たとえば、次の sweep 設定を使用しており、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
> ```
>
> `optimizer.py` で、グリッドサンプラーとしきい値プルーナーを使用する study を作成します。このプルーナーは、中間損失が 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]},
>         ),
>         # 中間損失が 0.5 を超えた run はすべて停止します。
>         pruner=optuna.pruners.ThresholdPruner(
>             upper=0.5,
>             n_warmup_steps=0,
>         ),
>     )
> ```
>
> `train.py` で、設定した損失を各 step でログし、スケジューラーが中間結果をプルーナーに渡せるようにします：
>
> ```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]
> >
> > Optuna の枝刈り (pruning) は、多目的最適化の study では利用できません。

> [tab] Ax
>
> Ax で run ごとの早期停止を有効にするには、`client.set_early_stopping_strategy()` を呼び出して早期停止戦略を設定してから、クライアントを返します。
>
> たとえば、次の sweep 設定に対して Ax による早期停止を適用するとします。
>
> ```yaml title="sweep.yaml" theme={"system"}
> name: ax-run-stopping-demo
> program: train.py
>
> # sweep のスキーマ上必須です。パラメーターの生成は Ax が制御します。
> 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
> ```
>
> `optimizer.py` で、探索空間、目的関数、パーセンタイルベースの早期停止戦略を指定してクライアントを設定します。目的関数は `loss` を最小化するため、この戦略では損失値が高い run を性能の低い run として特定します。
>
> ```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
> ```
>
> `train.py` で、`difficulty` から合成の損失を計算し、各 step でログします。これらの中間値を使って、Ax は各 run の進捗を比較できます。
>
> ```python title="train.py" theme={"system"}
> import time
> import wandb
>
> with wandb.init() as run:
>     difficulty = run.config["difficulty"]
>
>     for step in range(30):
>         # difficulty=1.0 の run は常に結果が劣ります。
>         loss = difficulty + 1.0 / (step + 1)
>
>         run.log(
>             {"loss": loss},
>             step=step,
>         )
>
>         # スケジューラーがポーリングできるよう、run を十分な時間実行し続けます。
>         time.sleep(1)
> ```
>
> 2 つの sweep エージェントを同時に実行し、スケジューラーが両方の run から中間結果を収集できるようにします。Ax が run の停止を推奨すると、スケジューラーは Weights & Biases にその run を停止するようリクエストします。

### sweep を停止する

sweep レベルの停止では、スケジューラーが新しい run の提案を停止するタイミングを制御します。`run_cap` を使用すると、どのエンジンでも run 数の上限を固定値で設定できます。Optuna または Ax では、最適化の現在の状態を評価する停止関数を返すこともできます。

> [!NOTE]
>
> 以下の例ではスケジューラーが探索戦略を制御するため、`method: random` は無視されます。ただし、Weights & Biases の sweep スキーマでは `method` の指定が必須です。

停止条件が満たされた時点で、キューに追加済みの run や実行中の run がすでに存在する場合があります。これらの run は、スケジューラーが新しい run の提案を停止した後も引き続き実行できます。

> [tab] Optuna
>
> sweep レベルでの停止を有効にするには、`scheduler.optimizer` で指定する最適化関数が、Optuna の study と停止関数をタプルで返す必要があります。
>
> ```python theme={"system"}
> (study, terminator_callback)
> ```
>
> 結果を処理した後、スケジューラーは現在の study を停止関数に渡します。この関数は、sweep を停止する場合は `True` を、新しい run の提案を続ける場合は `False` を返します。
>
> たとえば、次の sweep 設定では、`x` を探索対象とし、sweep の run 数を 20 に制限したうえで、`optimizer.py` ファイルの `make_study()` を呼び出すよう Optuna スケジューラーに指示します。
>
> ```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
> ```
>
> この例では、停止関数が先に sweep を終了しなかった場合に備えて、`run_cap` がフォールバック用の上限として機能します。
>
> 次に、Optuna の study と停止関数を定義します。`make_study()` はシード付きのランダムサンプラーを設定し、`stop_after_three_completed_trials()` と組み合わせた study を返します。
>
> ```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
> ```
>
> 停止関数は、正常に完了した試行のみをカウントします。3 回目の試行が完了すると `True` を返し、設定の提案を停止するようスケジューラーに指示します。失敗した試行、枝刈りされた試行、実行中の試行はカウントの対象外です。
>
> 最後に、各 sweep run で評価する目的関数を定義します。トレーニングスクリプトは、提案された `x` の値を取得して損失を計算し、その損失を 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})
> ```
>
> 各 run が終了すると、スケジューラーはその run で記録済みの損失を Optuna の study に渡します。3 回の試行が完了すると停止関数が `True` を返し、スケジューラーは新しい run の提案を停止します。すでにキューに追加されている run や実行中の run は、そのまま終了まで実行されます。

> [tab] Ax
>
> sweep レベルでの停止を有効にするには、`scheduler.optimizer` で指定した関数から、Ax クライアントと停止関数を含むタプルを返すようにします。
>
> ```python theme={"system"}
> (client, terminator)
> ```
>
> 次の設定では、sweep の run 数を 20 に制限します。目的関数の値が改善しなくなった場合は、停止関数によって sweep をそれより早く終了させることもできます。
>
> ```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
> ```
>
> `optimizer.py` で、Ax クライアントと停止関数を作成します。この例では `ImprovementGlobalStoppingStrategy` を使用して、直近の改善幅を、これまでに観測された目的値のばらつきと比較します:
>
> ```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()
>
>     # sweep.yaml のパラメーターを Ax の探索空間に変換します。
>     client.configure_experiment(
>         parameters=sweep_config_to_search_space(sweep_info.config),
>     )
>
>     # Ax が最小化する目的として "loss" を設定します。
>     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
> ```
>
> 次のトレーニングスクリプトは、`x=0.5` で最小値をとる合成目的関数を評価します。生成戦略はこのポイントを最初に評価するため、以降の試行で最良の結果が更新されることはありません。
>
> ```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)
> ```
>
> この停止戦略では、完了した各 run の最終的な目的関数値のみを使用します。スクリプトはトレーニングをシミュレートするために中間値をログしますが、この例では個々の run に対する早期停止は設定していません。

## スケジューラーの再起動への対応

sweep スケジューラーは既存の sweep 上で動作するため、新しい sweep を作成しなくても、スケジューラーを停止して再起動できます。スケジューラーは起動するたびに sweep の既存の run データから最適化履歴を再構築し、最適化ループを再開します。保存済みのオプティマイザーのチェックポイントからエンジンをリストアすることはありません。

スケジューラーは起動または再起動時に、カスタムのオプティマイザー関数を呼び出して新しいエンジンインスタンスを作成します。この関数では、実行のたびに新しい Optuna study または Ax クライアントを返すようにしてください。別途保存したオプティマイザーのチェックポイントを読み込んだり、以前のスケジューラープロセスのエンジンインスタンスを再利用したりしないでください。

`scheduler.source` ファイルを使用する場合、スケジューラーは起動するたびにその時点のファイル内容を読み込みます。そのため、次回の起動までにファイルを更新して、バグを修正したり、カスタムの `optimizer` 関数や `search_space` 関数を変更したりできます。ただし、これらの変更は以降の提案に影響する可能性があります。最適化を再現する必要がある場合は、スケジューラーのセッションごとに、使用した `source` ファイルのバージョンを保存しておいてください。
