概要 - CoreWeave Docs

sweep は、ハイパーパラメーターの値を探索する戦略と、それらの値を評価するコードを組み合わせたものです。戦略には、すべての選択肢を試すような単純なものから、Bayesian Optimization and Hyperband (BOHB) のような複雑なものまであります。このガイドでは、探索するハイパーパラメーター、使用する探索戦略、各 run の評価方法を指定する sweep 設定の定義方法を説明します。新しい sweep をセットアップするときや、既存の設定を別の探索手法やパラメーター空間に合わせて変更するときに参照してください。 sweep 設定は、Python の辞書または YAML ファイルで定義します。どちらを使うかは、sweep をどのように管理するかによって決まります。

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

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

基本構造

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

CLI
Python script or notebook

コマンドラインから sweep をインタラクティブに管理するには、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 が含まれています。以下のコード例では、同じ設定を 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 script or notebook

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 のコマンドマクロセクションを参照してください。

真偽値の引数

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 の例

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

真偽値の引数