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

适用于:Azure CLI ml 扩展 v2(当前版)

适用于:Python SDK azure-ai-ml v2(当前版本)

了解如何使用联机终结点部署模型,这样就不需要创建和管理底层基础结构。 首先在本地计算机上部署一个模型以调试任何错误,然后在 Azure 中部署并测试该模型。

你还将了解如何查看日志和监视服务级别协议 (SLA)。 你将从模型着手,最后会使用一个可缩放的 HTTPS/REST 终结点执行联机和实时评分。

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

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

本文档中的主要示例使用托管联机终结点进行部署。 若要改为使用 Kubernetes,请参阅本文档中与托管联机终结点的讨论相关的说明。

先决条件

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

  • Azure 基于角色的访问控制 (Azure RBAC) 用于授予对 Azure 机器学习中的操作的访问权限。 若要执行本文中的步骤,必须为用户帐户分配 Azure 机器学习工作区的所有者或参与者角色,或者分配一个允许 Microsoft.MachineLearningServices/workspaces/onlineEndpoints/* 的自定义角色。 有关详细信息,请参阅管理对 Azure 机器学习工作区的访问

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

    az account set --subscription <subscription ID>
    az configure --defaults workspace=<Azure Machine Learning workspace name> group=<resource group>
    
  • (可选)若要在本地部署,必须在本地计算机上安装 Docker 引擎。 强烈建议选择此选项,以便更轻松地调试问题。

重要

本文档中的示例假定在使用 Bash shell。 例如,从 Linux 系统或者适用于 Linux 的 Windows 子系统

准备你的系统

克隆示例存储库

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

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

提示

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

设置终结点名称

要设置你的终结点名称,请运行以下命令(将 YOUR_ENDPOINT_NAME 替换为唯一名称)。

若是 Unix,运行此命令:

export ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"

注意

Azure 区域中的终结点名称必须唯一。 例如,在 Azure chinaeast 区域中,只能有一个名为 my-endpoint 的终结点。

定义终结点和部署

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

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

注意

有关 YAML 的完整说明,请参阅联机终结点 YAML 参考

下表描述了 YAML 格式的终结点的参考资料。 若要了解如何指定这些属性,请参阅准备系统联机终结点 YAML 参考中的 YAML 示例。 有关托管终结点相关限制的信息,请参阅管理和提高 Azure 机器学习资源的配额

说明
$schema (可选)YAML 架构。 如要查看 YAML 文件的所有可用选项,可在浏览器中查看上述示例中的架构。
name 终结点的名称。 在 Azure 区域中必须具有唯一性。
命名规则在托管联机终结点限制下定义。
auth_mode 使用 key 可执行基于密钥的身份验证。 使用 aml_token 可执行基于 Azure 机器学习令牌的身份验证。 key 不会过期,但 aml_token 会过期。 (使用 az ml online-endpoint get-credentials 命令获取最新的令牌。)

该示例包含在联机终结点上部署模型所需的所有文件。 若要部署模型,必须具备:

  • 模型文件(或者已在工作区中注册的模型的名称和版本)。 本示例中有一个执行回归的 scikit-learn 模型。
  • 为模型评分所需的代码。 在这种情况下,我们会用到 score.py 文件。
  • 运行模型的环境。 正如你所见,环境可能是具有 Conda 依赖项的 Docker 映像,也可能是 Dockerfile。
  • 用于指定实例类型和缩放容量的设置。

以下代码片段显示了 endpoints/online/managed/sample/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.yml
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
instance_type: Standard_DS2_v2
instance_count: 1

下表描述了 deployment 的属性:

密钥 说明
name 部署的名称。
model 在此示例中,我们指定了内联模型属性:path。 将自动上传模型文件并使用自动生成的名称注册。 有关相关的最佳实践,请参阅下一节中的提示。
code_configuration.code.path 本地开发环境中的目录,其中包含用于为模型评分的所有 Python 源代码。 可以使用嵌套目录和包。
code_configuration.scoring_script 位于本地开发环境的 code_configuration.code.path 评分目录中的 Python 文件。 此 Python 代码必须具有 init() 函数和 run() 函数。 在创建或更新模型后将调用 init() 函数(例如,可以使用该函数在内存中缓存模型)。 每次调用终结点时,都将调用 run() 函数来执行实际评分和预测。
environment 包含用于承载模型和代码的环境的详细信息。 在此示例中,我们具有包含 path 的内联定义。 我们将为映像使用 environment.docker.image。 将在映像之上安装 conda_file 依赖项。 有关详细信息,请参阅下一节中的提示。
instance_type 用于承载部署实例的 VM SKU。 有关详细信息,请参阅托管联机终结点支持的 VM SKU
instance_count 部署中的实例数。 请根据预期的工作负载确定值。 为实现高可用性,建议至少将 instance_count 设置为 3。 我们保留额外的 20% 来执行升级。 有关详细信息,请参阅托管联机终结点配额

在部署期间,本地文件(如评分模型的 Python 源)是从开发环境上传的。

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

注意

使用 Kubernetes 而不是托管终结点作为计算目标:

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

本文中使用的所有命令(除了可选 SLA 监视和 Azure Log Analytics 集成)可以与托管终结点或 Kubernetes 终结点一起使用。

单独注册模型和环境

在此示例中,我们以内联方式指定 path(从何处上传文件)。 CLI 会自动上传文件并注册模型和环境。 适用于生产的最佳做法是注册模型和环境,并在 YAML 中指定已注册的名称和版本。 使用格式 model: azureml:my-model:1environment: azureml:my-env:1

若要执行注册,可以将 modelenvironment 的 YAML 定义提取到单独的 YAML 文件中,并使用命令 az ml model createaz ml environment create。 若要详细了解这些命令,请运行 az ml model create -haz ml environment create -h

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

上述 YAML 使用常规用途类型 (Standard_DS2_v2) 和非 GPU Docker 映像(请参阅 YAML 中的 image 特性)。 对于 GPU 计算,应选择 GPU 计算类型 SKU 和 GPU Docker 映像。

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

注意

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

使用多个模型

目前,在 YAML 中只能为每个部署指定一个模型。 如果你有多个模型,注册模型时,请将所有模型(作为文件或子目录)复制到用于注册的文件夹中。 在评分脚本中,使用环境变量 AZUREML_MODEL_DIR 获取模型根文件夹的路径。 保留基础目录结构。 有关将多个模型部署到一个部署的示例,请参阅将多个模型部署到一个部署

了解评分脚本

提示

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

如之前所述,code_configuration.scoring_script 中指定的脚本必须具有一个 init() 函数和一个 run() 函数。 此示例使用 score.py 文件

初始化或启动容器时,将调用函数 init()。 初始化通常在创建或更新部署后立即发生。 在此处编写逻辑以执行全局初始化操作,例如在内存中高速缓存模型(如本示例中的执行)。 每次调用终结点时,都将调用 run() 函数,该函数应执行实际的评分和预测。 在该示例中,我们将从 JSON 输入提取数据,调用模型的 predict() 方法,并返回结果。

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

为了节省调试时间,我们强烈建议在本地对终结点进行测试运行。 有关详细信息,请参阅在 Visual Studio Code 中以本地方式调试联机终结点

注意

重要

在本地部署终结点的目的是在部署到 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_stateSucceeded

{
  "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 属性。 本文档后面提供了基于 curl 的示例命令。

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

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

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

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

将联机终结点部署到 Azure

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

“部署到 Azure”

若要在云中创建终结点,请运行以下代码:

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

若要在终结点下创建名为 blue 的部署,请运行以下代码:

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

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

提示

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

重要

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

提示

检查终结点的状态

对于终结点和部署,show 命令包含 provisioning_status 中的信息:

az ml online-endpoint show -n $ENDPOINT_NAME

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

az ml online-endpoint list --output table

检查联机部署的状态

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

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

默认情况下,日志是从推理服务器拉取的。 若要查看存储初始值(将模型和代码等资产装载到容器)中的日志,请添加 --container storage-initializer 标志。

有关部署日志的更多信息,请参阅获取容器日志

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

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

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

以下示例显示了如何获取用于对终结点进行身份验证的密钥:

提示

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

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

接下来,使用 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

请注意,我们使用 showget-credentials 命令来获取身份验证凭据。 另请注意,我们使用 --query 标志来筛选特性,以便仅显示所需的特性。 可以在查询 Azure CLI 命令输出中详细了解 --query

若要查看调用日志,请再次运行 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.yml
    

    注意

    使用 YAML 进行更新是声明性的。 也就是说,YAML 中的更改反映在基础资源 Azure 资源管理器资源(终结点和部署)中。 声明性方法有助于 GitOps:对终结点和部署的所有更改都将通过 YAML 进行(甚至包括 instance_count)。 无需使用 YAML 即可使用 --set 标志进行更新。

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

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

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

提示

使用 update 命令时,可以使用 --setAzure CLI 中的参数来替代 YAML 中的特性,或者将该参数用于设置特定的特性,而无需传递 YAML 文件。 在开发和测试方案中,为单个特性使用 --set,这种做法特别有用。 例如,若要纵向扩展第一个部署的 instance_count 值,可以使用标志 --set instance_count=2。 但是,由于 YAML 未更新,此方法对 GitOps 没有帮助。

注意

以上是就地滚动更新的示例。

  • 对于托管的联机终结点,使用新配置更新同一部署,一次更新 20% 的节点,即如果部署有 10 个节点,一次将更新 2 个节点。
  • 对于 Kubernetes 联机终结点,系统将使用新配置以迭代方式创建新的部署实例,并删除旧部署实例。
  • 对于生产用途,你可能需要考虑蓝绿部署,蓝绿部署提供了更安全的替代方案。

(可选)配置自动缩放

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

(可选)使用 Azure Monitor 监视 SLA

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

(可选)与 Log Analytics 集成

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

如何在工作室中配置电子邮件

若要开始在作业、联机终结点或批处理终结点完成时或者在出现问题(失败、取消)的情况下接收电子邮件,请按照以下步骤操作:

  1. 在 Azure ML 工作室中,通过选择齿轮图标来转到设置。
  2. 选择“电子邮件通知”选项卡。
  3. 切换开关,为某个特定事件启用或禁用电子邮件通知。

屏幕截图显示 Azure ML Studio 在电子邮件通知选项卡上的设置。

删除终结点和部署

如果你将来不再使用该部署,应运行以下代码将其删除(这会删除终结点和所有基础部署):

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

后续步骤

下一步是尝试安全推出你的模型:

若要了解更多信息,请查看下列文章: