閱讀英文

共用方式為

使用联机终结点部署机器学习模型并对其进行评分

  • 發行項
  • 2024/08/26

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

本文介绍如何将模型部署到联机终结点以用于实时推理。 首先在本地计算机上部署一个模型以调试任何错误。 然后，在 Azure 中部署和测试模型，查看部署日志，并监视服务级别协议 (SLA)。 在本文结束时，你将拥有一个可缩放的 HTTPS/REST 终结点，可用于实时推理。

联机终结点是用于实时推理的终结点。 有两种类型的联机终结点：托管联机终结点和 Kubernetes 联机终结点。 有关终结点的详细信息以及托管联机终结点与 Kubernetes 联机终结点之间的差异，请参阅什么是 Azure 机器学习终结点？

托管联机终结点有助于以统包方式部署机器学习模型。 托管联机终结点在 Azure 中以一种可缩放的、完全托管的方式使用功能强大的 CPU 和 GPU 计算机。 托管联机终结点负责处理、缩放、保护和监视你的模型，使你没有设置和管理底层基础结构的开销。

本文档中的主要示例使用托管联机终结点进行部署。 若要改用 Kubernetes，请参阅本文档中与托管联机终结点讨论内联的注释。

先决条件

适用于：Azure CLI ml 扩展 v2（当前）

