Azure Machine Learning で登録済みモデルを操作する

[アーティクル]
06/18/2024

適用対象:Azure CLI ml extension v2 (現行)Python SDK azure-ai-ml v2 (現行)

この記事では、次を使用して Azure Machine Learning のモデルを登録して操作する方法について説明します。

Azure Machine Learning スタジオ UI。
Azure Machine Learning V2 CLI。
Python Azure Machine Learning V2 SDK。

学習内容は次のとおりです。

ローカルファイル、データストア、またはジョブ出力からモデルレジストリに登録済みモデルを作成します。
カスタム、MLflow、Triton など、さまざまな種類のモデルを操作します。
トレーニングジョブの入力または出力としてモデルを使用します。
モデル資産のライフサイクルを管理します。

モデルの登録

モデルの登録によって、モデルを Azure クラウドのワークスペースに保存してバージョンを管理できます。モデルのレジストリは、トレーニングしたモデルの整理と追跡に役立ちます。 Azure CLI、Python SDK、または Machine Learning スタジオ UI を使用して、Azure Machine Learning でモデルを資産として登録できます。

サポートされているパス

モデルを登録するには、データまたはジョブの場所を指すパスを指定する必要があります。次の表は、Azure Machine Learning でサポートするさまざまなデータの場所と、path パラメーターの構文を示しています。

場所	構文
ローカルコンピューター	`<model-folder>/<model-filename>`
Azure Machine Learning データストア	`azureml://datastores/<datastore-name>/paths/<path_on_datastore>`
Azure Machine Learning ジョブ	`azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>`
MLflow ジョブ	`runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>`
Machine Learning ワークスペース内のモデル資産	`azureml:<model-name>:<version>`
Machine Learning レジストリ内のモデル資産	`azureml://registries/<registry-name>/models/<model-name>/versions/<version>`

サポートされているモード

入力または出力にモデルを使用する場合は、次のいずれかの "モード" を指定できます。たとえば、モデルを読み取り専用にマウントするか、コンピューティングターゲットにダウンロードするかを指定できます。

ro_mount: データを読み取り専用としてコンピューティング先にマウントします。
rw_mount: データを読み取り/書き込みマウントします。
download: コンピューティング先にデータをダウンロードします。
upload: コンピューティング先からデータをアップロードします。
direct: URI を文字列として渡します。

次の表に、さまざまなモデルの種類の入力と出力に使用できるモードオプションを示します。

Type	`upload`	`download`	`ro_mount`	`rw_mount`	`direct`
`custom` ファイル入力
`custom` フォルダー入力		✓	✓		✓
`mlflow` 入力		✓	✓
`custom` ファイル出力	✓			✓	✓
`custom` フォルダーの出力	✓			✓	✓
`mlflow` 出力	✓			✓	✓

前提条件

無料版または有料版の Azure Machine Learning を使用する Azure サブスクリプション。 Azure サブスクリプションをお持ちでない場合は、始める前に無料アカウントを作成してください。
Azure Machine Learning ワークスペース。

この記事のコードサンプルを実行し、Azure Machine Learning V2 CLI または Python Azure Machine Learning V2 SDK を使用するには、次も必要です。

Azure CLI
Python SDK

Azure CLI バージョン 2.38.0 以降がインストールされていること。
次のコマンドを実行してインストールされた ml 拡張機能の V2。詳しくは、CLI (v2) のインストール、設定、使用に関するページをご覧ください。
```
az extension add -n ml
```

Python 3.8 以降がインストールされていること。
次のコマンドを実行してインストールされた Azure Machine Learning SDK v2 for Python:
```
pip install azure-ai-ml azure-identity
```

Note

V2 には完全な下位互換性が用意されています。 v1 SDK または CLI からのモデル資産を引き続き使用できます。 v1 CLI または SDK に登録されているすべてのモデルに型 custom が割り当てられます。

スタジオ UI を使用してモデルを登録する

Azure Machine Learning スタジオ UI を使用してモデルを登録するには:

スタジオのワークスペースで、左側のナビゲーションから [モデル] を選択します。
[モデル一覧] ページで [登録] を選択し、ドロップダウンリストから次のいずれかの場所を選択します。
- ローカルファイルから
- ジョブ出力から
- データストアから
- ローカルファイルから (フレームワークに基づく)
最初の [モデルを登録] 画面で:
1. モデルのローカルファイル、データストア、またはジョブ出力に移動します。
2. 入力モデルの種類として、[MLflow]、[Triton]、または [Unspecified 型] を選択します。
[モデル設定] 画面で、登録済みモデルの名前やその他のオプション設定を指定し、[次へ] を選択します。
[確認] 画面で、構成を確認し、[登録] を選択します。

