将模型部署为联机终结点

适用于：Python SDK azure-ai-ml v2（当前版本）

了解如何使用 Azure 机器学习 Python SDK v2 将模型部署到联机终结点。

在本教程中，部署并使用一个模型来预测客户信用卡付款违约的可能性。

可采取以下步骤：

先决条件

1. 若要使用 Azure 机器学习，你首先需要一个工作区。 如果没有工作区，请完成创建开始使用所需的资源以创建工作区并详细了解如何使用它。

2. 登录到工作室，选择工作区（如果尚未打开）。

3. 在工作区中打开或创建一个笔记本：

   • 如果要将代码复制/粘贴到单元格中，请创建新的笔记本。
   • 或者从工作室的“示例”部分打开 tutorials/get-started-notebooks/deploy-model.ipynb。 然后选择“克隆”，将笔记本添加到你的“文件”。 （了解在何处找到“示例”。）

4. 查看 VM 配额并确保有足够的配额可用于创建联机部署。 在本教程中，至少需要 8 个 STANDARD_DS3_v2 核心和 12 个 STANDARD_F4s_v2 核心。 若要查看 VM 配额使用情况并请求增加配额，请参阅管理资源配额。

设置内核

1. 在打开的笔记本上方的顶部栏中，创建一个计算实例（如果还没有计算实例）。

   

2. 如果计算实例已停止，请选择“启动计算”，并等待它运行。

   

3. 确保右上角的内核为 Python 3.10 - SDK v2。 如果不是，请使用下拉列表选择此内核。

   

4. 如果看到一个横幅，提示你需要进行身份验证，请选择“身份验证”。

创建工作区句柄

在深入了解代码之前，需要一种方法来引用工作区。 为工作区的句柄创建 ml_client，并使用 ml_client 来管理资源和作业。

在下一个单元中，输入你的订阅 ID、资源组名称和工作区名称。 若要查找这些值：

1. 在右上方的 Azure 机器学习工作室工具栏中，选择你的工作区名称。
2. 将工作区、资源组和订阅 ID 的值复制到代码中。
3. 需要复制一个值，关闭区域并粘贴，然后返回继续复制下一个值。

from azure.ai.ml import MLClient
from azure.identity import DefaultAzureCredential

# authenticate
credential = DefaultAzureCredential()

# Get a handle to the workspace
ml_client = MLClient(
    credential=credential,
    subscription_id="<SUBSCRIPTION_ID>",
    resource_group_name="<RESOURCE_GROUP>",
    workspace_name="<AML_WORKSPACE_NAME>",
)

注册模型

如果你已完成前面的训练教程：训练模型，则你已将 MLflow 模型注册为训练脚本的一部分，可以跳到下一部分。

如果未完成训练教程，则需要注册模型。 建议的最佳做法是在部署前注册模型。

下面的代码以内联方式指定 path（从中上传文件的位置）。 如果你克隆了教程文件夹，则按原样运行以下代码。 否则，请下载要部署的模型的文件和元数据并解压缩文件。 更新本地计算机上已解压缩文件的位置的路径。

SDK 会自动上传文件并注册模型。

有关将模型注册为资产的详细信息，请参阅使用 SDK 在机器学习中将模型注册为资产。

# Import the necessary libraries
from azure.ai.ml.entities import Model
from azure.ai.ml.constants import AssetTypes

# Provide the model details, including the
# path to the model files, if you've stored them locally.
mlflow_model = Model(
    path="./deploy/credit_defaults_model/",
    type=AssetTypes.MLFLOW_MODEL,
    name="credit_defaults_model",
    description="MLflow Model created from local files.",
)

# Register the model
ml_client.models.create_or_update(mlflow_model)

确认模型已注册

可以查看 Azure 机器学习工作室中的“模型”页，以识别已注册模型的最新版本。

或者，可以使用以下代码检索可用的最新版本号。

registered_model_name = "credit_defaults_model"

# Let's pick the latest version of the model
latest_model_version = max(
    [int(m.version) for m in ml_client.models.list(name=registered_model_name)]
)

print(latest_model_version)

拥有已注册的模型后，可以创建终结点和部署。 下一部分简要介绍有关这些主题的一些关键详细信息。

终结点和部署

训练了机器学习模型后，需要部署它，以便其他人可以将其用于推理。 为此，Azure 机器学习允许创建终结点并向其添加部署。

在此上下文中，终结点是一个 HTTPS 路径，它为客户端提供一个接口，用于将请求（输入数据）发送到训练后的模型，并接收来自模型的推理（评分）结果。 终结点提供：

• 使用基于“密钥和令牌”的身份验证
• TLS(SSL) 终止
• 稳定的评分 URI (endpoint-name.region.inference.studio.ml.azure.cn)

部署是一组资源，用于承载执行实际推理的模型。

一个终结点可以包含多个部署。 终结点和部署是显示在 Azure 门户中的独立 Azure 资源管理器资源。

Azure 机器学习允许实现联机终结点，以便对客户端数据进行实时推理，并可实现批处理终结点，以便在一段时间内对大量数据进行推理。

