概要

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

W&B Sweep は、ハイパーパラメーターの値を探索する戦略と、それらを評価するコードを組み合わせたものです。戦略は、すべての候補を試すシンプルなものから、Bayesian Optimization や Hyperband (BOHB) のような複雑なものまでさまざまです。

sweep 設定は、Python の辞書 または YAML ファイルで定義します。どちらの形式で sweep 設定を定義するかは、sweep をどのように管理したいかによって異なります。

コマンドラインから sweep を初期化し、sweep agent を起動する場合は、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

コマンドライン (CLI) から 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 スクリプトまたはノートブックで定義する場合は、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、epoch、optimizer の各キーがネストされています。指定した各ネストキーには、1 つ以上の値、分布、確率などを指定できます。詳細は、Sweep configuration options の parameters セクションを参照してください。

​

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

sweep 設定では、ネストされたパラメーターをサポートしています。ネストされたパラメーターを定義するには、トップレベルのパラメーター名の下に parameters キーを追加します。

次の例は、nested_category_1、nested_category_2、nested_category_3 という 3 つのネストされたパラメーターを含む sweep 設定を示しています。各ネストされたパラメーターには、さらに momentum と weight_decay という 2 つのパラメーターが含まれています。

nested_category_1、nested_category_2、nested_category_3 はプレースホルダーです。実際のユースケースに合わせた名前に置き換えてください。

次のコードスニペットは、YAML ファイルと Python 辞書の両方でネストされたパラメーターを定義する方法を示しています。

CLI

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]

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

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 設定テンプレート

以下のテンプレートは、パラメーターを設定し、検索条件を指定する方法を示しています。hyperparameter_name はハイパーパラメーター名に、<> で囲まれた値は適切な値に置き換えてください。

config.yaml

program: <insert>
method: <insert>
parameter:
  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: 0
  eta: 0
  max_iter: 0
command:
- ${Command macro}
- ${Command macro}
- ${Command macro}
- ${Command macro}      

科学的記数法で数値を表すには、YAML の !!float 演算子を追加して、その値を浮動小数点数にキャストします。たとえば、min: !!float 1e-5 です。コマンドの例を参照してください。

​

sweep 設定例

CLI

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

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

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

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

​

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

より複雑なコマンドライン引数では、マクロを使用して環境変数、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

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('test-project') as run:
    run.log({'validation_loss':1})

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

​

ブール引数

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 does not support boolean arguments by default.
  """
  if isinstance(v, bool):
      return v
  return v.lower() in ('yes', 'true', 't', '1')