CLI (v2) 並列ジョブの YAML スキーマ

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

重要

並列ジョブは、Azure Machine Learning パイプライン ジョブ内の単一ステップとしてのみ使用できます。 したがって、現時点では、並列ジョブのソース JSON スキーマはありません。 このドキュメントでは、パイプラインで並列ジョブを作成するときの有効なキーとその値の一覧を示します。

Note

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

YAML 構文

キー	Type	説明	使用できる値	既定値
type	const	必須です。 ジョブの種類。	parallel
inputs	object	並列ジョブへの入力の辞書。 キーは、ジョブのコンテキスト内の入力の名前であり、値は入力値です。 入力は、${{ inputs.<input_name> }} 式を使用して program_arguments で参照できます。 並列ジョブの入力は、${{ parent.inputs.<input_name> }} 式を使用したパイプライン入力によって参照できます。 並列ステップの入力をパイプラインの入力にバインドする方法については、パイプライン ジョブのステップ間で入力と出力をバインドするための式構文を参照してください。
inputs.<input_name>	数値、整数、ブール値、文字列、またはオブジェクト	リテラル値 (型番号、整数、ブール値、または文字列) のいずれか、またはジョブ入力データ仕様を含むオブジェクト。
outputs	object	並列ジョブの出力構成の辞書。 キーはジョブのコンテキスト内の出力の名前であり、値は出力構成です。 並列ジョブの出力は、${{ parents.outputs.<output_name> }} 式を使用したパイプラインの出力によって参照できます。 並列ステップの出力をパイプラインの出力にバインドする方法については、パイプライン ジョブのステップ間で入力と出力をバインドするための式構文を参照してください。
outputs.<output_name>	object	オブジェクトは空のままにしておくことができます。この場合、既定では出力の種類は uri_folder になり、Azure Machine Learning は次のテンプレート化されたパスに基づいて出力の出力場所をシステム生成します: {settings.datastore}/azureml/{job-name}/{output-name}/。 出力ディレクトリへのファイルは、読み取り/書き込みマウントを使用して書き込まれます。 出力に別のモードを指定する場合は、ジョブ出力仕様を含むオブジェクトを指定します。
compute	string	ジョブを実行するコンピューティング先の名前。 この値は、ワークスペース内の既存のコンピューティングへの参照 (azureml:<compute_name> 構文を使用) または local でローカル実行を指定する場合があります。 パイプラインで並列ジョブを使用する場合、この設定は空にすることができます。その場合、コンピューティングはパイプラインの default_compute によって自動選択されます。		local
task	object	必須。 並列ジョブの分散タスクを定義するためのテンプレート。 「task キーの属性」を参照してください。
input_data	object	必須。 並列ジョブを実行するためにミニバッチに分割する入力データを定義します。 ${{ inputs.<input_name> }} 式を使用して並列ジョブ inputs の 1 つを参照する場合にのみ適用されます
mini_batch_size	string	入力を分割する各ミニバッチのサイズを定義します。 input_data がフォルダーまたは一連のファイルの場合、この数値は各ミニバッチの ファイル数 を定義します。 たとえば、10、100 です。 input_data が mltable からの表形式データの場合、この数値は各ミニバッチの最も近い物理サイズを定義します。 たとえば、100 kb、100 mb などです。		1
partition_keys	list	データセットをミニバッチにパーティション分割するために使用されるキー。 指定した場合、同じキーを持つデータが同じミニバッチにパーティション分割されます。 両方 partition_keys が mini_batch_size 指定されている場合、パーティション キーが有効になります。
mini_batch_error_threshold	integer	この並列ジョブで無視できる失敗したミニバッチの数を定義します。 失敗したミニバッチの数がこのしきい値を超えた場合、並列ジョブは失敗としてマークされます。 ミニバッチは、次の場合に失敗としてマークされます。 - run() からの戻り値の数がミニバッチの入力数未満です。 - カスタム run() コードで例外をキャッチしました。 既定値は "-1" で、並列ジョブの間に失敗したすべてのミニバッチを無視することを意味します。	[-1, int.max]	-1
logging_level	string	ユーザー ログ ファイルにダンプされるログのレベルを定義します。	INFO、WARNING、DEBUG	INFO
resources.instance_count	整数 (integer)	ジョブに使用するノードの数。		1
max_concurrency_per_instance	整数 (integer)	コンピューティングの各ノードのプロセス数を定義します。 GPU コンピューティングの場合、既定値は 1 です。 CPU コンピューティングの場合、既定値はコアの数です。
retry_settings.max_retries	整数 (integer)	ミニバッチが失敗またはタイムアウトしたときの再試行回数を定義します。 すべての再試行が失敗した場合、そのミニバッチは失敗とマークされて mini_batch_error_threshold の計算でカウントされます。		2
retry_settings.timeout	整数 (integer)	カスタム run() 関数の実行でのタイムアウトを秒単位で定義します。 実行時間がこのしきい値を超えた場合、そのミニバッチは中止され、失敗とマークされて再試行がトリガーされます。	(0, 259200]	60
environment_variables	object	コマンドが実行されるプロセスに設定する環境変数のキーと値のペアの辞書。

task キーの属性

