概要 - Weights & Biases Documentation

sweep は、ハイパーパラメーターの値を探索する戦略と、それらを評価するコードを組み合わせたものです。戦略は、すべての候補を試すシンプルなものから、Bayesian Optimization や Hyperband (BOHB) のような複雑なものまでさまざまです。このガイドでは、どのハイパーパラメーターを探索するか、どの探索戦略を使用するか、各 run をどのように評価するかを指定する sweep 設定の定義方法を示します。新しい sweep を設定する場合や、既存の設定を別の探索方法やパラメーター空間に合わせて調整する場合に使用してください。 sweep 設定は、Python の辞書または YAML ファイルで定義します。どちらの形式で sweep 設定を定義するかは、sweep をどのように管理したいかによって異なります。

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

以下のセクションでは、sweep 設定の書式を説明します。最上位レベルの sweep 設定キーの一覧については、Sweep configuration options を参照してください。

基本構造

sweep 設定は、YAML または Python の辞書のいずれかを使用して、キーと値のペアおよびネストされた構造で定義します。 sweep 設定のトップレベルキーを使用して、sweep 検索の特性を定義します。たとえば、sweep の name、検索対象の parameters、検索 method などです。たとえば、次のコードスニペットは、YAML ファイル内と Python の辞書内で定義した同じ sweep 設定を示しています。sweep 設定では、program、name、method、metric、parameters の 5 つのトップレベルキーを指定しています。

CLI
Python スクリプトまたはノートブック

コマンドラインから Sweeps をインタラクティブに管理するには、YAML ファイルで sweep 設定を定義します。

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

トレーニングアルゴリズムを Python スクリプトまたはノートブックで定義する場合は、Python の辞書データ構造で sweep を定義します。次のコードスニペットでは、sweep_configuration という名前の変数に sweep 設定を格納しています。

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

トップレベルの parameters キーの中には、learning_rate、batch_size、epochs、optimizer の各キーがネストされています。指定した各ネストキーには、1 つ以上の値、分布、確率などを指定できます。詳細は、Sweep configuration options の parameters セクションを参照してください。

二重にネストしたパラメーター

関連するハイパーパラメーターをまとめてグループ化したい場合や、トレーニングコードでネストされた設定構造を想定している場合は、ネストされたパラメーターを使用します。ネストされたパラメーターを定義するには、トップレベルのパラメーター名の下に parameters キーを追加します。次の例は、ネストされたパラメーター nested_category_1、nested_category_2、nested_category_3 を含む sweep 設定を示しています。各ネストされたパラメーターには、さらに momentum と weight_decay という 2 つのパラメーターが含まれています。次のコード例は、この設定を YAML ファイルと Python の辞書の両方で示しています。

CLI
Python script or 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]
        }
      }
    }
  }
}

sweep 設定で定義したネストされたパラメーターは、W&B の run 設定で指定したキーを上書きします。例として、ネストされたデフォルト値を使って run を初期化する train.py スクリプトがあるとします。

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

sweep 設定では、最上位の "parameters" キーの下にネストされたパラメーターを定義します。

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 は含まれません。

Sweep 設定テンプレート

このテンプレートを、新しい sweep 設定の出発点として使用してください。ここでは、最も一般的なパラメーターと早期終了のパターンを示しています。hyperparameter_name は使用するハイパーパラメーターの名に置き換え、角括弧で囲まれた値も必要に応じて置き換えてください。

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}

数値を科学表記で表すには、YAMLの!!float演算子を追加して、値を浮動小数点数として扱います。たとえば、min: !!float 1e-5です。詳細は、マクロとカスタムコマンド引数の例をご覧ください。

sweep 設定例

以下の sweep 設定は、一般的なシナリオを示したものです。ご自身のトレーニングスクリプトに合わせて sweep を調整する際の参考として使用してください。

CLI
Python スクリプトまたはノートブック

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

Bayes hyperbandの例

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

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 の反復回数の最小値または最大値を指定する方法を示します。

最小反復回数
最大反復回数

この例でのブラケットは [3, 3*eta, 3*eta*eta, 3*eta*eta*eta] で、[3, 9, 27, 81] になります。

early_terminate:
  type: hyperband
  min_iter: 3

この例でのブラケットは [27/eta, 27/eta/eta] で、[9, 3] になります。

early_terminate:
  type: hyperband
  max_iter: 27
  s: 2

マクロとカスタムコマンド引数の例

この例では、デフォルトの invocation よりも細かく制御したい場合に、sweep エージェントが各試行で実行するコマンドをどのように構築するかを示します。より複雑なコマンドライン引数では、マクロを使用して環境変数、Python インタープリター、追加の引数を渡せます。W&B は事前定義済みのマクロと、sweep 設定で指定できるカスタムコマンドライン引数をサポートしています。たとえば、次の sweep 設定 (sweep.yaml) では、Python スクリプト (run.py) を実行するコマンドを定義しており、sweep の実行時に ${env}、${interpreter}、${program} の各マクロが適切な値に置き換えられます。 --batch_size=${batch_size}、--test=True、--optimizer=${optimizer} の各引数ではカスタムマクロを使用して、sweep 設定で定義された batch_size、test、optimizer の各パラメーターの値を渡します。

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"

対応する Python スクリプト run.py では、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()

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

[sweep 設定で使用できる、あらかじめ定義されたマクロの一覧については、Sweep configuration options のコマンドマクロセクションを参照してください。](/models/sweeps/sweep-config-keys#command-macros)

ブール引数

sweep がコマンド引数としてブールフラグを渡す場合、argparse はデフォルトではブール値の文字列を解釈しないため、トレーニングスクリプトで追加の処理が必要です。 argparse モジュールは、デフォルトではブール引数をサポートしていません。ブール引数を定義するには、action パラメーターを使用するか、ブール値の文字列表現をブール型に変換するカスタム関数を使用します。たとえば、次のコードスニペットを使用してブール引数を定義できます。ArgumentParser の引数として store_true または store_false を渡します:

import wandb
import argparse

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

args.test  # --test が渡された場合は True、そうでない場合は False

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

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

​基本構造

​二重にネストしたパラメーター

​Sweep 設定テンプレート

​sweep 設定例

​Bayes hyperbandの例

​マクロとカスタムコマンド引数の例

​ブール引数

基本構造

二重にネストしたパラメーター

Sweep 設定テンプレート

sweep 設定例

Bayes hyperbandの例

マクロとカスタムコマンド引数の例

ブール引数