在本教程中，你将完成实现托管联机终结点的步骤。 托管联机终结点以可缩放的完全托管方式与 Azure 中功能强大的 CPU 和 GPU 计算机配合使用，使你无需设置和管理底层部署基础结构的开销。

创建联机终结点

现在，你拥有了一个已注册的模型，接下来可以创建联机终结点。 终结点名称需在整个 Azure 区域中唯一。 在本教程中，你将使用通用唯一标识符 UUID 创建唯一名称。 有关终结点命名规则的详细信息，请参阅终结点限制。

import uuid

# Create a unique name for the endpoint
online_endpoint_name = "credit-endpoint-" + str(uuid.uuid4())[:8]

首先，使用 ManagedOnlineEndpoint 类定义终结点。

from azure.ai.ml.entities import ManagedOnlineEndpoint

# define an online endpoint
endpoint = ManagedOnlineEndpoint(
    name=online_endpoint_name,
    description="this is an online endpoint",
    auth_mode="key",
    tags={
        "training_dataset": "credit_defaults",
    },
)

使用前面创建的 MLClient，在工作区中创建终结点。 此命令会启动终结点创建操作，并在终结点创建操作继续时返回确认响应。

# create the online endpoint
# expect the endpoint to take approximately 2 minutes.

endpoint = ml_client.online_endpoints.begin_create_or_update(endpoint).result()

创建终结点后，可按如下方式检索它：

endpoint = ml_client.online_endpoints.get(name=online_endpoint_name)

print(
    f'Endpoint "{endpoint.name}" with provisioning state "{endpoint.provisioning_state}" is retrieved'
)

了解联机部署

部署的关键方面包括：

• name - 部署的名称。
• endpoint_name - 将包含部署的终结点的名称。
• model - 要用于部署的模型。 此值可以是对工作区中现有版本受控模型的引用，也可以是对内联模型规范的引用。
• environment - 用于部署（或运行模型）的环境。 此值可以是对工作区中现有版本受控环境的引用，也可以是对内联环境规范的引用。 环境可以是包含 Conda 依赖项的 Docker 映像，也可以是 Dockerfile。
• code_configuration - 源代码和评分脚本的配置。
  • path - 用于对模型评分的源代码目录的路径。
  • scoring_script - 源代码目录中评分文件的相对路径。 此脚本根据给定的输入请求执行模型。 有关评分脚本的示例，请参阅“使用联机终结点部署 ML 模型”一文中的“了解评分脚本”。
• instance_type - 用于部署的 VM 大小。 有关支持的大小列表，请参阅托管联机终结点 SKU 列表。
• instance_count - 用于部署的实例数。

使用 MLflow 模型的部署

Azure 机器学习支持使用 MLflow 创建和记录的模型的无代码部署。 这意味着，无需在模型部署期间提供评分脚本或环境，因为评分脚本和环境是在训练 MLflow 模型时自动生成的。 但是，如果使用自定义模型，则必须在部署期间指定环境和评分脚本。

将模型部署到终结点

首先创建处理 100% 传入流量的单个部署。 为部署选择任意颜色名称（蓝色）。 若要为终结点创建部署，请使用 ManagedOnlineDeployment 类。

from azure.ai.ml.entities import ManagedOnlineDeployment

# Choose the latest version of the registered model for deployment
model = ml_client.models.get(name=registered_model_name, version=latest_model_version)

# define an online deployment
# if you run into an out of quota error, change the instance_type to a comparable VM that is available.\
# Learn more on https://www.azure.cn/en-us/pricing/details/machine-learning/.
blue_deployment = ManagedOnlineDeployment(
    name="blue",
    endpoint_name=online_endpoint_name,
    model=model,
    instance_type="Standard_DS3_v2",
    instance_count=1,
)

现在，使用前面创建的 MLClient 在工作区中创建部署。 此命令将启动部署创建操作，并在部署创建操作继续时返回确认响应。

# create the online deployment
blue_deployment = ml_client.online_deployments.begin_create_or_update(
    blue_deployment
).result()

# blue deployment takes 100% traffic
# expect the deployment to take approximately 8 to 10 minutes.
endpoint.traffic = {"blue": 100}
ml_client.online_endpoints.begin_create_or_update(endpoint).result()

检查终结点的状态

可以检查终结点的状态，以查看模型是否已部署且未出错：

# return an object that contains metadata for the endpoint
endpoint = ml_client.online_endpoints.get(name=online_endpoint_name)

# print a selection of the endpoint's metadata
print(
    f"Name: {endpoint.name}\nStatus: {endpoint.provisioning_state}\nDescription: {endpoint.description}"
)

# existing traffic details
print(endpoint.traffic)

# Get the scoring URI
print(endpoint.scoring_uri)

使用示例数据测试终结点

将模型部署到终结点后，接下来可以使用它来运行推理。 首先创建一个示例请求文件，该文件遵循在评分脚本中找到的 run 方法中的预期设计。

import os

# Create a directory to store the sample request file.
deploy_dir = "./deploy"
os.makedirs(deploy_dir, exist_ok=True)

现在，在部署目录中创建文件。 下面的代码单元使用 IPython magic 将文件写入刚刚创建的目录中。