Azure CLI または Python SDK を使用してモデルを登録する

次のコードスニペットでは、Azure CLI または Python SDK を使用して Azure Machine Learning でモデルを資産として登録する方法について説明します。これらのスニペットでは、custom および mlflow のモデル型が使用されます。

custom 型では、Azure Machine Learning で現在サポートされていないカスタム標準でトレーニングされたモデルのファイルまたはフォルダーを参照します。
mlflow 型では、MLflow でトレーニングされたモデルを参照します。 MLflow トレーニング済みモデルは、MLmodel ファイル、model ファイル、conda dependencies ファイル、requirements.txt ファイルを含むフォルダー内にあります。

ヒント

azureml-examples リポジトリで model.ipynb ノートブックを実行すると、次のサンプルの Python バージョンで進めることができます。

ワークスペースに接続する

ワークスペースは、Azure Machine Learning の最上位のリソースで、Azure Machine Learning を使用するときに作成するすべての成果物を操作するための一元的な場所を提供します。このセクションでは、Azure Machine Learning ワークスペースに接続して、登録済みモデルを作成します。

Azure CLI
Python SDK

az login を実行してプロンプトに従って、Azure にサインインします。

次のコマンドで、<subscription-id>、<workspace-name>、<resource-group>、<location> をお使いの環境の値に置き換えます。

az account set --subscription <subscription-id>
az configure --defaults workspace=<workspace-name> group=<resource-group> location=<location>

必要なライブラリをインポートします。

from azure.ai.ml import MLClient, Input
from azure.ai.ml.entities import Model
from azure.ai.ml.constants import AssetTypes
from azure.identity import DefaultAzureCredential

ワークスペースの詳細を構成し、ワークスペースへのハンドルを取得します。次のコードスニペットで、<subscription-id>、<resource-group>、<workspace-name> のプレースホルダーをお使いの環境の値に置き換えます。
```
subscription_id = "<subscription-id>"
resource_group = "<resource-group>"
workspace = "<workspace-name>"

ml_client = MLClient(DefaultAzureCredential(), subscription_id, resource_group, workspace)
```

登録済みモデルを作成する

登録済みモデルは、次のモデルから作成できます。

ローカルコンピューター上にある。
Azure Machine Learning データストアにある。
Azure Machine Learning ジョブからの出力。

YAML ファイル <file-name>.yml を作成します。ファイルで、登録済みモデルの名前、ローカルモデルファイルへのパス、説明を指定します。次に例を示します。
```
$schema: https://azuremlschemas.azureedge.net/latest/model.schema.json
name: local-file-example
path: mlflow-model/model.pkl
description: Model created from local file.
```
YAML ファイルの名前を使用して、次のコマンドを実行します。
```
az ml model create -f <file-name>.yml
```

完全な例については、モデル YAML を参照してください。

次の例は、ローカルファイルからの登録済みモデルの作成を示しています。

from azure.ai.ml.entities import Model
from azure.ai.ml.constants import AssetTypes

file_model = Model(
    path="mlflow-model/model.pkl",
    type=AssetTypes.CUSTOM_MODEL,
    name="local-file-example",
    description="Model created from local file.",
)
ml_client.models.create_or_update(file_model)

データストア

サポートされている URI 形式のいずれかを使用して、クラウドパスからモデルを作成できます。

Azure CLI
Python SDK

次の例では、構文 azureml://datastores/<datastore-name>/paths/<path_on_datastore> を使用して、データストア上のパスを指す短縮形の azureml スキームを使用します。

az ml model create --name my-model --version 1 --path azureml://datastores/myblobstore/paths/models/cifar10/cifar.pt

完全な例については、CLI リファレンスを参照してください。

次の例では、構文 azureml://datastores/${{datastore-name}}/paths/${{path_on_datastore}} を使用して、データストア上のパスを指す短縮形の azureml スキームを使用します。

from azure.ai.ml.entities import Model
from azure.ai.ml.constants import AssetTypes