キー	Type	説明	使用できる値	既定値
type	const	必須。 タスクの種類。 現時点では、run_function にのみ適用されます。 run_function モードでは、code、entry_script、program_arguments を指定し、実行可能な関数と引数を使用して Python スクリプトを定義する必要があります。 注: このモードでは、並列ジョブは Python スクリプトのみをサポートします。	run_function	run_function
code	string	アップロードしてジョブに使用するソース コード ディレクトリへのローカル パス。
entry_script	string	定義済みの並列関数の実装を含む Python ファイル。 詳細については、「並列ジョブへの入力スクリプトの準備」を参照してください。
environment	文字列またはオブジェクト	必須。タスクの実行に使用する環境。 この値は、ワークスペース内の既存のバージョン管理された環境への参照、またはインライン環境仕様のいずれかになります。 既存の環境を参照するには、azureml:<environment_name>:<environment_version> 構文または azureml:<environment_name>@latest (環境の最新バージョンを参照する場合) を使用します。 インライン環境を定義するには、環境スキーマに従います。 name プロパティと version プロパティは、インライン環境ではサポートされていないため、除外します。
program_arguments	string	エントリ スクリプトに渡される引数。 入力または出力に対し、"--<arg_name> ${{inputs.<intput_name>}}" 参照を含む場合があります。 並列ジョブには、並列実行の構成を設定するための定義済みの引数の一覧が用意されています。 詳細については、並列ジョブの定義済み引数を参照してください。
append_row_to	string	ミニバッチの各実行から戻されたすべての値を集約して、このファイルに出力します。 ${{outputs.<output_name>}} というを使って、並列ジョブの出力の 1 つを参照できます

ジョブの入力

キー	Type	説明	使用できる値	既定値
type	string	ジョブ入力の種類。 mltable メタ ファイルがある場所を指す入力データの場合は mltable、フォルダー ソースを指す入力データの場合は uri_folder を指定します。	mltable, uri_folder	uri_folder
path	string	入力として使用するデータのパス。 この値は、いくつかの方法で指定できます。 - データ ソース ファイルまたはフォルダーへのローカル パス (例: path: ./iris.csv)。 データはジョブの送信中にアップロードされます。 - 入力として使用するファイルまたはフォルダーへのクラウド パスの URI。 サポートされる URI の種類は azureml、https、wasbs、abfss、adl です。 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、 downloaddirect	ro_mount

ジョブ出力

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

並列ジョブの定義済み引数

Key	説明	使用できる値	既定値
--error_threshold	失敗した項目数のしきい値。 失敗した項目の数は、入力数と各ミニバッチから返された数の間のギャップによってカウントされます。 失敗した項目の合計がこのしきい値を超えた場合、並列ジョブは失敗としてマークされます。 注: 既定値は "-1" で、並列ジョブの間の失敗をすべて無視することを意味します。	[-1, int.max]	-1
--allowed_failed_percent	mini_batch_error_threshold に似ていますが、カウントではなく失敗したミニバッチの割合を使います。	[0, 100]	100
--task_overhead_timeout	各ミニバッチの初期化のタイムアウト (秒)。 たとえば、ミニバッチのデータを読み込んで run() 関数に渡します。	(0, 259200]	30
--progress_update_timeout	ミニバッチの実行の進行状況を監視するためのタイムアウト (秒)。 このタイムアウト設定内に進行状況の更新を受け取らない場合、並列ジョブは失敗としてマークされます。	(0, 259200]	他の設定によって動的に計算されます。
--first_task_creation_timeout	ジョブの開始から最初のミニバッチの実行までの時間を監視するためのタイムアウト (秒)。	(0, 259200]	600
--copy_logs_to_parent	ジョブの進行状況、概要、ログを親パイプライン ジョブにコピーするかどうかを示すブール値オプション。	True、False	×
--metrics_name_prefix	この並列ジョブでメトリックのカスタム プレフィックスを指定します。
--push_metrics_to_parent	メトリックを親パイプライン ジョブにプッシュするかどうかを示すブール値オプション。	True、False	×
--resource_monitor_interval	ノード リソースの使用状況 (CPU、メモリなど) を "logs/sys/perf" パスの下のログ フォルダーにダンプする時間間隔 (秒)。 注: リソース ログを頻繁にダンプすると、ミニバッチの実行速度が若干遅くなります。 リソース使用状況のダンプを停止するには、この値を "0" に設定します。	[0, int.max]	600

解説

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

例

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

YAML: パイプラインでの並列ジョブの使用

$schema: https://azuremlschemas.azureedge.net/latest/pipelineJob.schema.json
type: pipeline

display_name: iris-batch-prediction-using-parallel
description: The hello world pipeline job with inline parallel job
tags:
  tag: tagvalue
  owner: sdkteam

settings:
  default_compute: azureml:cpu-cluster

jobs:
  batch_prediction:
    type: parallel
    compute: azureml:cpu-cluster
    inputs:
      input_data: 
        type: mltable
        path: ./neural-iris-mltable
        mode: direct
      score_model: 
        type: uri_folder
        path: ./iris-model
        mode: download
    outputs:
      job_output_file:
        type: uri_file
        mode: rw_mount

    input_data: ${{inputs.input_data}}
    mini_batch_size: "10kb"
    resources:
        instance_count: 2
    max_concurrency_per_instance: 2

    logging_level: "DEBUG"
    mini_batch_error_threshold: 5
    retry_settings:
      max_retries: 2
      timeout: 60

    task:
      type: run_function
      code: "./script"
      entry_script: iris_prediction.py
      environment:
        name: "prs-env"
        version: 1
        image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04
        conda_file: ./environment/environment_parallel.yml
      program_arguments: >-
        --model ${{inputs.score_model}}
        --error_threshold 5
        --allowed_failed_percent 30
        --task_overhead_timeout 1200
        --progress_update_timeout 600
        --first_task_creation_timeout 600
        --copy_logs_to_parent True
        --resource_monitor_interva 20
      append_row_to: ${{outputs.job_output_file}}

次のステップ

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