CLI (v2) スイープ ジョブ YAML スキーマ

適用対象: Azure CLI ML 拡張機能 v2 (現行)

ソース JSON スキーマは https://azuremlschemas.azureedge.net/latest/sweepJob.schema.json にあります。

Note

このドキュメントで詳しく説明されている YAML 構文は、最新バージョンの ML CLI v2 拡張機能の JSON スキーマに基づいています。 この構文は、ML CLI v2 拡張機能の最新バージョンでのみ動作することが保証されています。 以前のバージョンの拡張機能のスキーマについては、https://azuremlschemasprod.azureedge.net/ でご確認いただけます。

YAML 構文

キー 種類 説明 使用できる値 既定値
$schema string YAML スキーマ。 Azure Machine Learning 用 VS Code 拡張機能を使用して YAML ファイルを作成する場合は、ファイルの先頭に $schema を含めることで、スキーマとリソースの入力候補を呼び出すことができます。
type const 必須。 ジョブの種類。 sweep sweep
name string ジョブの名前。 ワークスペース内のすべてのジョブで一意である必要があります。 省略した場合、Azure Machine Learning によって名前の GUID が自動生成されます。
display_name string スタジオ UI でのジョブの表示名。 ワークスペース内で一意ではない場合があります。 省略した場合、Azure Machine Learning により、表示名として、人間が判読できる形容詞と名詞の識別子が自動生成されます。
experiment_name string ジョブを整理するための実験名。 各ジョブの実行レコードは、スタジオの [実験] タブの対応する実験の下に整理されます。省略した場合、Azure Machine Learning により、既定で、ジョブが作成された作業ディレクトリの名前が設定されます。
description string ジョブの説明。
tags object ジョブのタグの辞書。
sampling_algorithm object 必須。 search_space で使用するハイパーパラメーター サンプリング アルゴリズム。 RandomSamplingAlgorithmGridSamplingAlgorithmBayesianSamplingAlgorithm のいずれか。
search_space object 必須。 ハイパーパラメーター検索空間の辞書。 キーはハイパーパラメーターの名前で、値はパラメーター式です。

ハイパーパラメーターは、${{ search_space.<hyperparameter> }} 式を使用して trial.command で参照できます。
search_space.<hyperparameter> object 使用できる式のセットについては、「パラメーター式」を参照してください。
objective.primary_metric string 必須。 各トライアル ジョブによって報告されるプライマリ メトリックの名前。 メトリックは、同じ対応するメトリック名を持つ mlflow.log_metric() を使用して、ユーザーのトレーニング スクリプトに記録する必要があります。
objective.goal string 必須。 objective.primary_metric の最適化の目標。 maximize, minimize
early_termination object 使用する早期終了ポリシー。 指定したポリシーの条件が満たされると、トライアル ジョブはキャンセルされます。 省略した場合、早期終了ポリシーは適用されません。 BanditPolicyMedianStoppingPolicy、または TruncationSelectionPolicy のいずれか。
limits object スイープ ジョブの制限。 「limits キーの属性」を参照してください。
compute string 必須。 azureml:<compute_name> 構文を使用してジョブを実行するコンピューティング先の名前。
trial object 必須。 各トライアルのジョブ テンプレート。 各トライアル ジョブには、システムが search_space からサンプリングするハイパーパラメーター値のさまざまな組み合わせが提供されます。 「trial キーの属性」を参照してください。
inputs object ジョブへの入力の辞書。 キーは、ジョブのコンテキスト内の入力の名前であり、値は入力値です。

入力は、${{ inputs.<input_name> }} 式を使用して command で参照できます。
inputs.<input_name> 数値、整数、ブール値、文字列、またはオブジェクト リテラル値 (型番号、整数、ブール値、または文字列) のいずれか、またはジョブ入力データ仕様を含むオブジェクト。
outputs object ジョブの出力構成の辞書。 キーはジョブのコンテキスト内の出力の名前であり、値は出力構成です。