cloud_model = Model(
    path=file_model.path,
    # The above line basically provides a path in the format "azureml://subscriptions/XXXXXXXXXXXXXXXX/resourceGroups/XXXXXXXXXXX/workspaces/XXXXXXXXXXX/datastores/workspaceblobstore/paths/model.pkl"
    # Users could also use,"azureml://datastores/workspaceblobstore/paths/model.pkl" as a shorthand to the same location
    name="cloud-path-example",
    type=AssetTypes.CUSTOM_MODEL,
    description="Model created from cloud path.",
)
ml_client.models.create_or_update(cloud_model)

ジョブの出力

モデルデータがジョブ出力から取得される場合は、モデルパスを指定するための 2 つのオプションがあります。 MLflow runs: URI 形式または azureml://jobs URI 形式を使用できます。

Note

artifacts 予約キーワードは、既定の成果物の場所からの出力を表します。

MLflow の実行: URI 形式

このオプションは、MLflow runs: URI 形式に既に慣れている可能性が高い MLflow ユーザー向けに最適化されています。このオプションでは、既定の成果物の場所 (MLflow でログに記録されたすべてのモデルと成果物が配置されている場所) で成果物からモデルを作成します。このオプションにより、登録されたモデルとモデルの元となる実行の間に系列が確立されます。

形式: runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>

例:
- Azure CLI
- Python SDK
```
az ml model create --name my-registered-model --version 1 --path runs:/my_run_0000000000/model/ --type mlflow_model
```
```
from azure.ai.ml.entities import Model
from azure.ai.ml.constants import ModelType

run_model = Model(
    path="runs:/my_run_0000000000/model/"
    name="my-registered-model",
    description="Model created from run.",
    type=ModelType.MLFLOW_MODEL
)

ml_client.models.create_or_update(run_model) 
```

azureml://jobs URI 形式

azureml://jobs 参照 URI オプションを使用すると、ジョブの出力パスのいずれかで成果物からモデルを登録できます。この形式は、azureml://datastores 参照 URI 形式と一致し、既定の成果物の場所以外の名前付き出力からの成果物の参照もサポートします。

MLflow を使用したトレーニングスクリプト内でモデルを直接登録しなかった場合、このオプションを使用して、登録されたモデルと、そのトレーニング元のジョブとの間に系列を確立できます。

形式: azureml://jobs/<run-id>/outputs/<output-name>/paths/<path-to-model>
- 既定の成果物の場所: azureml://jobs/<run-id>/outputs/artifacts/paths/<path-to-model>/。この場所は MLflow runs:/<run-id>/<model> と同じです。
- 名前付き出力フォルダー: azureml://jobs/<run-id>/outputs/<named-output-folder>
- 名前付き出力フォルダー内の特定のファイル: azureml://jobs/<run-id>/outputs/<named-output-folder>/paths/<model-filename>
- 名前付き出力フォルダー内の特定のフォルダーパス: azureml://jobs/<run-id>/outputs/<named-output-folder>/paths/<model-folder-name>
例:
- Azure CLI
- Python SDK
名前付き出力フォルダーからのモデルの保存:
```
az ml model create --name run-model-example --version 1 --path azureml://jobs/my_run_0000000000/outputs/artifacts/paths/model/
```
完全な例については、CLI リファレンスを参照してください。
名前付き出力からのモデルの保存:
```
from azure.ai.ml.entities import Model
from azure.ai.ml.constants import AssetTypes

job_name = "<JOB_NAME>"

run_model = Model(
    path=f"azureml://jobs/{job_name}/outputs/artifacts/paths/model/",
    name="run-model-example",
    description="Model created from run.",
    type=AssetTypes.MLFLOW_MODEL,
)
# Uncomment after adding required details above
# ml_client.models.create_or_update(run_model)
```
完全な例については、モデルノートブックを参照してください。

トレーニングにモデルを使用する

v2 Azure CLI と Python SDK では、トレーニングジョブの入力または出力としてモデルを使用することもできます。

トレーニングジョブでモデルを入力として使用する

Azure CLI
Python SDK

ジョブ仕様の YAML ファイル <file-name>.yml を作成します。ジョブの inputs セクションで次のように指定します。

モデル type。mlflow_model、custom_model、または triton_model を指定できます。
モデルが配置されている path。次の例のコメントに記載されているパスのいずれかを指定できます。

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json

# Possible Paths for models:
# AzureML Datastore: azureml://datastores/<datastore-name>/paths/<path_on_datastore>
# MLflow run: runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>
# Job: azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>
# Model Asset: azureml:<my_model>:<version>

