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

[アーティクル]
03/10/2024

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

Note

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

YAML 構文

キー	Type	説明	使用できる値	既定値
`$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 ラーニングの既定値`experiment_name`は、ジョブが作成された作業ディレクトリの名前になります。
`description`	string	ジョブの説明。
`tags`	object	ジョブのタグの辞書。
`sampling_algorithm`	object	必須。 `search_space` で使用するハイパーパラメーターサンプリングアルゴリズム。 RandomSamplingAlgorithm、GridSamplingAlgorithm、BayesianSamplingAlgorithm のいずれか。
`search_space`	object	必須。ハイパーパラメーター検索空間の辞書。ハイパーパラメーター名はキーであり、値はパラメーター式です。ハイパーパラメーターは、式で`trial.command${{ search_space.<hyperparameter> }}`参照できます。
`search_space.<hyperparameter>`	オブジェクト	使用できる一連の式については、パラメーター式を参照してください。
`objective.primary_metric`	string	必須。各トライアルジョブによって報告されるプライマリメトリックの名前。メトリックは、同じ対応するメトリック名を使用して `mlflow.log_metric()` 、ユーザーのトレーニングスクリプトに記録する必要があります。
`objective.goal`	string	必須。 `objective.primary_metric` の最適化の目標。	`maximize`, `minimize`
`early_termination`	object	使用する早期終了ポリシー。指定したポリシーの条件が満たされると、トライアルジョブはキャンセルされます。省略した場合、早期終了ポリシーは適用されません。 BanditPolicy、MedianStoppingPolicy、または TruncationSelectionPolicy のいずれか。
`limits`	object	スイープジョブの制限。「`limits` キーの属性」を参照してください。
`compute`	string	必須。構文を使用して、ジョブを実行するコンピューティング先の `azureml:<compute_name>` 名前。
`trial`	オブジェクト	必須。各トライアルのジョブテンプレート。各試用ジョブには、システムによってサンプリングされるハイパーパラメーター値の異なる組み合わせが用意されています `search_space`。キーの属性にアクセス`trial`します。
`inputs`	オブジェクト	ジョブへの入力の辞書。キーは、ジョブのコンテキスト内の入力の名前であり、値は入力値です。入力は、`${{ inputs.<input_name> }}` 式を使用して `command` で参照できます。
`inputs.<input_name>`	number、integer、boolean、string、または object	リテラル値 (型番号、整数、ブール値、または文字列) の 1 つ、またはジョブ入力データの指定を含むオブジェクト。
`outputs`	オブジェクト	ジョブの出力構成の辞書。キーはジョブのコンテキスト内の出力の名前であり、値は出力構成です。出力は、`${{ outputs.<output_name> }}` 式を使用して `command` で参照できます。
`outputs.<output_name>`	オブジェクト	オブジェクトは空のままにしておくことができます。その場合、既定では出力の`uri_folder`種類が設定され、Azure Machine ラーニングシステムによって出力の出力場所が生成されます。出力ディレクトリへのすべてのファイルは、読み取り/書き込みマウントを使用して書き込まれます。出力に別のモードを指定するには、ジョブ出力仕様を含むオブジェクトを指定します。
`identity`	オブジェクト	ID は、データアクセスに使用されます。ユーザー ID 構成、マネージド ID 構成、またはなしを指定できます。 UserIdentityConfiguration の場合、ジョブの送信者の ID を使用して入力データにアクセスし、結果を出力フォルダーに書き込みます。それ以外の場合は、コンピューティング先のマネージド ID が使用されます。

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

RandomSamplingAlgorithm

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

GridSamplingAlgorithm

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

BayesianSamplingAlgorithm

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

早期終了ポリシー

BanditPolicy

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

TruncationSelectionPolicy

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

パラメーター式

選択肢

キー	Type	説明	使用できる値
`type`	const	必須。式の型。	`choice`
`values`	配列	必須。選択する個別の値の一覧。

Randint

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

Qlognormal、qnormal

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

Qloguniform、quniform

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

Lognormal、normal

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

Loguniform

キー	Type	説明	使用できる値
`type`	const	必須。式の型。	`loguniform`
`min_value`	数値	必須。範囲内の最小値は (両端を含む) です `exp(min_value)` 。
`max_value`	数値	必須。範囲内の最大値は (両端を含む) です `exp(max_value)` 。

Uniform

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

`limits` キーの属性

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

`trial` キーの属性

キー	Type	説明	既定値
`command`	string	必須。実行するコマンドです。
`code`	string	アップロードしてジョブに使用するソースコードディレクトリへのローカルパス。
`environment`	文字列またはオブジェクト	必須。ジョブに使用する環境。この値は、ワークスペース内の既存のバージョン管理された環境への参照、またはインライン環境仕様のいずれかになります。既存の環境を参照するには、`azureml:<environment-name>:<environment-version>` 構文を使用します。環境をインラインで定義するには、環境スキーマに従います。インライン環境では `name` サポートされていないため、プロパティと `version` プロパティを除外します。
`environment_variables`	オブジェクト	コマンドが実行されるプロセスに設定する環境変数の名前と値のペアの辞書。
`distribution`	object	分散トレーニングシナリオの配布構成。 Mpi 構成、PyTorch 構成、または TensorFlow 構成のいずれか。
`resources.instance_count`	integer	ジョブに使用するノードの数。	`1`

配布構成

MpiConfiguration

キー	Type	説明	使用できる値
`type`	const	必須。配布の種類。	`mpi`
`process_count_per_instance`	整数 (integer)	必須。ジョブに対して起動するノードあたりのプロセスの数。

PyTorchConfiguration

キー	Type	説明	使用できる値	既定値
`type`	const	必須。配布の種類。	`pytorch`
`process_count_per_instance`	整数 (integer)	ジョブに対して起動するノードあたりのプロセスの数。		`1`

TensorFlowConfiguration

キー	Type	説明	使用できる値	既定値
`type`	const	必須。配布の種類。	`tensorflow`
`worker_count`	整数 (integer)	ジョブに対して起動するワーカーの数。		既定値は `resources.instance_count` です。
`parameter_server_count`	整数 (integer)	ジョブに対して起動するパラメーターサーバーの数。		`0`

ジョブの入力

キー	Type	説明	使用できる値	既定値
`type`	string	ジョブ入力の種類。 1 つのファイルソースを指す入力データの場合は `uri_file`、フォルダーソースを指す入力データの場合は `uri_folder` を指定します。詳細については、データアクセスの詳細を参照してください。	`uri_file`、`uri_folder`、、 `mltablemlflow_model`	`uri_folder`
`path`	string	入力として使用するデータのパス。この値は、いくつかの方法で指定できます。 - データソースファイルまたはフォルダーへのローカルパス (例: `path: ./iris.csv`)。ジョブの送信中にデータがアップロードされます。 - 入力として使用するファイルまたはフォルダーへのクラウドパスの URI。サポートされる URI の種類は `azureml`、`https`、`wasbs`、`abfss`、`adl` です。 URI 形式の使用の`azureml://`詳細については、Core 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 ラーニングは、入力をマウントパスに解決します。モードの場合 `download` 、データはコンピューティング先にダウンロードされます。 Azure Machine ラーニングは、ダウンロードしたパスへの入力を解決します。データ自体をマウントまたはダウンロードする代わりに、データ成果物または成果物の保存場所の URL だけを使用します `direct` 。これにより、ジョブ入力としてストレージの場所の URL が渡されます。この場合、ストレージにアクセスするための資格情報を処理する責任があります。	`ro_mount`、 `downloaddirect`	`ro_mount`

ジョブ出力

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

ID の構成

UserIdentityConfiguration

キー	Type	説明	使用できる値
`type`	const	必須です。 ID の型。	`user_identity`

ManagedIdentityConfiguration

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

解説

このコマンドをaz ml job使用して、Azure Machine ラーニングジョブを管理できます。

例

例については、 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://registries/azureml/environments/sklearn-1.0/labels/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://registries/azureml/environments/sklearn-1.0/labels/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.

次のステップ

CLI (v2) をインストールして使用する

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