在 Azure 机器学习中使用已注册的模型

项目
08/14/2024

适用范围：Azure CLI ml 扩展 v2（最新版）Python SDK azure-ai-ml v2（最新版）

本文介绍如何使用以下方法在 Azure 机器学习中注册和使用模型：

Azure 机器学习工作室 UI。
Azure 机器学习 V2 CLI。
Python Azure 机器学习 V2 SDK。

学习如何：

从本地文件、数据存储或作业输出在模型注册表中创建已注册的模型。
使用不同类型的模型，例如自定义、MLflow 和 Triton。
在训练作业中使用模型作为输入或输出。
管理模型资产的生命周期。

模型的注册

通过模型注册，可在 Azure 云的工作区中存储模型并控制模型版本。模型注册表可帮助你组织和跟踪已训练的模型。可以使用 Azure CLI、Python SDK 或机器学习工作室 UI 将模型注册为 Azure 机器学习中的资产。

支持的路径

若要注册模型，需要指定指向数据或作业位置的路径。下表显示了 Azure 机器学习支持的各种数据位置，以及 path 参数的语法：

位置	语法
本地计算机	`<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 机器学习工作区。

若要运行本文中的代码示例并使用 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 类型。

使用工作室 UI 注册模型

若要使用 Azure 机器学习工作室 UI 注册模型，请执行以下操作：

在工作室的工作区中，选择左侧导航中的“模型”。
在“模型列表”页上，选择“注册”，然后从下拉列表中选择以下位置之一：
- 从本地文件
- 从作业输出
- 从数据存储
- 从本地文件(基于框架)
在第一个“注册模型”屏幕上：
1. 导航到模型的本地文件、数据存储或作业输出。
2. 选择输入模型类型：“MLflow”、“Triton”或“未指定类型”。
在“模型设置”屏幕上，提供已注册模型的名称和其他可选设置，然后选择“下一步”。
在“查看”屏幕上，查看配置，然后选择“注册”。

使用 Azure CLI 或 Python SDK 注册模型

以下代码片段介绍如何使用 Azure CLI 或 Python SDK 在 Azure 机器学习中将模型注册为资产。这些代码片段使用 custom 和 mlflow 模型类型。

custom 类型指的是使用 Azure 机器学习当前不支持的自定义标准训练的模型文件或文件夹。
mlflow 类型指的是使用 MLflow 训练的模型。 MLflow 训练的模型位于包含 MLmodel 文件、模型文件、conda 依赖项文件和 requirements.txt 文件的文件夹中。

提示

可以通过运行 azureml-examples 存储库中的 model.ipynb 笔记本来跟踪以下示例的 Python 版本。

连接到工作区

工作区是 Azure 机器学习的顶级资源，为使用 Azure 机器学习时创建的所有项目提供了一个集中的处理位置。在本部分中，将连接到 Azure 机器学习工作区以创建已注册的模型。

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 机器学习数据存储上。
Azure 机器学习作业的输出。

创建 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)

作业输出

如果模型数据来自作业输出，则有两个选项来指定模型路径。可以使用 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 文件 <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: /machine-learning/reference-yaml-model#yaml-syntax
    path: ../../assets/model/mlflow-model
environment: azureml://registries/azureml/environments/sklearn-1.0/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 文件 <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:AzureML-sklearn-1.0-ubuntu20.04-py38-cpu@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