CLI (v2) コア YAML 構文

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

すべての Azure Machine Learning エンティティには、スキーマ化された YAML 表現があります。 .yml 拡張子または .yaml 拡張子を持つ YAML 構成ファイルから新しいエンティティを作成できます。

この記事では、これらの YAML ファイルを構成するときに生じるコア構文の概念の概要について説明します。

Azure Machine Learning エンティティの参照

Azure Machine Learning では、YAML ファイルを構成するときに既存の Azure Machine Learning エンティティを参照するための参照構文 (短い形式と長い形式で構成) が提供されます。 たとえば、ワークスペース内の既存の登録済み環境を参照して、ジョブの環境として使用できます。

Azure Machine Learning アセットの参照

Azure Machine Learning アセット (環境、モデル、データ、コンポーネント) を参照するには、次の 2 つのオプションがあります。

• アセットの明示的なバージョンを参照する:

  • 短い構文: azureml:<asset_name>:<asset_version>
  • アセットの Azure Resource Manager (ARM) リソース ID を含む長い構文:

  azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/environments/<environment-name>/versions/<environment-version>
  

• アセットの最新バージョンを参照する:

  一部のシナリオでは、実際のバージョン文字列自体を明示的に検索して指定することなく、アセットの最新バージョンを参照する必要がある場合があります。 最新バージョンは、特定の名前でアセットの作成された最新バージョン (最新とも呼ばれる) として定義されます。

  次の構文を使用して、最新バージョンを参照できます: azureml:<asset_name>@latest。 Azure Machine Learning では、ワークスペース内の明示的なアセット バージョンへの参照が解決されます。

Azure Machine Learning リソースを参照する

Azure Machine Learning リソース (コンピューティングなど) を参照するには、次のいずれかの構文を使用できます。

• 短い構文: azureml:<resource_name>
• リソースの ARM リソース ID を含む長い構文:

azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/computes/<compute-name>

Azure Machine Learning データ参照 URI

Azure Machine Learning では、Azure ストレージ サービス内のデータを指す便利なデータ参照 URI 形式を使用できます。 これは、YAML ファイルでクラウド ストレージの場所を指定する必要があるシナリオで使用できます。たとえば、ストレージ内のファイルから Azure Machine Learning モデルを作成したり、ジョブに入力として渡すデータを指したりする場合に使用できます。

このデータ URI 形式を使用するには、参照するストレージ サービスを最初にワークスペースにデータストアとして登録する必要があります。 Azure Machine Learning は、データストアの作成時に指定した資格情報を使用してデータ アクセスを処理します。

形式は、現在のワークスペースのデータストアと、指すファイルまたはフォルダーへのデータストアのパスで構成されます。

azureml://datastores/<datastore-name>/paths/<path-on-datastore>/

次に例を示します。

• azureml://datastores/workspaceblobstore/paths/example-data/
• azureml://datastores/workspaceblobstore/paths/example-data/iris.csv

Azure Machine Learning データ参照 URI に加えて、Azure Machine Learning では、パブリック http や https URI だけではなく、https、wasbs、abfss、adl などのダイレクト ストレージ URI プロトコルもサポートされています。

Azure Machine Learning ジョブとコンポーネントを構成するための式の構文

v2 ジョブとコンポーネントの YAML ファイルを使用すると、式を使用してさまざまなシナリオのコンテキストにバインドできます。 重要な使用例として、構成の作成時には認識されていない可能性があるが、実行時に解決する必要が生じる値に式を使用する場合を挙げられます。

次の構文を使用して、Azure Machine Learning に、式を文字列として扱うのではなく、式を評価するように指示します。

${{ <expression> }}

サポートされているシナリオについて、以下で説明します。

ジョブの inputs コンテキストと outputs コンテキストで command をパラメーター化する

ジョブへの入力として、リテラル値、URI パス、および登録済みの Azure Machine Learning データ アセットを指定できます。 その後、${{inputs.<input_name>}} 構文を使用して、それらの入力への参照を使用し、command をパラメーター化できます。 リテラル入力への参照は実行時にリテラル値に解決されます。一方、データ入力への参照は、(指定された mode に応じて) ダウンロード パスまたはマウント パスに解決されます。

同様に、ジョブへの出力は、command でも参照できます。 outputs 辞書に指定された名前付き出力ごとに、Azure Machine Learning は、ファイルを書き込むことができる既定のデータストア上に出力の場所をシステム生成します。 名前付き出力の出力場所は、テンプレート化されたパス <default-datastore>/azureml/<job-name>/<output_name>/ に基づいて決定されます。 ${{outputs.<output_name>}} 構文を使用して command をパラメーター化すると、システム生成されたパスにその参照が解決されます。これにより、スクリプトでジョブからその場所にファイルを書き込めるようになります。