command: |
  ls ${{inputs.my_model}}
inputs:
  my_model:
    type: mlflow_model # List of all model types here: https://learn.microsoft.com/azure/machine-learning/reference-yaml-model#yaml-syntax
    path: ../../assets/model/mlflow-model
environment: azureml://registries/azureml/environments/sklearn-1.5/labels/latest

お使いの YAML ファイル名に置き換えて、次のコマンドを実行します。
```
az ml job create -f <file-name>.yml
```

完全な例については、モデル GitHub レポジトリを参照してください。

Input クラスを使用すると次を定義できます。

モデル資産の種類。次のいずれかの値を指定できます。
- AssetTypes.CUSTOM_MODEL
- AssetTypes.MLFLOW_MODEL
- AssetTypes.TRITON_MODEL
モデルデータの path。次のいずれかの場所を指定できます。
- ローカルパス: <model-folder>/<model-filename>
- Azure Machine Learning データストア: azureml://datastores/<datastore-name>/paths/<path_on_datastore>
- MLflow 実行: runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>
- ジョブ: azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>
- モデル資産: azureml:<my_model>:<version>

次の例では、ローカルフォルダーから MLflow モデルを入力します。

from azure.ai.ml import command
from azure.ai.ml.entities import Model
from azure.ai.ml import Input
from azure.ai.ml.constants import AssetTypes
from azure.ai.ml import MLClient

my_job_inputs = {
    "input_model": Input(type=AssetTypes.MLFLOW_MODEL, path="mlflow-model")
}

job = command(
    code="./src",  # local path where the code is stored
    command="ls ${{inputs.input_model}}",
    inputs=my_job_inputs,
    environment="AzureML-sklearn-0.24-ubuntu18.04-py37-cpu:9",
    compute="cpu-cluster",
)

# submit the command
returned_job = ml_client.jobs.create_or_update(job)
# get a URL for the status of the job
returned_job.services["Studio"].endpoint

ジョブの出力としてモデルを書き込む

ジョブでは、outputs を使用してクラウドベースのストレージにモデルを書き込むことができます。

Azure CLI
Python SDK

ジョブ仕様の YAML ファイル <file-name>.yml を作成します。 outputs セクションに出力モデルの種類とパスを設定します。

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json

# Possible Paths for Model:
# Local path: mlflow-model/model.pkl
# AzureML Datastore: azureml://datastores/<datastore-name>/paths/<path_on_datastore>
# MLflow run: runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>
# Job: azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>
# Model Asset: azureml:<my_model>:<version>

code: src
command: >-
  python hello-model-as-output.py 
  --input_model ${{inputs.input_model}} 
  --custom_model_output ${{outputs.output_folder}}
inputs:
  input_model: 
    type: mlflow_model # mlflow_model,custom_model, triton_model
    path: ../../assets/model/mlflow-model
outputs:
  output_folder: 
    type: custom_model # mlflow_model,custom_model, triton_model
environment: azureml://registries/azureml/environments/sklearn-1.5/labels/latest

CLI を使用してジョブを作成します。
```
az ml job create --file <file-name>.yml
```

完全な例については、モデル GitHub レポジトリを参照してください。

Output クラスを使用すると次を定義できます。

モデル資産の種類。次のいずれかの値を指定できます。
- AssetTypes.CUSTOM_MODEL
- AssetTypes.MLFLOW_MODEL
- AssetTypes.TRITON_MODEL
モデルデータの path。次のいずれかの場所を指定できます。
- ローカルパス: mlflow-model/model.pkl
- Azure Machine Learning データストア: azureml://datastores/<datastore-name>/paths/<path_on_datastore>
- MLflow 実行: runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>
- ジョブ: azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>
- モデル資産: azureml:<my_model>:<version>

次の例では、既定のデータストアを読み取り/書き込みモードでマウントする出力を作成します。このコードでは単に、ローカル MLflow モデルを入力として読み込み、マウントされたデータストアに保存されたジョブの出力と同じモデルをエクスポートします。

from azure.ai.ml import command
from azure.ai.ml.entities import Model
from azure.ai.ml import Input, Output
from azure.ai.ml.constants import AssetTypes

my_job_inputs = {
    "input_model": Input(type=AssetTypes.MLFLOW_MODEL, path="mlflow-model"),
    "input_data": Input(type=AssetTypes.URI_FILE, path="./mlflow-model/input_example.json"),}

