Azure Machine Learning CLI でコンポーネントを使用して機械学習パイプラインを作成して実行する
適用対象:
Azure CLI ML 拡張機能 v2 (現行)
この記事では、Azure CLI とコンポーネントを使用して、機械学習パイプラインを作成して実行する方法について説明します。 コンポーネントを使用せずにパイプラインを作成することはできますが、コンポーネントによって最大限の柔軟性と再利用が提供されます。 Azure Machine Learning パイプラインは、YAML に定義して CLI から実行したり、Python で作成したり、ドラッグアンドドロップ UI を使って Azure Machine Learning スタジオ デザイナーで作成したりできます。 このドキュメントでは、CLI に焦点を当てています。
前提条件
Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。 無料版または有料版の Azure Machine Learning をお試しください。
Azure Machine Learning ワークスペース。 ワークスペース リソースの作成.
examples リポジトリをクローンします。
git clone https://github.com/Azure/azureml-examples --depth 1 cd azureml-examples/cli/jobs/pipelines-with-components/basics
先に読んでおくことが推奨される記事
コンポーネントを使用して最初のパイプラインを作成する
例を使用して、コンポーネントを使用して最初のパイプラインを作成してみましょう。 このセクションでは、具体的な例を使用して、Azure Machine Learning でパイプラインとコンポーネントが最初にどのように見えるかを示すことを目的とします。
azureml-examples リポジトリーの cli/jobs/pipelines-with-components/basics ディレクトリーから、3b_pipeline_with_data サブディレクトリーに移動します。 このディレクトリには 3 種類のファイルがあります。 これらは、独自のパイプラインを構築するときに作成する必要があるファイルです。
pipeline.yml: この YAML ファイルは、機械学習パイプラインを定義します。 この YAML ファイルでは、1 つの機械学習タスク全体を複数のステップから成るワークフローに分割する方法を記述します。 たとえば、履歴データを使用して売上予測モデルをトレーニングする単純な機械学習タスクを考えたとき、データ処理、モデル トレーニング、モデル評価のステップを持つシーケンシャル ワークフローの構築が必要な場合もあります。 各ステップは 1 つのコンポーネントであり、適切に定義されたインターフェイスを持ち、個別に開発、テスト、最適化できます。 また、パイプライン YAML は、子ステップがパイプライン内の他のステップに接続する方法も定義します。たとえば、モデル トレーニング ステップによってモデル ファイルが生成され、そのモデル ファイルがモデル評価ステップに渡されます。
component.yml: この YAML ファイルはコンポーネントを定義します。 次の情報がパッケージされます:
- メタデータ: "名前"、"表示名"、"バージョン"、"説明"、"種類" など。メタデータは、コンポーネントの記述と管理に役立ちます。
- インターフェイス: "入力" と "出力"。 たとえば、モデル トレーニング コンポーネントは、入力としてトレーニング データとエポックの数を受け取り、出力としてトレーニング済みのモデル ファイルを生成します。 インターフェイスが定義されると、さまざまなチームがコンポーネントを個別に開発およびテストできます。
- コマンド、コード、環境: コンポーネントを実行するための "コマンド"、"コード"、"環境"。 コマンドは、コンポーネントを実行するためのシェル コマンドです。 コードは通常、ソース コード ディレクトリを参照します。 環境は、Azure Machine Learning 環境 (キュレーションされた環境または顧客によって作成された環境)、Docker イメージ、または conda 環境にすることができます。
component_src: これは、特定のコンポーネントのソース コード ディレクトリです。 これには、コンポーネントで実行されるソース コードが含まれます。 任意の言語 (Python、R...) を使用できます。コードはシェル コマンドで実行する必要があります。 ソース コードでは、シェル コマンド ラインからいくつかの入力を受け取って、このステップの実行方法を制御できます。 たとえば、トレーニング ステップでは、トレーニング プロセスを制御するためにトレーニング データ、学習率、エポックの数を取得できます。 シェル コマンドの引数は、入力と出力をコードに渡すのに使用されます。
次に、3b_pipeline_with_data 例を使用してパイプラインを作成しましょう。 各ファイルの詳細な意味については、以降のセクションで説明します。
最初に、次のコマンドを使用して、使用可能なコンピューティング リソースを一覧表示します。
az ml compute list
ない場合は、次を実行して cpu-cluster という名前のクラスターを作成します。
Note
サーバーレス コンピューティングを使う場合は、このステップをスキップしてください。
az ml compute create -n cpu-cluster --type amlcompute --min-instances 0 --max-instances 10
次に、以下のコマンドを使用して、pipeline.yml ファイルで定義されたパイプライン ジョブを作成します。 コンピューティング先は、pipeline.yml ファイルで azureml:cpu-cluster として参照されます。 コンピューティング先で別の名前が使用される場合は、必ず pipeline.yml ファイルで更新してください。
az ml job create --file pipeline.yml
次のようなパイプライン ジョブに関する情報を含む JSON ディクショナリを受け取ります:
| キー | 説明 |
|---|---|
name |
ジョブの GUID ベースの名前。 |
experiment_name |
Studio でジョブが整理されるときに使用される名前。 |
services.Studio.endpoint |
パイプライン ジョブを監視および確認するための URL。 |
status |
ジョブの状態。 この時点では、これは Preparing になる可能性が高くなります。 |
services.Studio.endpoint URL を開いて、パイプラインのグラフの視覚化を表示します。
パイプライン定義 YAML について
3b_pipeline_with_data/pipeline.yml ファイルのパイプライン定義を見てみましょう。
Note
サーバーレス コンピューティングを使う場合は、このファイルで default_compute: azureml:cpu-cluster を default_compute: azureml:serverless に置き換えてください。
$schema: https://azuremlschemas.azureedge.net/latest/pipelineJob.schema.json
type: pipeline
display_name: 3b_pipeline_with_data
description: Pipeline with 3 component jobs with data dependencies
settings:
default_compute: azureml:cpu-cluster
outputs:
final_pipeline_output:
mode: rw_mount
jobs:
component_a:
type: command
component: ./componentA.yml
inputs:
component_a_input:
type: uri_folder
path: ./data
outputs:
component_a_output:
mode: rw_mount
component_b:
type: command
component: ./componentB.yml
inputs:
component_b_input: ${{parent.jobs.component_a.outputs.component_a_output}}
outputs:
component_b_output:
mode: rw_mount
component_c:
type: command
component: ./componentC.yml
inputs:
component_c_input: ${{parent.jobs.component_b.outputs.component_b_output}}
outputs:
component_c_output: ${{parent.outputs.final_pipeline_output}}
# mode: upload
この表では、パイプライン YAML スキーマの最も一般的に使用されるフィールドについて説明します。 詳細については、「完全なパイプライン YAML スキーマ」を参照してください。
| キー | description |
|---|---|
| type | 必須。 ジョブの種類は、パイプライン ジョブの場合は pipeline である必要があります。 |
| display_name | Studio UI でのパイプライン ジョブの表示名。 Studio UI で編集できます。 ワークスペース内のすべてのジョブで一意である必要はありません。 |
| jobs | [必須] 。 パイプライン内のステップとして実行する個々のジョブのセットの辞書。 これらのジョブは、親パイプライン ジョブの子ジョブと見なされます。 このリリースでは、パイプラインでサポートされているジョブの種類は command および sweep です。 |
| inputs | パイプライン ジョブへの入力の辞書。 キーは、ジョブのコンテキスト内の入力の名前であり、値は入力値です。 これらのパイプライン入力は、${{ parent.inputs.<input_name> }} 式を使用して、パイプライン内の個々のステップ ジョブの入力によって参照できます。 |
| outputs | パイプライン ジョブの出力構成の辞書。 キーはジョブのコンテキスト内の出力の名前であり、値は出力構成です。 これらのパイプライン出力は、${{ parents.outputs.<output_name> }} 式を使用して、パイプライン内の個々のステップ ジョブの出力によって参照できます。 |
3b_pipeline_with_data の例では、3 つのステップから成るパイプラインを作成しました。
- これらの 3 つのステップは
jobsで定義されています。 3 つのステップの種類はすべてコマンド ジョブです。 各ステップの定義は、対応するcomponent.ymlファイル内にあります。 コンポーネント YAML ファイルは、3b_pipeline_with_data ディレクトリで確認できます。 次のセクションで componentA.yml について説明します。 - このパイプラインには、データ依存関係があります。これは、ほとんどの実際のパイプラインで一般的です。 Component_a は、ローカル フォルダーの
./data(17 行目から 20 行目) からデータ入力を受け取り、その出力を componentB (29 行目) に渡します。 Component_a の出力は${{parent.jobs.component_a.outputs.component_a_output}}として参照できます。 computeは、このパイプラインの既定のコンピューティングを定義します。jobsの下のコンポーネントで、このコンポーネントに別のコンピューティングが定義されている場合、システムではコンポーネント固有の設定が優先されます。
パイプライン内のデータの読み取りと書き込み
一般的なシナリオの 1 つは、パイプライン内のデータの読み取りと書き込みです。 Azure Machine Learning では、すべての型のジョブ (パイプライン ジョブ、コマンド ジョブ、およびスイープ ジョブ) に対して同じスキーマを使用してデータの読み取りと書き込みを行います。 一般的なシナリオでデータを使用するパイプライン ジョブの例を次に示します。
コンポーネント定義 YAML について
次に、コンポーネント定義 YAML を理解するために例として componentA.yml を見てみましょう。
$schema: https://azuremlschemas.azureedge.net/latest/commandComponent.schema.json
type: command
name: component_a
display_name: componentA
version: 1
inputs:
component_a_input:
type: uri_folder
outputs:
component_a_output:
type: uri_folder
code: ./componentA_src
environment:
image: python
command: >-
python hello.py --componentA_input ${{inputs.component_a_input}} --componentA_output ${{outputs.component_a_output}}
コンポーネント YAML で使用される最も一般的なスキーマについて表で説明します。 詳細については、「完全なコンポーネント YAML スキーマ」を参照してください。
| キー | description |
|---|---|
| name | [必須] 。 コンポーネント名。 Azure Machine Learning ワークスペース全体で一意である必要があります。 先頭には小文字を使用する必要があります。 小文字、数字、アンダースコア (_) を使用できます。 最大文字数は 255 文字です。 |
| display_name | Studio UI でのコンポーネントの表示名。 ワークスペース内で一意ではない場合があります。 |
| command | 必須。実行するコマンド |
| code | アップロードしてコンポーネントに使用するソース コード ディレクトリへのローカル パス。 |
| 環境 | 必須。 コンポーネントの実行に使用される環境。 |
| inputs | コンポーネント入力の辞書。 キーはコンポーネントのコンテキスト内の入力の名前であり、値はコンポーネントの入力定義です。 入力は、${{ inputs.<input_name> }} 式を使用してコマンドで参照できます。 |
| outputs | コンポーネント出力の辞書。 キーはコンポーネントのコンテキスト内の出力の名前であり、値はコンポーネントの出力定義です。 出力は、${{ outputs.<output_name> }} 式を使用してコマンドで参照できます。 |
| is_deterministic | コンポーネントの入力が変更されなかった場合に、前のジョブの結果を再利用するかどうか。 既定値は true です。既定では 再利用 とも呼ばれます。 false として設定する一般的なシナリオは、クラウド ストレージまたは URL からデータを強制的にリロードすることです。 |
3b_pipeline_with_data/componentA.yml の例では、componentA には 1 つのデータ入力と 1 つのデータ出力があり、親パイプラインの他のステップに接続できます。 コンポーネント YAML の code セクションにあるすべてのファイルは、パイプライン ジョブの送信時に Azure Machine Learning にアップロードされます。 この例では、./componentA_src の下にあるファイルがアップロードされます (componentA.yml の 16 行目)。 アップロードされたソース コードは、Studio UI で確認できます。次のスクリーンショットに示すように、ComponentA ステップをダブルクリックし、[スナップショット] タブに移動します。 単純な印刷を行うだけの hello-world スクリプトであることがわかり、現在の日時を componentA_output パスに書き込むことができます。 コンポーネントはコマンド ライン引数を使用して入力と出力を受け取り、argparse を使用して hello.py で処理されます。
入力と出力
入力と出力は、コンポーネントのインターフェイスを定義します。 入力と出力は、リテラル値 (型 string、number、integer、または boolean)、もしくは入力スキーマを含むオブジェクトのいずれかにすることができます。
オブジェクトの入力 (型 uri_file、uri_folder、mltable、mlflow_model、custom_model) は、親パイプライン ジョブ内の他のステップに接続できるため、データ/モデルを他のステップに渡すことができます。 パイプラインのグラフでは、オブジェクトの種類の入力は接続ドットとしてレンダリングされます。
リテラル値の入力 (string、number、integer、boolean) は、実行時にコンポーネントに渡すことができるパラメーターです。 default フィールドの下にリテラル入力の既定値を追加できます。 number と integer 型の場合、min と max フィールドを使用して、許容される値の最小値と最大値を追加することもできます。 入力値が最小値と最大値を超えると、パイプラインは検証時に失敗します。 検証は、時間を節約するためにパイプライン ジョブの送信前に行われます。 検証は、CLI、Python SDK、デザイナー UI で機能します。 次のスクリーンショットは、デザイナー UI の検証例を示しています。 同様に、enum フィールドで使用できる値を定義できます。
コンポーネントに入力を追加する場合は、必ず次の 3 つの場所を編集してください:
- コンポーネント YAML の
inputsフィールド - コンポーネント YAML の
commandフィールド。 - コマンドライン入力を処理するコンポーネントのソース コード。 前のスクリーンショットでは、緑色のボックスにマークされています。
入力と出力の詳細については、「コンポーネントとパイプラインの入力と出力を管理する」を参照してください。
Environment
環境は、コンポーネントを実行する環境を定義します。 Azure Machine Learning 環境 (キュレーションされた環境またはカスタム登録された環境)、Docker イメージ、または conda 環境にすることができます。 次の例を参照してください。
- Azure Machine Learning 登録済み環境資産。 これは、
azureml:<environment-name>:<environment-version>構文に従うコンポーネントで参照されます。 - パブリック Docker イメージ
- conda ファイル Conda ファイルは、基本イメージと一緒に使用する必要があります。
再利用と共有のためにコンポーネントを登録する
特定のパイプラインに固有のコンポーネントもありますが、コンポーネントの本当の利点は再利用と共有ができることです。 コンポーネントを再利用できるようにするには、Machine Learning ワークスペースにそれを登録します。 登録されたコンポーネントは自動バージョン管理に対応しているので、コンポーネントを更新できますが、古いバージョンを必要とするパイプラインは引き続き動作します。
azureml-examples リポジトリで、cli/jobs/pipelines-with-components/basics/1b_e2e_registered_components ディレクトリに移動します。
コンポーネントを登録するには、az ml component create コマンドを使用します。
az ml component create --file train.yml
az ml component create --file score.yml
az ml component create --file eval.yml
これらのコマンドの実行が完了すると、コンポーネントが Studio の [Asset -> Components] (資産 -> コンポーネント) の下に表示されます。
コンポーネントを選択します。 コンポーネントのバージョンごとに詳細情報が表示されます。
[詳細] タブには、名前、作成者、バージョンなど、コンポーネントの基本情報が表示されます。編集可能な [タグ] および [説明] フィールドが表示されます。 タグは、迅速に検索されるキーワードを追加するために使用できます。 説明フィールドは Markdown の書式設定をサポートしており、コンポーネントの機能と基本的な使用方法を説明するために使用する必要があります。
[ジョブ] タブには、このコンポーネントを使用するすべてのジョブの履歴が表示されます。
パイプライン ジョブ YAML ファイルの登録済みコンポーネントを使用する
1b_e2e_registered_components を使用して、パイプライン YAML の登録済みコンポーネントを使用する方法を示します。 1b_e2e_registered_components ディレクトリに移動し、pipeline.yml ファイルを開きます。 inputs および outputs フィールドのキーと値は、既に説明したものに似ています。 唯一の重要な違いは、jobs.<JOB_NAME>.component エントリの component フィールドの値です。 component の値は、azureml:<COMPONENT_NAME>:<COMPONENT_VERSION> という形式になっています。 たとえば、train-job の定義は、登録されたコンポーネント my_train の最新バージョンを使用する必要があることを指定します。
type: command
component: azureml:my_train@latest
inputs:
training_data:
type: uri_folder
path: ./data
max_epocs: ${{parent.inputs.pipeline_job_training_max_epocs}}
learning_rate: ${{parent.inputs.pipeline_job_training_learning_rate}}
learning_rate_schedule: ${{parent.inputs.pipeline_job_learning_rate_schedule}}
outputs:
model_output: ${{parent.outputs.pipeline_job_trained_model}}
services:
my_vscode:
コンポーネントを管理する
CLI (v2) を使用して、コンポーネントの詳細を確認し、コンポーネントを管理できます。 コンポーネント コマンドの詳細な説明を取得するには、az ml component -h を使用します。 次の表は、すべての使用可能なコマンドの一覧です。 「Azure CLI リファレンス」でその他の例を参照してください。
| commands | description |
|---|---|
az ml component create |
コンポーネントを作成する |
az ml component list |
ワークスペース内のコンポーネントを一覧表示する |
az ml component show |
コンポーネントの詳細を表示する |
az ml component update |
コンポーネントを更新します。 いくつかのフィールド (description、display_name) のみが更新をサポートします |
az ml component archive |
コンポーネント コンテナーをアーカイブする |
az ml component restore |
アーカイブされたコンポーネントを復元する |