コマンド ジョブ YAML ファイルの次の例では、command は、リテラル入力とデータ入力という 2 つの入力と、1 つの出力でパラメーター化されます。 実行時に、${{inputs.learning_rate}} 式は 0.01 に解決され、${{inputs.iris}} 式は iris.csv ファイルのダウンロード パスに解決されます。 ${{outputs.model_dir}} は、model_dir 出力に対応するシステム生成の出力場所のマウント パスに解決されます。

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: ./src
command: python train.py --lr ${{inputs.learning_rate}} --training-data ${{inputs.iris}} --model-dir ${{outputs.model_dir}}
environment: azureml:AzureML-Minimal@latest
compute: azureml:cpu-cluster
inputs:
  learning_rate: 0.01
  iris:
    type: uri_file
    path: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv
    mode: download
outputs:
  model_dir:

スイープ ジョブの search_space コンテキストで command をパラメーター化する

また、スイープ ジョブでハイパーパラメーターのチューニングを実行する場合も、ジョブの作成中にハイパーパラメーターの実際の値が認識されないため、この式構文を使用します。 スイープ ジョブを実行すると、Azure Machine Learning では、search_space に基づいて各試用版のハイパーパラメーター値が選択されます。 トレーニング スクリプト内のこれらの値にアクセスするには、スクリプトのコマンド ライン引数を使用してそれらを渡す必要があります。 これを行うには、trial.command で ${{search_space.<hyperparameter>}} 構文を使用します。

スイープ ジョブ YAML ファイルの次の例では、trial.command の ${{search_space.learning_rate}} および ${{search_space.boosting}} 参照は、試用ジョブが実行のために送信される際に、各試用版で選択された実際のハイパーパラメーター値に解決されます。

$schema: https://azuremlschemas.azureedge.net/latest/sweepJob.schema.json
type: sweep
sampling_algorithm:
  type: random
search_space:
  learning_rate:
    type: uniform
    min_value: 0.01
    max_value: 0.9
  boosting:
    type: choice
    values: ["gbdt", "dart"]
objective:
  goal: minimize
  primary_metric: test-multi_logloss
trial:
  code: ./src
  command: >-
    python train.py 
    --training-data ${{inputs.iris}}
    --lr ${{search_space.learning_rate}}
    --boosting ${{search_space.boosting}}
  environment: azureml:AzureML-Minimal@latest
inputs:
  iris:
    type: uri_file
    path: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv
    mode: download
compute: azureml:cpu-cluster

パイプライン ジョブのステップ間で入力と出力をバインドする

式は、パイプライン ジョブのステップ間で入力と出力をバインドするためにも使用されます。 たとえば、パイプライン内の 1 つのジョブ (job B) の入力を別のジョブ (job A) の出力にバインドできます。 このように使用すると、パイプライン グラフ内の依存関係フローが Azure Machine Learning にシグナル送信され、job B は job A の後に実行されるようになります。これは、job A の出力が job B の入力として必要であるからです。

パイプライン ジョブ YAML ファイルの場合、それぞれの子ジョブの inputs セクションと outputs セクションは、親コンテキスト (トップ レベルのパイプライン ジョブ) 内で評価されます。 一方、command は現在のコンテキスト (子ジョブ) に解決されます。

パイプライン ジョブで入力と出力をバインドする方法は 2 つあります。

パイプライン ジョブの上位の入力と出力にバインドする

構文 ${{parent.inputs.<input_name>}} または ${{parent.outputs.<output_name>}} を使用して、子ジョブの入力または出力 (パイプライン ステップ) を、上位の親パイプライン ジョブの入力/出力にバインドできます。 この参照は parent コンテキスト、つまり、上位の入力/出力に解決されます。

次の例では、最初の prep ステップの入力 (raw_data) が、${{parent.inputs.input_data}} を介して上位パイプラインの入力にバインドされています。 最後の train ステップの出力 (model_dir) が、${{parent.outputs.trained_model}} を介して上位パイプライン ジョブの出力にバインドされています。

別の子ジョブ (ステップ) の入力と出力にバインドする

あるステップの入力/出力を別のステップの入力/出力にバインドするには、${{parent.jobs.<step_name>.inputs.<input_name>}} または ${{parent.jobs.<step_name>.outputs.<outputs_name>}} の構文を使用します。 ここでも、この参照は親コンテキストに解決されるため、式は parent.jobs.<step_name> で始まる必要があります。

次の例では、train ステップの入力 (training_data) が、${{parent.jobs.prep.outputs.clean_data}} を介して prep ステップの出力 (clean_data) にバインドされています。 prep ステップから用意されたデータは、train ステップのトレーニング データとして使用されます。

一方、command プロパティ内のコンテキスト参照は現在のコンテキストに解決されます。 たとえば、prep ステップの command の ${{inputs.raw_data}} 参照は、prep 子ジョブである現在のコンテキストの入力に解決されます。 prep.inputs に対して検索が行われるため、raw_data という名前の入力をここで定義する必要があります。

$schema: https://azuremlschemas.azureedge.net/latest/pipelineJob.schema.json
type: pipeline
inputs:
  input_data: 
    type: uri_folder
    path: https://azuremlexamples.blob.core.windows.net/datasets/cifar10/