出力は、${{ outputs.<output_name> }} 式を使用して command で参照できます。
outputs.<output_name> object オブジェクトは空のままにしておくことができます。この場合、既定では出力の種類は uri_folder になり、Azure Machine Learning では出力の出力場所がシステム生成されます。 出力ディレクトリへのファイルは、読み取り/書き込みマウントを使用して書き込まれます。 出力に別のモードを指定する場合は、ジョブ出力仕様を含むオブジェクトを指定します。
identity object ID は、データアクセスに使用されます。 UserIdentityConfigurationManagedIdentityConfiguration、または None を指定できます。 UserIdentityConfiguration の場合、ジョブの送信者の ID を使用して入力データにアクセスし、結果を出力フォルダーに書き込みます。それ以外の場合は、コンピューティング 先のマネージド ID が使用されます。

サンプリング アルゴリズム

RandomSamplingAlgorithm

キー 種類 説明 使用できる値 既定値
type const 必須。 サンプリング アルゴリズムの種類。 random
seed 整数 乱数生成の初期化に使用するランダム シード。 省略した場合、既定のシード値は null になります。
rule string 使用するランダム サンプリングの種類。 既定値の random では単純な均一ランダム サンプリングが使用され、sobol では Sobol 準ランダム シーケンスが使用されます。 random, sobol random

GridSamplingAlgorithm

キー 種類 説明 使用できる値
type const 必須。 サンプリング アルゴリズムの種類。 grid

BayesianSamplingAlgorithm

キー 種類 説明 使用できる値
type const 必須。 サンプリング アルゴリズムの種類。 bayesian

早期終了ポリシー

BanditPolicy

キー 種類 説明 使用できる値 既定値
type const 必須。 ポリシーの種類。 bandit
slack_factor number 最高パフォーマンスのトライアルからの許容される距離を計算するために使用される比率。 slack_factor または slack_amount のいずれかが必須です。
slack_amount number 最高パフォーマンスのトライアルからの許容される絶対距離。 slack_factor または slack_amount のいずれかが必須です。
evaluation_interval 整数 (integer) ポリシーを適用する頻度。 1
delay_evaluation 整数 (integer) 最初のポリシー評価を遅延する間隔の数。 指定した場合、delay_evaluation 以上の evaluation_interval の倍数ごとにポリシーが適用されます。 0

MedianStoppingPolicy

キー 種類 説明 使用できる値 既定値
type const 必須。 ポリシーの種類。 median_stopping
evaluation_interval 整数 (integer) ポリシーを適用する頻度。 1
delay_evaluation 整数 (integer) 最初のポリシー評価を遅延する間隔の数。 指定した場合、delay_evaluation 以上の evaluation_interval の倍数ごとにポリシーが適用されます。 0

TruncationSelectionPolicy

キー 種類 説明 使用できる値 既定値
type const 必須。 ポリシーの種類。 truncation_selection
truncation_percentage 整数 (integer) 必須。 各評価期間にキャンセルされるトライアル ジョブの割合。
evaluation_interval 整数 (integer) ポリシーを適用する頻度。 1
delay_evaluation 整数 (integer) 最初のポリシー評価を遅延する間隔の数。 指定した場合、delay_evaluation 以上の evaluation_interval の倍数ごとにポリシーが適用されます。 0

パラメーター式

choice

キー 種類 説明 使用できる値
type const 必須。 式の型。 choice
values array 必須。 選択する不連続値の一覧。

randint

キー 種類 説明 使用できる値
type const 必須。 式の型。 randint
upper 整数 (integer) 必須。 整数の範囲の排他的な上限。

qlognormal、qnormal

キー 種類 説明 使用できる値
type const 必須。 式の型。 qlognormal, qnormal
mu number 必須。 正規分布の平均。
sigma number 必須。 正規分布の標準偏差。
q 整数 (integer) 必須。 スムージング係数。

qloguniform、quniform

キー 種類 説明 使用できる値
type const 必須。 式の型。 qloguniform, quniform
min_value number 必須。 範囲内の最小値 (包含的)。
max_value number 必須。 範囲内の最大値 (包含的)。
q 整数 (integer) 必須。 スムージング係数。

lognormal、normal