my_job_outputs = {
    "output_folder": Output(type=AssetTypes.CUSTOM_MODEL)
}

job = command(
    code="./src",  # local path where the code is stored
    command="python load_write_model.py --input_model ${{inputs.input_model}} --output_folder ${{outputs.output_folder}}",
    inputs=my_job_inputs,
    outputs=my_job_outputs,
    environment="AzureML-sklearn-0.24-ubuntu18.04-py37-cpu:9",
    compute="cpu-cluster",
)

# submit the command
returned_job = ml_client.create_or_update(job)
# get a URL for the status of the job
returned_job.services["Studio"].endpoint

モデルを管理する

Azure CLI と Python SDK では、Azure Machine Learning モデル資産のライフサイクルを管理することもできます。

一覧取得

Azure CLI
Python SDK

次にワークスペース内のすべてのモデルを一覧表示します。

az ml model list

指定された名前のすべてのモデルバージョンを一覧表示します。

az ml model list --name run-model-example

次にワークスペース内のすべてのモデルを一覧表示します。

models = ml_client.models.list()
for model in models:
    print(model.name)

指定された名前のすべてのモデルバージョンを一覧表示します。

models = ml_client.models.list(name="run-model-example")
for model in models:
    print(model.version)

表示

特定のモデルの詳細を取得します。

Azure CLI
Python SDK

az ml model show --name run-model-example --version 1

model_example = ml_client.models.get(name="run-model-example", version="1")
print(model_example)

更新

次の特定のモデルの変更可能なプロパティを更新します。

重要

モデルの場合、更新できるのは description と tags のみです。その他のすべてのプロパティは変更できません。変更する必要がある場合は、新しいバージョンのモデルを作成する必要があります。

Azure CLI
Python SDK

az ml model update --name  run-model-example --version 1 --set description="This is an updated description." --set tags.stage="Prod"

model_example.description="This is an updated description."
model_example.tags={"stage":"Prod"}
ml_client.models.create_or_update(model=model_example)

アーカイブ

モデルをアーカイブすると、既定で az ml model list のようにリストクエリから非表示になります。アーカイブされたモデルは、ワークフローで参照し、使用し続けることができます。

モデルのすべてのバージョンまたは特定のバージョンのみをアーカイブできます。バージョンを指定しない場合、モデルのすべてのバージョンがアーカイブされます。アーカイブされたモデルコンテナーの下に新しいモデルバージョンを作成すると、新しいバージョンも自動的にアーカイブ済みとして設定されます。

Azure CLI
Python SDK

次のモデルのすべてのバージョンをアーカイブします。

az ml model archive --name run-model-example

次の特定のモデルのバージョンをアーカイブします。

az ml model archive --name run-model-example --version 1

次のモデルのすべてのバージョンをアーカイブします。

ml_client.models.archive(name="run-model-example")

次の特定のモデルのバージョンをアーカイブします。

ml_client.models.archive(name="run-model-example", version="1")

次の方法で共有

Azure Machine Learning で登録済みモデルを操作する

モデルの登録

サポートされているパス

サポートされているモード

前提条件

スタジオ UI を使用してモデルを登録する

Azure CLI または Python SDK を使用してモデルを登録する

ワークスペースに接続する

登録済みモデルを作成する

ローカルファイルまたはフォルダー

データストア

ジョブの出力

トレーニングにモデルを使用する

トレーニングジョブでモデルを入力として使用する

ジョブの出力としてモデルを書き込む

モデルを管理する

一覧取得

表示

更新

アーカイブ

フィードバック

フィードバック

その他のリソース

次の方法で共有

Azure Machine Learning で登録済みモデルを操作する

モデルの登録

サポートされているパス

サポートされているモード

前提条件

スタジオ UI を使用してモデルを登録する

Azure CLI または Python SDK を使用してモデルを登録する

ワークスペースに接続する

登録済みモデルを作成する

ローカル ファイルまたはフォルダー

データストア

ジョブの出力

トレーニングにモデルを使用する

トレーニング ジョブでモデルを入力として使用する

ジョブの出力としてモデルを書き込む

モデルを管理する

一覧取得

表示

更新

アーカイブ

関連するコンテンツ

フィードバック

フィードバック

その他のリソース

ローカルファイルまたはフォルダー

トレーニングジョブでモデルを入力として使用する