outputs:
  trained_model:
jobs:
  prep:
    type: command
    inputs:
      raw_data: ${{parent.inputs.input_data}}
    outputs:
      clean_data:
    code: src/prep
    environment: azureml:AzureML-Minimal@latest
    command: >-
      python prep.py 
      --raw-data ${{inputs.raw_data}} 
      --prep-data ${{outputs.clean_data}}
    compute: azureml:cpu-cluster
  train:
    type: command
    inputs: 
      training_data: ${{parent.jobs.prep.outputs.clean_data}}
      num_epochs: 1000
    outputs:
      model_dir: ${{parent.outputs.trained_model}}
    code: src/train
    environment: azureml:AzureML-Minimal@latest
    command: >-
      python train.py 
      --epochs ${{inputs.num_epochs}}
      --training-data ${{inputs.training_data}} 
      --model-output ${{outputs.model_dir}}
    compute: azureml:gpu-cluster

コンポーネントの inputs コンテキストと outputs コンテキストで command をパラメーター化する

ジョブの command と同様に、コンポーネントの command も inputs コンテキストと outputs コンテキストへの参照を使用してパラメーター化することができます。 この場合、参照はコンポーネントの入力と出力に対する参照です。 コンポーネントがジョブで実行されている場合、Azure Machine Learning は、それぞれのコンポーネントの入力と出力に指定されたジョブ ランタイムの入力値と出力値に参照を解決します。 コマンド コンポーネント YAML 仕様のコンテキスト構文の使用例を次に示します。

$schema: https://azuremlschemas.azureedge.net/latest/commandComponent.schema.json
name: train_data_component_cli
display_name: train_data
description: A example train component
tags:
  author: azureml-sdk-team
type: command
inputs:
  training_data: 
    type: uri_folder
  max_epocs:
    type: integer
    optional: true
  learning_rate: 
    type: number
    default: 0.01
    optional: true
  learning_rate_schedule: 
    type: string
    default: time-based
    optional: true
outputs:
  model_output:
    type: uri_folder
code: ./train_src
environment: azureml://registries/azureml/environments/sklearn-1.5/labels/latest
command: >-
  python train.py 
  --training_data ${{inputs.training_data}} 
  $[[--max_epocs ${{inputs.max_epocs}}]]
  $[[--learning_rate ${{inputs.learning_rate}}]]
  $[[--learning_rate_schedule ${{inputs.learning_rate_schedule}}]]
  --model_output ${{outputs.model_output}}

コマンド ラインで省略可能な入力を定義する

入力が optional = true として設定されている場合、入力を含むコマンド ラインを $[[]] を使用して囲む必要があります。 たとえば、「 $[[--input1 ${{inputs.input1}}] 」のように指定します。 実行時のコマンド ラインでは、異なる入力がある場合があります。

• 必須の training_data と model_output のパラメーターのみを使用する場合、コマンド ラインは次のようになります。

python train.py --training_data some_input_path --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path

実行時に値が指定されない場合、learning_rate および learning_rate_schedule では既定値が使用されます。

• 実行時にすべての入力/出力で値が提供される場合、コマンド ラインは次のようになります。

python train.py --training_data some_input_path --max_epocs 10 --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path

出力パス式

ジョブの出力パスでは、次の式を使用できます。

重要

次の式は、クライアント側ではなく、サーバー側で解決されます。 スケジュールされたジョブでジョブの作成時間とジョブの送信時間が異なる場合、ジョブの送信時に式が解決されます。 これらの式はサーバー側で解決されるため、スケジュールされたジョブの作成時のワークスペースの状態ではなく、ワークスペースの現在の状態を使用します。 たとえば、スケジュールされたジョブを作成した後にワークスペースの既定のデータストアを変更した場合、式 ${{default_datastore}} は、スケジュールされたジョブの作成時の既定のデータストアではなく、新しい既定のデータストアに解決されます。

Expression	説明	スコープ
${{default_datastore}}	パイプラインの既定のデータストアが構成されている場合は、パイプラインの既定のデータストア名として解決されます。それ以外の場合は、ワークスペースの既定のデータストア名として解決されます。 パイプラインの既定のデータストアは、pipeline_job.settings.default_datastore を使用して制御できます。	すべてのジョブで機能します。 パイプライン ジョブには、構成可能なパイプラインの既定のデータストアがあります。
${{name}}	ジョブ名です。 パイプラインの場合は、パイプライン ジョブ名ではなく、ステップ ジョブ名です。	すべてのジョブで機能します
${{output_name}}	ジョブ出力名	すべてのジョブで機能します

たとえば、azureml://datastores/${{default_datastore}}/paths/${{name}}/${{output_name}} が出力パスとして使用されている場合、実行時には azureml://datastores/workspaceblobstore/paths/<job-name>/model_path のパスとして解決されます。

次のステップ

• CLI (v2) をインストールして使用する
• CLI (v2) を使用してモデルをトレーニングする
• CLI (v2) YAML スキーマ