キー 種類 説明 使用できる値
type const 必須。 式の型。 lognormal, normal
mu number 必須。 正規分布の平均。
sigma number 必須。 正規分布の標準偏差。

loguniform

キー 種類 説明 使用できる値
type const 必須。 式の型。 loguniform
min_value number 必須。 範囲内の最小値は exp(min_value) (包含的) になります。
max_value number 必須。 範囲内の最大値は exp(max_value) (包含的) になります。

uniform

キー 種類 説明 使用できる値
type const 必須。 式の型。 uniform
min_value number 必須。 範囲内の最小値 (包含的)。
max_value number 必須。 範囲内の最大値 (包含的)。

limits キーの属性

キー 種類 説明 既定値
max_total_trials 整数 (integer) トライアル ジョブの最大数。 1000
max_concurrent_trials 整数 (integer) 同時に実行できるトライアル ジョブの最大数。 既定値は max_total_trials です。
timeout 整数 (integer) スイープ ジョブ全体を実行できる最大時間 (秒単位)。 この制限に達すると、システムにより、すべてのトライアルを含めてスイープ ジョブがキャンセルされます。 5184000
trial_timeout 整数 (integer) 各トライアル ジョブを実行できる最大時間 (秒単位)。 この制限に達すると、システムによってトライアルがキャンセルされます。

trial キーの属性

キー 種類 説明 既定値
command string 必須。 実行するコマンドです。
code string アップロードしてジョブに使用するソース コード ディレクトリへのローカル パス。
environment 文字列またはオブジェクト 必須。 ジョブに使用する環境。 これは、ワークスペース内のバージョン管理される既存の環境への参照、またはインライン環境仕様のいずれかになります。

既存の環境を参照するには、azureml:<environment-name>:<environment-version> 構文を使用します。

環境をインラインで定義するには、環境スキーマに従います。 name プロパティと version プロパティは、インライン環境ではサポートされていないため、除外します。
environment_variables object コマンドが実行されるプロセスに設定する環境変数の名前と値のペアの辞書。
distribution object 分散トレーニング シナリオの配布構成。 MpiConfigurationPyTorchConfigurationTensorFlowConfiguration のいずれか。
resources.instance_count 整数 (integer) ジョブに使用するノードの数。 1

配布構成

MpiConfiguration
キー 種類 説明 使用できる値
type const 必須。 配布の種類。 mpi
process_count_per_instance 整数 (integer) 必須。 ジョブに対して起動するノードあたりのプロセスの数。
PyTorchConfiguration
キー 種類 説明 使用できる値 既定値
type const 必須。 配布の種類。 pytorch
process_count_per_instance 整数 (integer) ジョブに対して起動するノードあたりのプロセスの数。 1
TensorFlowConfiguration
キー 種類 説明 使用できる値 既定値
type const 必須。 配布の種類。 tensorflow
worker_count 整数 (integer) ジョブに対して起動するワーカーの数。 既定値は resources.instance_count です。
parameter_server_count 整数 (integer) ジョブに対して起動するパラメーター サーバーの数。 0

ジョブの入力

キー 種類 説明 使用できる値 既定値
type string ジョブ入力の種類。 1 つのファイル ソースを指す入力データの場合は uri_file、フォルダー ソースを指す入力データの場合は uri_folder を指定します。 データ アクセスの詳細について確認してください uri_file, uri_folder, mltable, mlflow_model uri_folder
path string 入力として使用するデータのパス。 これは、いくつかの方法で指定できます。

- データ ソース ファイルまたはフォルダーへのローカル パス (例: path: ./iris.csv)。 データはジョブの送信中にアップロードされます。

- 入力として使用するファイルまたはフォルダーへのクラウド パスの URI。 サポートされる URI の種類は azuremlhttpswasbsabfssadl です。 azureml:// URI 形式の使用方法の詳細については、コア yaml 構文に関する記事を参照してください。

- 入力として使用する既存の登録済み Azure Machine Learning データ資産。 登録済みデータ資産を参照するには、azureml:<data_name>:<data_version> 構文または azureml:<data_name>@latest (そのデータ資産の最新バージョンを参照する場合) を使用します。(例: path: azureml:cifar10-data:1 または path: azureml:cifar10-data@latest)。
mode string コンピューティング先にデータを配信する方法のモード。