%%writefile {deploy_dir}/sample-request.json
{
  "input_data": {
    "columns": [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22],
    "index": [0, 1],
    "data": [
            [20000,2,2,1,24,2,2,-1,-1,-2,-2,3913,3102,689,0,0,0,0,689,0,0,0,0],
            [10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 10, 9, 8]
            ]
                }
}

使用前面创建的 MLClient，获取终结点的句柄。 可以使用 invoke 命令和以下参数来调用终结点：

• endpoint_name - 终结点的名称
• request_file - 包含请求数据的文件
• deployment_name - 要在终结点中测试的特定部署的名称

使用示例数据测试蓝色部署。

# test the blue deployment with the sample data
ml_client.online_endpoints.invoke(
    endpoint_name=online_endpoint_name,
    deployment_name="blue",
    request_file="./deploy/sample-request.json",
)

获取部署日志

检查日志以查看终结点/部署是否已成功调用。 如果遇到错误，请参阅排查联机终结点部署问题。

logs = ml_client.online_deployments.get_logs(
    name="blue", endpoint_name=online_endpoint_name, lines=50
)
print(logs)

创建第二个部署

将模型部署为名为 green 的第二个部署。 在实践中，可以创建多个部署并比较其性能。 这些部署可以使用相同模型的不同版本、不同模型或功能更强大的计算实例。

在此示例中，使用更强大的计算实例部署相同的模型版本，性能可能会有所提高。

# pick the model to deploy. Here you use the latest version of the registered model
model = ml_client.models.get(name=registered_model_name, version=latest_model_version)

# define an online deployment using a more powerful instance type
# if you run into an out of quota error, change the instance_type to a comparable VM that is available.\
# Learn more on https://www.azure.cn/en-us/pricing/details/machine-learning/.
green_deployment = ManagedOnlineDeployment(
    name="green",
    endpoint_name=online_endpoint_name,
    model=model,
    instance_type="Standard_F4s_v2",
    instance_count=1,
)

# create the online deployment
# expect the deployment to take approximately 8 to 10 minutes
green_deployment = ml_client.online_deployments.begin_create_or_update(
    green_deployment
).result()

扩展部署以处理更多流量

借助前面创建的 MLClient，可获取 green 部署的句柄。 然后可以通过增加或减少 instance_count 来缩放该部署。

在以下代码中，手动增加 VM 实例。 但是，还可以自动缩放联机终结点。 自动缩放会自动运行适量的资源来处理应用程序的负载。 托管联机终结点支持通过与 Azure Monitor 自动缩放功能的集成进行自动缩放。 要配置自动缩放，请参阅自动缩放联机终结点。

# update definition of the deployment
green_deployment.instance_count = 2

# update the deployment
# expect the deployment to take approximately 8 to 10 minutes
ml_client.online_deployments.begin_create_or_update(green_deployment).result()

更新部署的流量分配

可以在部署之间拆分生产流量。 你可能首先需要使用示例数据测试 green 部署，就像对 blue 部署所做的那样。 测试了绿色部署后，为其分配一小部分流量。

endpoint.traffic = {"blue": 80, "green": 20}
ml_client.online_endpoints.begin_create_or_update(endpoint).result()

通过多次调用终结点来测试流量分配：

# You can invoke the endpoint several times
for i in range(30):
    ml_client.online_endpoints.invoke(
        endpoint_name=online_endpoint_name,
        request_file="./deploy/sample-request.json",
    )

显示 green 部署中的日志，以检查是否存在传入请求且模型是否成功评分。

logs = ml_client.online_deployments.get_logs(
    name="green", endpoint_name=online_endpoint_name, lines=50
)
print(logs)

使用 Azure Monitor 查看指标

可以查看联机终结点及其部署的各种指标（请求数、请求延迟、网络字节数、CPU/GPU/磁盘/内存利用率等），方法是在工作室中查看终结点的详细信息页中的链接。 点击以下任意链接可在 Azure 门户中访问终结点或部署的指标页面。

如果打开联机终结点的指标，则可以设置页面以查看指标，例如平均请求延迟，如下图所示。

有关如何查看联机终结点指标的详细信息，请参阅监视联机终结点。

将所有流量发送到新部署

对 green 部署完全满意后，将所有流量切换到该部署。

endpoint.traffic = {"blue": 0, "green": 100}
ml_client.begin_create_or_update(endpoint).result()

删除旧部署

删除旧（蓝色）部署：

ml_client.online_deployments.begin_delete(
    name="blue", endpoint_name=online_endpoint_name
).result()

清理资源

如果在完成此教程后你不打算使用终结点和部署，则应该删除它们。

ml_client.online_endpoints.begin_delete(name=online_endpoint_name).result()

删除所有内容

使用这些步骤可删除 Azure 机器学习工作区和所有计算资源。

如果你不打算使用已创建的任何资源，请删除它们，以免产生任何费用：

1. 在 Azure 门户中，选择最左侧的“资源组” 。

2. 从列表中选择你创建的资源组。

3. 选择“删除资源组”。

   

4. 输入资源组名称。 然后选择“删除”。

下一步