在 Azure 機器學習中使用已註冊的模型

發行項
06/13/2024

適用於：Azure CLI ml 延伸模組 v2 (目前)Python SDK azure-ai-ml v2 (目前)

在本文中，您將瞭解如何使用下列方式在 Azure 機器學習中註冊和使用模型：

Azure Machine Learning 工作室 UI。
Azure 機器學習 V2 CLI。
Python Azure 機器學習 V2 SDK。

您將學習如何：

從本機檔案、數據存放區或作業輸出，在模型登錄中建立已註冊的模型。
使用不同類型的模型，例如自定義、MLflow 和 Triton。
在定型作業中使用模型作為輸入或輸出。
管理模型資產的生命週期。

模型註冊

模型註冊可讓您在 Azure 雲端的工作區中儲存模型並設定其版本。模型登錄可協助您組織和追蹤已定型模型。您可以使用 Azure CLI、Python SDK 或機器學習 Studio UI，將模型註冊為 Azure 機器學習中的資產。

支援的路徑

若要註冊模型，您必須指定指向資料或作業位置的路徑。下表顯示 Azure 機器學習支援的各種資料位置，以及參數的path語法：

Location	語法
本機電腦	`<model-folder>/<model-filename>`
Azure 機器學習數據存放區	`azureml://datastores/<datastore-name>/paths/<path_on_datastore>`
Azure 機器學習作業	`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>`
在機器學習工作區中建立資產模型	`azureml:<model-name>:<version>`
在機器學習登錄中建立資產模型	`azureml://registries/<registry-name>/models/<model-name>/versions/<version>`

支援的模式

當您將模型用於輸入或輸出時，您可以指定下列 其中一種模式。例如，您可以指定模型是否應該掛接只讀，或下載至計算目標。

ro_mount：將數據掛接至計算目標做為唯讀。
rw_mount：讀寫掛接數據。
download：將數據下載至計算目標。
upload：從計算目標上傳數據。
direct：以字串的形式傳入 URI。

下表顯示不同模型類型輸入和輸出的可用模式選項。

類型	`upload`	`download`	`ro_mount`	`rw_mount`	`direct`
`custom` 檔案輸入
`custom` 資料夾輸入		✓	✓		✓
`mlflow` 輸入		✓	✓
`custom` 檔案輸出	✓			✓	✓
`custom` 資料夾輸出	✓			✓	✓
`mlflow` 輸出	✓			✓	✓

必要條件

Azure 訂用帳戶，具有免費或付費版本的 Azure 機器學習。如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。
Azure Machine Learning 工作區。

若要執行本文中的程式代碼範例，並使用 Azure 機器學習 V2 CLI 或 Python Azure 機器學習 V2 SDK，您也需要：

Azure CLI
Python SDK

已安裝 Azure CLI 2.38.0 版或更新版本。
執行下列命令來安裝延伸模組的 ml V2。如需詳細資訊，請參閱安裝、設定和使用 CLI (v2)。
```
az extension add -n ml
```

注意

V2 提供完整的回溯相容性。您仍然可以從 v1 SDK 或 CLI 使用模型資產。所有向 v1 CLI 或 SDK 註冊的模型都會指派類型 custom。

使用 Studio UI 註冊模型

若要使用 Azure Machine Learning 工作室 UI 註冊模型：

在 Studio 的工作區中，從左側導覽中選取 [模型 ]。
在 [ 模型清單] 頁面上，選取 [ 註冊]，然後從下拉式清單中選取下列其中一個位置：
- 從本機檔案
- 從作業輸出
- 從數據存放區
- 從本機檔案（根據架構）
在第一個 [註冊模型] 畫面上：
1. 流覽至模型的本機檔案、數據存放區或作業輸出。
2. 選擇輸入模型類型：MLflow、Triton 或 Unspecified 類型。
在 [ 模型設定 ] 畫面上，提供已註冊模型的名稱和其他選擇性設定，然後選取 [ 下一步]。
在 [ 檢閱] 畫面上檢閱設定，然後選取 [ 註冊]。

使用 Azure CLI 或 Python SDK 註冊模型

下列代碼段說明如何使用 Azure CLI 或 Python SDK，在 Azure 機器學習中將模型註冊為資產。這些代碼段會使用 custom 和 mlflow 模型類型。

customtype 是指以 Azure 機器學習目前不支援的自定義標準定型的模型檔案或資料夾。
mlflow type 是指使用 MLflow 定型的模型。 MLflow 定型模型位於資料夾中，其中包含 MLmodel 檔案、模型檔案、conda 相依性檔案，以及 requirements.txt 檔案。

提示

您可以遵循下列範例的 Python 版本，方法是在 azureml-examples 存放庫中執行 model.ipynb Notebook。

連線到您的工作區

工作區是 Azure Machine Learning 的最上層資源，其提供一個集中位置來處理您在使用 Azure Machine Learning 時建立的所有成品。在本節中，您會連線到 Azure 機器學習工作區，以建立已註冊的模型。

Azure CLI
Python SDK

執行 az login 並遵循提示來登入 Azure。

在下列命令中，將、<workspace-name>、 <resource-group>和 <location> 佔位元取代<subscription-id>為您環境的值。

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 機器學習資料存放區。
Azure 機器學習作業的輸出。

建立 YAML 檔案 <檔名>.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)

Datastore

您可以使用任何支援的 URI 格式，從雲端路徑建立模型。

Azure CLI
Python SDK

下列範例使用速記 azureml 配置，以使用語法 azureml://datastores/<datastore-name>/paths/<path_on_datastore>指向數據存放區上的路徑。

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

如需完整範例，請參閱 CLI 參考。

下列範例使用速記 azureml 配置，以使用語法 azureml://datastores/${{datastore-name}}/paths/${{path_on_datastore}}指向數據存放區上的路徑。

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)

作業輸出

如果您的模型資料來自作業輸出，您有兩個選項可用來指定模型路徑。您可以使用 MLflow runs: URI 格式或 azureml://jobs URI 格式。

注意

成品保留關鍵詞代表預設成品位置的輸出。

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 檔案、 <檔名>.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 機器學習數據存放區：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

將模型寫入為作業的輸出

您的作業可以使用輸出，將模型寫入雲端式記憶體。

Azure CLI
Python SDK

建立作業規格 YAML 檔案 <檔名>.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 機器學習數據存放區：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 機器學習模型資產的生命週期。

清單

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 機器學習中使用已註冊的模型

模型註冊

支援的路徑

支援的模式

必要條件

使用 Studio UI 註冊模型

使用 Azure CLI 或 Python SDK 註冊模型

連線到您的工作區

建立已註冊的模型

本機檔案或資料夾

Datastore

作業輸出

使用模型進行定型

在定型作業中使用模型作為輸入

將模型寫入為作業的輸出

管理模型

清單

顯示

更新

封存

意見反應

意見反應

其他資源

共用方式為

在 Azure 機器學習 中使用已註冊的模型

模型註冊

支援的路徑

支援的模式

必要條件

使用 Studio UI 註冊模型

使用 Azure CLI 或 Python SDK 註冊模型

連線到您的工作區

建立已註冊的模型

本機檔案或資料夾

Datastore

作業輸出

使用模型進行定型

在定型作業中使用模型作為輸入

將模型寫入為作業的輸出

管理模型

清單​​

顯示

更新

封存

相關內容

意見反應

意見反應

其他資源

在 Azure 機器學習中使用已註冊的模型

清單