読み取り専用マウントの場合 (ro_mount)、データはマウント パスとして使用されます。 フォルダーはフォルダーとしてマウントされ、ファイルはファイルとしてマウントされます。 Azure Machine Learning では、マウント パスへの入力が解決されます。

download モードの場合、データはコンピューティング先にダウンロードされます。 Azure Machine Learning では、ダウンロードされたパスへの入力が解決されます。

データ自体をマウントまたはダウンロードするのではなく、データ成果物の保存場所の URL のみが必要な場合は、モード direct を使用できます。 これにより、保存場所の URL がジョブ入力として渡されます。 この場合、ストレージにアクセスするための資格情報を処理する責任があります。
ro_mount, download, direct ro_mount

ジョブ出力

キー 種類 説明 使用できる値 既定値
type string ジョブ出力の種類。 既定の uri_folder 種類の場合、出力はフォルダーに対応します。 uri_file, uri_folder, mltable, mlflow_model uri_folder
mode string 出力ファイルを宛先ストレージに配信する方法のモード。 読み取り/書き込みマウント モード (rw_mount) の場合、出力ディレクトリはマウントされたディレクトリになります。 アップロード モードの場合、書き込まれたファイルがジョブの最後にアップロードされます。 rw_mount, upload rw_mount

ID の構成

UserIdentityConfiguration

キー 種類 説明 使用できる値
type const 必須。 ID の型。 user_identity

ManagedIdentityConfiguration

キー 種類 説明 使用できる値
type const 必須。 ID の型。 managed または managed_identity

解説

az ml job コマンドは、Azure Machine Learning ジョブを管理するために使用できます。

例は、GitHub リポジトリの例にあります。 以下にいくつか示します。

YAML: hello sweep

$schema: https://azuremlschemas.azureedge.net/latest/sweepJob.schema.json
type: sweep
trial:
  command: >-
    python hello-sweep.py
    --A ${{inputs.A}}
    --B ${{search_space.B}}
    --C ${{search_space.C}}
  code: src
  environment: azureml:AzureML-sklearn-1.0-ubuntu20.04-py38-cpu@latest
inputs:
  A: 0.5
sampling_algorithm: random
search_space:
  B:
    type: choice
    values: ["hello", "world", "hello_world"]
  C:
    type: uniform
    min_value: 0.1
    max_value: 1.0
objective:
  goal: minimize
  primary_metric: random_metric
limits:
  max_total_trials: 4
  max_concurrent_trials: 2
  timeout: 3600
display_name: hello-sweep-example
experiment_name: hello-sweep-example
description: Hello sweep job example.

YAML: 基本的な Python モデルのハイパーパラメーター調整

$schema: https://azuremlschemas.azureedge.net/latest/sweepJob.schema.json
type: sweep
trial:
  code: src
  command: >-
    python main.py 
    --iris-csv ${{inputs.iris_csv}}
    --C ${{search_space.C}}
    --kernel ${{search_space.kernel}}
    --coef0 ${{search_space.coef0}}
  environment: azureml:AzureML-sklearn-0.24-ubuntu18.04-py37-cpu@latest
inputs:
  iris_csv: 
    type: uri_file
    path: wasbs://datasets@azuremlexamples.blob.core.windows.net/iris.csv
compute: azureml:cpu-cluster
sampling_algorithm: random
search_space:
  C:
    type: uniform
    min_value: 0.5
    max_value: 0.9
  kernel:
    type: choice
    values: ["rbf", "linear", "poly"]
  coef0:
    type: uniform
    min_value: 0.1
    max_value: 1
objective:
  goal: minimize
  primary_metric: training_f1_score
limits:
  max_total_trials: 20
  max_concurrent_trials: 10
  timeout: 7200
display_name: sklearn-iris-sweep-example
experiment_name: sklearn-iris-sweep-example
description: Sweep hyperparemeters for training a scikit-learn SVM on the Iris dataset.

次のステップ