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

> sweep の設定ファイルを作成する方法について説明します。

# 概要

sweep は、ハイパーパラメーターの値を探索する戦略と、それらの値を評価するコードを組み合わせたものです。戦略には、すべての選択肢を試すような単純なものから、Bayesian Optimization and Hyperband ([BOHB](https://arxiv.org/abs/1807.01774)) のような複雑なものまであります。

このガイドでは、探索するハイパーパラメーター、使用する探索戦略、各 run の評価方法を指定する sweep 設定の定義方法を説明します。新しい sweep をセットアップするときや、既存の設定を別の探索手法やパラメーター空間に合わせて変更するときに参照してください。

sweep 設定は、[Python の辞書](https://docs.python.org/3/tutorial/datastructures.html#dictionaries)または [YAML](https://yaml.org/) ファイルで定義します。どちらを使うかは、sweep をどのように管理するかによって決まります。

<Note>
  コマンドラインから sweep を初期化して sweep エージェントを起動する場合は、YAML ファイルで sweep 設定を定義します。sweep の初期化から開始までをすべて Python スクリプトまたはノートブック内で行う場合は、Python の辞書で sweep を定義します。
</Note>

以下のセクションでは、sweep 設定の記述形式について説明します。sweep 設定のトップレベルキーの一覧については、[Sweep configuration options](/ja/products/wandb/sweeps/sweep-config-keys) を参照してください。

<h2 id="basic-structure">
  基本構造
</h2>

sweep 設定は、YAML または Python の辞書を使用して、キーと値のペアとネストされた構造で定義します。

sweep 設定のトップレベルキーでは、sweep の [`name`](/ja/products/wandb/sweeps/sweep-config-keys)、探索対象の [`parameters`](/ja/products/wandb/sweeps/sweep-config-keys#parameters)、探索 [`method`](/ja/products/wandb/sweeps/sweep-config-keys#method) など、sweep 探索の特性を定義します。

たとえば、次のコードスニペットは、同じ sweep 設定を YAML ファイルと Python の辞書でそれぞれ定義した例です。この sweep 設定では、`program`、`name`、`method`、`metric`、`parameters` の 5 つのトップレベルキーを指定しています。

<Tabs>
  <Tab title="CLI">
    コマンドラインから sweep をインタラクティブに管理するには、YAML ファイルで sweep 設定を定義します。

    ```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="Python script or notebook">
    トレーニングアルゴリズムを Python スクリプトまたはノートブックで定義する場合は、Python の辞書で sweep を定義します。

    次のコードスニペットでは、`sweep_configuration` という変数に sweep 設定を格納しています。

    ```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>

トップレベルの `parameters` キーには、`learning_rate`、`batch_size`、`epochs`、`optimizer` の各キーがネストされています。ネストされた各キーには、1 つ以上の値、分布、確率などを指定できます。詳細については、[Sweep configuration options](/ja/products/wandb/sweeps/sweep-config-keys) の [parameters](/ja/products/wandb/sweeps/sweep-config-keys#parameters) セクションを参照してください。

<h2 id="double-nested-parameters">
  二重にネストされたパラメーター
</h2>

関連するハイパーパラメーターをグループ化したい場合や、トレーニングコードがネストされた設定構造を前提としている場合は、ネストされたパラメーターを使用します。ネストされたパラメーターを定義するには、トップレベルのパラメーター名の下に `parameters` キーをさらに追加します。

次の例は、ネストされたパラメーター `nested_category_1`、`nested_category_2`、`nested_category_3` を含む sweep 設定です。それぞれに追加のパラメーター `momentum` と `weight_decay` が含まれています。以下のコード例では、同じ設定を YAML ファイルと 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="Python script or 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>
  sweep 設定で定義したネストされたパラメーターは、W\&B run の設定で指定されたキーを上書きします。

  たとえば、ネストされたデフォルト値を指定して run を初期化する `train.py` スクリプトがあるとします。

  ```python theme={"system"}
  def main():
      with  wandb.init(config={"nested_param": {"manual_key": 1}}) as run:
          # ここにトレーニングコードを記述します
  ```

  sweep 設定では、トップレベルの `"parameters"` キーの下にネストされたパラメーターを定義します。

  ```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)
  ```

  sweep の run では、`run.config["nested_param"]` に sweep 設定で定義されたサブツリー (`learning_rate` と `double_nested_param`) が反映されます。`wandb.init(config=...)` で定義された `manual_key` は含まれません。
</Warning>

<h2 id="sweep-configuration-template">
  sweep 設定のテンプレート
</h2>

新しい sweep 設定を作成する際は、このテンプレートを出発点として使用してください。このテンプレートには、よく使われるパラメーターと早期終了のパターンが含まれています。`hyperparameter_name` を実際のハイパーパラメーター名に置き換え、角かっこで囲まれた値もそれぞれ適切な値に置き換えてください。

```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}
```

数値を科学的記数法で表すには、YAML の `!!float` オペレーターを付加します。このオペレーターは値を浮動小数点数にキャストします。例: `min: !!float 1e-5`。詳細については、[マクロとカスタムコマンドの引数の例](#macro-and-custom-command-arguments-example)を参照してください。

<h2 id="sweep-configuration-examples">
  sweep 設定のサンプル
</h2>

以下の sweep 設定は、よくあるシナリオの例です。独自のトレーニングスクリプトに合わせて sweep を調整する際の参考にしてください。

<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="Python script or 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">
  Bayes hyperband の例
</h3>

次の例では、ベイズ探索と Hyperband による早期終了を組み合わせています。パフォーマンスの低い run を早い段階で停止し、より有望な設定にリソースを振り向けます。

```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
```

次のタブでは、`early_terminate` に反復回数の最小値または最大値を指定する方法を示します。

<Tabs>
  <Tab title="反復回数の最小値">
    この例のブラケットは `[3, 3*eta, 3*eta*eta, 3*eta*eta*eta]`、つまり `[3, 9, 27, 81]` です。

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

  <Tab title="反復回数の最大値">
    この例のブラケットは `[27/eta, 27/eta/eta]`、つまり `[9, 3]` です。

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

<h3 id="macro-and-custom-command-arguments-example">
  マクロとカスタムコマンド引数の例
</h3>

この例では、デフォルトの invocation よりも細かい制御が必要な場合に、sweep エージェントが各試行で実行するコマンドを構築する方法を示します。

より複雑なコマンドライン引数を指定する場合は、マクロを使用して環境変数、Python インタープリター、追加の引数を渡せます。[W\&B は定義済みのマクロ](/ja/products/wandb/sweeps/sweep-config-keys#command-macros)に加え、sweep 設定で指定できるカスタムコマンドライン引数をサポートしています。

たとえば、次の sweep 設定 (`sweep.yaml`) では、Python スクリプト (`run.py`) を実行するコマンドを定義しています。sweep の実行時には、`${env}`、`${interpreter}`、`${program}` の各マクロが適切な値に置き換えられます。

`--batch_size=${batch_size}`、`--test=True`、`--optimizer=${optimizer}` の各引数は、カスタムマクロを使用して、sweep 設定で定義された `batch_size`、`test`、`optimizer` パラメーターの値を渡します。

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

これにより、対応する Python スクリプト `run.py` で、`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()

# W&B run を初期化する
with wandb.init(project="test-project") as run:
    run.log({'validation_loss': 1})
```

sweep 設定で使用できる定義済みマクロの一覧については、[Sweep configuration options](/ja/products/wandb/sweeps/sweep-config-keys) の [コマンドマクロ](/ja/products/wandb/sweeps/sweep-config-keys#command-macros) セクションを参照してください。

<h4 id="boolean-arguments">
  真偽値の引数
</h4>

sweep でコマンド引数を介して真偽値のフラグを渡す場合、`argparse` はデフォルトでは真偽値の文字列を解釈しないため、トレーニングスクリプト側で追加の処理が必要です。

`argparse` モジュールは、デフォルトでは真偽値の引数をサポートしていません。真偽値の引数を定義するには、[`action`](https://docs.python.org/3/library/argparse.html#action) パラメーターを使用するか、カスタム関数を使用して真偽値の文字列表現を真偽値のタイプに変換します。

たとえば、次のコードスニペットを使用して真偽値の引数を定義できます。`ArgumentParser` に引数として `store_true` または `store_false` を渡します。

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

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

args.test  # --test を指定すると True、指定しないと False になります
```

真偽値の文字列表現を真偽値のタイプに変換するカスタム関数を定義することもできます。たとえば、次のコードスニペットでは、文字列を真偽値に変換する `str2bool` 関数を定義しています。

```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')
```


## Related topics

- [概要](/ja/products/wandb/weave/reference.md)