在按照本文中的步骤操作之前，请确保满足以下先决条件：

  • Azure 基于角色的访问控制 (Azure RBAC) 用于授予对 Azure 机器学习中的操作的访问权限。 若要执行本文中的步骤，必须为用户帐户分配 Azure 机器学习工作区的所有者或参与者角色，或者分配一个允许 Microsoft.MachineLearningServices/workspaces/onlineEndpoints/* 的自定义角色。 如果使用工作室创建/管理联机终结点/部署，则需要资源组所有者提供的附加权限“Microsoft.Resources/deployments/write”。 有关详细信息，请参阅管理对 Azure 机器学习工作区的访问。

  • （可选）若要在本地部署，必须在本地计算机上安装 Docker 引擎。 强烈建议选择此选项，以便更轻松地调试问题。

  • 确保为部署分配了足够的虚拟机 (VM) 配额。 Azure 机器学习会保留 20% 的计算资源，以便在某些 VM SKU 上执行升级。 例如，如果在部署中请求 10 个实例，则必须为 VM SKU 的每个核心数指定 12 个配额。 未能考虑额外的计算资源会导致错误。 有些 VM SKU 不受额外配额预留的限制。 有关配额分配的更多信息，请参阅部署的虚拟机配额分配。

  • 或者，可以在有限的时间内使用 Azure 机器学习的共享配额池中的配额。 Azure 机器学习提供了一个共享配额池，不同区域中的用户可以根据可用性从中访问配额以执行有限时间的测试。 使用工作室将 Llama-2、Phi、Nemotron、Mistral、Dolly 和 Deci-DeciLM 模型从模型目录部署到托管联机终结点时，Azure 机器学习允许你在短时间访问其共享配额池，以便执行测试。 有关共享配额池的详细信息，请参阅 Azure 机器学习共享配额。

准备你的系统

设置环境变量。

如果尚未为 Azure CLI 指定默认设置，则应保存默认设置。 若要避免多次传入订阅、工作区和资源组的值，请运行此代码：

az account set --subscription <subscription ID>
az configure --defaults workspace=<Azure Machine Learning workspace name> group=<resource group>

克隆示例存储库

若要按照本文的说明进行操作，请先克隆示例存储库 (azureml-examples)。 然后，运行以下代码，以转至存储库的 cli/ 目录：

git clone --depth 1 https://github.com/Azure/azureml-examples
cd azureml-examples
cd cli

提示

使用 --depth 1 仅克隆最新提交到存储库的内容，从而减少完成操作所需的时间。

本教程中的命令位于 cli 目录中的文件 deploy-local-endpoint.sh 和 deploy-managed-online-endpoint.sh 内，YAML 配置文件位于 endpoints/online/managed/sample/ 子目录中。

注意

Kubernetes 联机终结点的 YAML 配置文件位于 endpoints/online/kubernetes/ 子目录中。

定义终结点

若要定义联机终结点，请指定终结点名称和身份验证模式。 有关托管联机终结点的详细信息，请参阅联机终结点。

设置终结点名称

要设置你的终结点名称，请运行以下命令。 将 YOUR_ENDPOINT_NAME 替换为在 Azure 区域中唯一的名称。 有关命名规则的详细信息，请参阅终结点限制。

对于 Linux，请运行以下命令：

export ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"

配置终结点

以下代码段显示了 endpoints/online/managed/sample/endpoint.yml 文件：

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: key

下表描述了 YAML 格式的终结点的参考资料。 若要了解如何指定这些属性，请参阅联机终结点 YAML 参考。 如需了解与托管终结点相关的限制，请参阅联机终结点限制。

密钥 说明
$schema （可选）YAML 架构。 若要查看 YAML 文件的所有可用选项，可在浏览器中查看上述代码片段中的架构。
name 终结点的名称。
auth_mode 使用 key 可执行基于密钥的身份验证。
使用 aml_token 可执行基于 Azure 机器学习令牌的身份验证。
使用 aad_token 进行基于 Microsoft Entra 令牌的身份验证（预览版）。
有关身份验证的详细信息，请参阅对联机终结点的客户端进行身份验证。

定义部署

部署是一组资源，用于承载执行实际推理的模型。 在此示例中，你将部署一个执行回归的 scikit-learn 模型，并使用评分脚本 score.py 根据给定的输入请求执行该模型。

若要了解部署的关键属性，请参阅联机部署。

配置部署

部署配置使用你希望部署的模型的位置。

以下代码片段显示了 endpoints/online/managed/sample/blue-deployment.yml 文件，其中包含配置部署所需的所有输入：

blue-deployment.yml

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-endpoint
model:
  path: ../../model-1/model/
code_configuration:
  code: ../../model-1/onlinescoring/
  scoring_script: score.py
environment: 
  conda_file: ../../model-1/environment/conda.yaml
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
instance_type: Standard_DS3_v2
instance_count: 1

blue-deployment.yml 文件指定以下部署属性：

  • model - 使用 path（上传文件的位置）指定内联模型属性。 CLI 自动上传模型文件并使用自动生成的名称注册模型。
  • environment - CLI 使用包含上传文件位置的内联定义自动上传 conda.yaml 文件并注册环境。 随后，为了构建环境，部署使用 image（在本示例中为 mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest）作为基础映像，并将 conda_file 依赖项安装在基础映像之上。
  • code_configuration - 在部署期间，本地文件（如评分模型的 Python 源）是从开发环境上传的。

有关 YAML 架构的详细信息，请参阅联机终结点 YAML 参考。

注意

若要使用 Kubernetes 终结点而不是托管联机终结点作为计算目标：

  1. 使用 Azure 机器学习工作室创建 Kubernetes 群集并将其作为计算目标附加到 Azure 机器学习工作区。
  2. 使用终结点 YAML 而不是托管终结点 YAML 来定位 Kubernetes。 需要编辑 YAML，将 compute 的值更改为注册的计算目标的名称。 可以使用此 deployment.yaml，它具有适用于 Kubernetes 部署的其他属性。

本文中针对托管联机终结点使用的所有命令也适用于 Kubernetes 终结点，但以下功能不适用于 Kubernetes 终结点：

了解评分脚本

提示

联机终结点的评分脚本格式与早期版本的 CLI 和 Python SDK 中使用的格式相同。

code_configuration.scoring_script 中指定的评分脚本必须具有一个 init() 函数和一个 run() 函数。

此示例使用 score.py 文件：score.py

import os
import logging
import json
import numpy
import joblib


def init():
    """
    This function is called when the container is initialized/started, typically after create/update of the deployment.
    You can write the logic here to perform init operations like caching the model in memory
    """
    global model
    # AZUREML_MODEL_DIR is an environment variable created during deployment.
    # It is the path to the model folder (./azureml-models/$MODEL_NAME/$VERSION)
    # Please provide your model's folder name if there is one
    model_path = os.path.join(
        os.getenv("AZUREML_MODEL_DIR"), "model/sklearn_regression_model.pkl"
    )
    # deserialize the model file back into a sklearn model
    model = joblib.load(model_path)
    logging.info("Init complete")


def run(raw_data):
    """
    This function is called for every invocation of the endpoint to perform the actual scoring/prediction.
    In the example we extract the data from the json input and call the scikit-learn model's predict()
    method and return the result back
    """
    logging.info("model 1: request received")
    data = json.loads(raw_data)["data"]
    data = numpy.array(data)
    result = model.predict(data)
    logging.info("Request processed")
    return result.tolist()

初始化或启动容器时，将调用函数 init()。 初始化通常在创建或更新部署后立即发生。 可通过 init 函数编写逻辑以执行全局初始化操作，例如在内存中高速缓存模型（如此 score.py 文件所示）。

每次调用终结点时，都将调用 run() 函数，该函数将执行实际的评分和预测。 在此 score.py 文件中，run() 函数将从 JSON 输入中提取数据，调用 scikit-learn 模型的 predict() 方法，然后返回预测结果。

使用本地终结点在本地部署和调试

强烈建议在本地测试运行终结点，以在部署到 Azure 之前验证和调试代码和配置。 Azure CLI 和 Python SDK 支持本地终结点和部署，而 Azure 机器学习工作室和 ARM 模板则不支持。

若要在本地部署，必须安装并运行 Docker 引擎。 Docker 引擎通常在计算机启动时启动。 如果它不启动，可以对 Docker 引擎进行故障排除。

提示

可以使用 Azure 机器学习推理 HTTP 服务器 Python 包在本地调试评分脚本而无需 Docker 引擎。 使用推理服务器进行调试有助于在部署到本地终结点之前调试评分脚本，以便在不受部署容器配置影响的情况下进行调试。

有关在部署到 Azure 之前在本地调试联机终结点的详细信息，请参阅联机终结点调试。

在本地部署模型

首先创建一个终结点。 （可选）对于本地终结点，可以跳过此步骤并直接创建部署（下一步骤），这继而将创建所需的元数据。 在本地部署模型对于开发和测试目的很有用。

az ml online-endpoint create --local -n $ENDPOINT_NAME -f endpoints/online/managed/sample/endpoint.yml

现在，在终结点下面创建一个名为 blue 的部署。

az ml online-deployment create --local -n blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml

--local 标志指示 CLI 在 Docker 环境中部署终结点。

提示

使用 Visual Studio Code 在本地测试和调试终结点。 有关详细信息，请参阅在 Visual Studio Code 中以本地方式调试联机终结点。

验证本地部署是否成功

检查部署状态，查看模型是否已部署且未出错：

az ml online-endpoint show -n $ENDPOINT_NAME --local

输出应类似于以下 JSON。 provisioning_state 为 Succeeded。

{
  "auth_mode": "key",
  "location": "local",
  "name": "docs-endpoint",
  "properties": {},
  "provisioning_state": "Succeeded",
  "scoring_uri": "http://localhost:49158/score",
  "tags": {},
  "traffic": {}
}

下表包含 provisioning_state 的可能值：

值 说明
Creating 正在创建资源。
更新 正在更新资源。
正在删除 正在删除此资源。
成功 创建/更新操作成功。
已失败 创建/更新/删除操作失败。

调用本地终结点以使用模型为数据评分

使用 invoke 命令并传递 JSON 文件中存储的查询参数，调用终结点来为模型评分：

az ml online-endpoint invoke --local --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json

如果要使用 REST 客户端（例如 curl），必须具有评分 URI。 如要获取评分 URI，需要运行 az ml online-endpoint show --local -n $ENDPOINT_NAME。 在返回的数据中，找到 scoring_uri 属性。

在日志中查看 invoke 操作的输出

在示例 score.py 文件中，run() 方法将一些输出记录到控制台。

可以使用 get-logs 命令查看此输出：

az ml online-deployment get-logs --local -n blue --endpoint $ENDPOINT_NAME

将联机终结点部署到 Azure

接下来，将联机终结点部署到 Azure。 作为生产环境的最佳做法，建议你注册将在部署中使用的模型和环境。

注册模型和环境

建议在部署到 Azure 之前注册模型和环境，以便在部署期间指定它们的注册名称和版本。 注册资产就可以重复使用资产，而无需在每次创建部署时上传它们，从而提高可重复性和可追溯性。

注意

与部署到 Azure 不同，本地部署不支持使用注册的模型和环境。 相反，本地部署使用本地模型文件并使用仅具有本地文件的环境。 若要部署到 Azure，可以使用本地或注册资产（模型和环境）。 在本文的这一小节中，我们使用注册资产部署到 Azure，但你也可以选择使用本地资产。 有关上传本地文件以用于本地部署的部署配置示例，请参阅配置部署。

若要注册模型和环境，请使用窗体 model: azureml:my-model:1 或 environment: azureml:my-env:1。 若要执行注册，可以将 model 和 environment 的 YAML 定义提取到单独的 YAML 文件中，并使用命令 az ml model create 和 az ml environment create。 若要详细了解这些命令，请运行 az ml model create -h 和 az ml environment create -h。

  1. 为模型创建 YAML 定义：

    $schema: https://azuremlschemas.azureedge.net/latest/model.schema.json
name: my-model
path: ../../model-1/model/

  2. 注册模型：

    az ml model create -n my-model -v 1 -f ./model.yaml

  3. 为环境创建 YAML 定义：

    $schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json
name: my-env
image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
conda_file: ../../model-1/environment/conda.yaml

  4. 注册环境：

    az ml environment create -n my-env -v 1 -f ./environment.yaml

有关将模型注册为资产的详细信息，请参阅使用 CLI 在机器学习中将模型注册为资产。 有关创建环境的详细信息，请参阅使用 CLI 和 SDK (v2) 管理 Azure 机器学习环境。

配置使用注册资产的部署

部署配置使用要部署的注册模型和注册环境。

在部署定义中使用注册资产（模型和环境）。 以下代码片段显示了 endpoints/online/managed/sample/blue-deployment-with-registered-assets.yml 文件，其中包含配置部署所需的所有输入：

blue-deployment-with-registered-assets.yml

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-endpoint
model: azureml:my-model:1
code_configuration:
  code: ../../model-1/onlinescoring/
  scoring_script: score.py
environment: azureml:my-env:1
instance_type: Standard_DS3_v2
instance_count: 1

使用不同的 CPU 和 GPU 实例类型及映像

可以在部署定义中为本地部署和部署到 Azure 指定 CPU 或 GPU 实例类型和映像。

blue-deployment-with-registered-assets.yml 文件中的部署定义使用通用类型 Standard_DS3_v2 实例和非 GPU Docker 映像 mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest。 对于 GPU 计算，应选择 GPU 计算类型 SKU 和 GPU Docker 映像。

可以在托管联机终结点支持的 VM SKU 中查看支持的常规用途类型和 GPU 实例类型。 有关 Azure 机器学习 CPU 和 GPU 基础映像的列表，请参阅 Azure 机器学习基础映像。

注意

若要使用 Kubernetes 而不是托管终结点作为计算目标，请参阅 Kubernetes 计算目标简介。

接下来，将联机终结点部署到 Azure。

“部署到 Azure”

  1. 在 Azure 云中创建终结点。

     az ml online-endpoint create --name $ENDPOINT_NAME -f endpoints/online/managed/sample/endpoint.yml

  2. 在终结点下面创建一个名为 blue 的部署。

    az ml online-deployment create -name blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment-with-registered-assets.yml --all-traffic

    创建此项部署最多可能需要约 15 分钟，具体取决于是否为首次构建基础环境或映像。 使用相同环境的后续部署将更快完成处理。

    提示

    • 如果你不希望阻塞 CLI 控制台，可将 --no-wait 标志添加到命令中。 但是，此选项会停止以交互方式显示部署状态。

    重要

    用于创建部署的代码 az ml online-deployment create 中的 --all-traffic 标志会将 100% 的终结点流量分配给新创建的蓝色部署。 尽管这对开发和测试非常有用，但对于生产，你可能想要通过显式命令路由到新部署的流量。 例如 az ml online-endpoint update -n $ENDPOINT_NAME --traffic "blue=100"。

若要调试部署中的错误，请参阅对联机终结点部署进行故障排除。

检查终结点的状态

  1. 对于终结点和部署，使用 show 命令以显示 provisioning_state 中的信息：

     az ml online-endpoint show -n $ENDPOINT_NAME

  2. 使用 list 命令以表格格式列出工作区中的所有终结点：

    az ml online-endpoint list --output table

检查联机部署的状态

检查日志，查看模型是否已部署且未出错。

  1. 若要查看容器的日志输出，请使用以下 CLI 命令：

     az ml online-deployment get-logs --name blue --endpoint $ENDPOINT_NAME

    默认情况下，日志是从推理服务器容器拉取的。 若要查看存储初始化表达式容器中的日志，请添加 --container storage-initializer 标志。 有关部署日志的更多信息，请参阅获取容器日志。

调用终结点，以使用模型为数据评分

  1. 使用 invoke 命令或你选择的 REST 客户端来调用终结点并为一些数据评分：

     az ml online-endpoint invoke --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json

  2. 获取用于向终结点进行身份验证的密钥：

    提示

    你可以对哪些 Microsoft Entra 安全主体能够获取身份验证密钥进行控制，方法是将其分配到一个允许 Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/action 和 Microsoft.MachineLearningServices/workspaces/onlineEndpoints/listkeys/action 的自定义角色。 有关管理工作区授权的详细信息，请参阅“管理对 Azure 机器学习的访问权限”。

     ENDPOINT_KEY=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -o tsv --query primaryKey)
 SCORING_URI=$(az ml online-endpoint show -n $ENDPOINT_NAME -o tsv --query scoring_uri)

 curl --request POST "$SCORING_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --data @endpoints/online/model-1/sample-request.json

  3. 使用 curl 对数据进行评分。

     SCORING_URI=$(az ml online-endpoint show -n $ENDPOINT_NAME -o tsv --query scoring_uri)

 curl --request POST "$SCORING_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --data @endpoints/online/model-1/sample-request.json

    请注意，使用 show 和 get-credentials 命令来获取身份验证凭据。 另请注意，使用 --query 标志来筛选特性，以便仅显示所需的特性。 若要详细了解 --query 标志，请参阅查询 Azure CLI 命令输出。

  4. 若要查看调用日志，请再次运行 get-logs。

（可选）更新部署

如果你要更新代码、模型或环境，请更新 YAML 文件，然后运行 az ml online-endpoint update 命令。

注意

如果你在单个 update 命令中更新实例计数（以缩放你的部署）和其他模型设置（例如代码、模型或环境），则首先将执行缩放操作，然后将应用其他更新。 在生产环境中单独执行这些操作是一个很好的做法。

若要了解 update 的工作原理，请执行以下操作：

  1. 打开 online/model-1/onlinescoring/score.py 文件。

  2. 更改 init() 函数的最后一行：在 logging.info("Init complete") 后面，添加 logging.info("Updated successfully")。

  3. 保存文件。

  4. 运行以下命令：

    az ml online-deployment update -n blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment-with-registered-assets.yml

    注意

    使用 YAML 进行更新是声明性的。 也就是说，YAML 中的更改反映在基础资源 Azure 资源管理器资源（终结点和部署）中。 声明性方法有助于 GitOps：对终结点和部署的所有更改都将通过 YAML 进行（甚至包括 instance_count）。

    提示

    • 可以将泛型更新参数（例如 --set 参数）与 CLI update 命令一起使用，以替代 YAML 中的属性或设置特定属性而不在 YAML 文件中传递它们。 在开发和测试方案中，为单个特性使用 --set，这种做法特别有用。 例如，若要纵向扩展第一个部署的 instance_count 值，可以使用标志 --set instance_count=2。 但是，由于 YAML 未更新，此方法对 GitOps 没有帮助。
    • 指定 YAML 文件不是必需的。 例如，如果要测试给定部署的不同并发设置，可以尝试类似 az ml online-deployment update -n blue -e my-endpoint --set request_settings.max_concurrent_requests_per_instance=4 environment_variables.WORKER_COUNT=4 的操作。 这将保留所有现有配置，但仅更新指定的参数。

  5. 由于修改了在创建或更新终结点时运行的 init() 函数，因此日志中会包含消息 Updated successfully。 运行以下命令检索日志：

    az ml online-deployment get-logs --name blue --endpoint $ENDPOINT_NAME

update 命令也适用于本地部署。 将同一个 az ml online-deployment update 命令与标志 --local 配合使用。

注意

本部分中的部署更新是就地滚动更新的示例。

  • 对于托管联机终结点，部署将更新为一次更新 20% 的节点的新配置。 也就是说，如果部署有 10 个节点，则一次将更新 2 个节点。
  • 对于 Kubernetes 联机终结点，系统将使用新配置以迭代方式创建新的部署实例，并删除旧部署实例。
  • 对于生产用途，应考虑蓝绿部署，它为更新 Web 服务提供了更安全的替代方法。

（可选）配置自动缩放

自动缩放会自动运行适量的资源来处理应用程序的负载。 托管联机终结点支持通过与 Azure Monitor 自动缩放功能的集成进行自动缩放。 要配置自动缩放，请参阅如何自动缩放联机终结点。

（可选）使用 Azure Monitor 监视 SLA

若要查看指标并根据 SLA 设置警报，请完成监视联机终结点中所述的步骤。

（可选）与 Log Analytics 集成

CLI 的 get-logs 命令或 SDK 的 get_logs 方法只提供自动选择的实例最近发出的几百行日志。 但是，Log Analytics 提供一种用于持久存储和分析日志的方式。 有关使用日志记录的详细信息，请参阅监视联机终结点。

删除终结点和部署

删除终结点及其所有基础部署：

az ml online-endpoint delete --name $ENDPOINT_NAME --yes --no-wait

相关内容