閱讀英文

共用方式為

安全推出用于实时推理的新部署

适用范围:Azure CLI ml 扩展 v2(最新版)Python SDK azure-ai-ml v2(最新版)

本文介绍如何在生产环境中部署新版本的机器学习模型,而不会造成任何中断。 使用蓝绿部署策略(也称为安全推出策略)将新版本的 Web 服务引入生产环境。 使用此策略时,可以在完全推出 Web 服务之前,将新版本的 Web 服务推广到一小部分用户或请求。

本文假定你使用联机终结点或用于联机(实时)推理的终结点。 有两种类型的联机终结点:托管联机终结点和 Kubernetes 联机终结点。 有关终结点的详细信息以及终结点类型之间的差异,请参阅 托管联机终结点与 Kubernetes 联机终结点

本文使用托管联机终结点进行部署。 但它还包括注释,说明如何利用 Kubernetes 终结点而不是托管联机终结点。

在本文中,你将了解如何:

  • 定义一个在线端点,通过名为 blue 的部署来服务模型的第一个版本。
  • 扩展blue部署,使其能够处理更多请求。
  • 将第二个版本的模型(称为 green 部署)部署到终结点,但不向该部署发送实时流量。
  • 在隔离环境中测试 green 部署。
  • 将一部分实时流量镜像到 green 部署以验证部署。
  • 将一小部分实时流量发送到 green 部署。
  • 将所有实时流量发送到 green 部署。
  • 删除未使用的 blue 部署。

先决条件

  • Azure CLIml Azure CLI 的扩展,已安装并配置。 有关详细信息,请参阅安装和设置 CLI (v2)。

  • Bash shell 或其他兼容的 shell,例如 Linux 系统中的 shell 或 Windows 的 Linux 子系统。 本文中的 Azure CLI 示例假定你使用这种类型的 shell。

  • Azure 机器学习工作区。 有关创建工作区的说明,请参阅 “设置”。

  • 至少具有以下 Azure 基于角色的访问控制(Azure RBAC)角色之一的用户帐户:

    • Azure 机器学习工作区的所有者角色
    • Azure 机器学习工作区的贡献者角色
    • 具有 Microsoft.MachineLearningServices/workspaces/onlineEndpoints/* 权限的自定义角色

    有关详细信息,请参阅管理对 Azure 机器学习工作区的访问

  • (可选)在本地安装并运行 Docker 引擎。 强烈建议使用此先决条件。 您需要它来在本地部署模型,它还有助于调试。

准备你的系统

设置环境变量。

可以将默认值配置为与 Azure CLI 一起使用。 若要避免多次传入订阅、工作区和资源组的值,请运行以下代码:

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

克隆示例存储库

若要按照本文的说明进行操作,请先克隆示例存储库 (azureml-examples)。 然后转到存储库的 cli/ 目录:

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

提示

使用 --depth 1 仅克隆最新提交到目录,这将减少操作完成所需的时间。

本教程中的命令位于 cli 目录中的 deploy-safe-rollout-online-endpoints.sh 文件中,YAML 配置文件位于 endpoints/online/managed/sample/ 子目录中。

注意

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

定义终结点和部署

联机终结点用于联机(实时)推理。 联机终结点包含已准备好从客户端接收数据并可实时发回响应的部署。

定义终结点

下表列出了定义终结点时要指定的关键属性。

属性 必需还是可选 描述
名称 必选 终结点的名称。 它在其 Azure 区域中必须是唯一的。 有关命名规则的详细信息,请参阅 Azure 机器学习联机终结点和批处理终结点
身份验证模式 可选 终结点的身份验证方法。 可以在基于密钥的身份验证 key和基于 Azure 机器学习令牌的身份验证 aml_token之间进行选择。 密钥不会过期,但令牌会过期。 有关身份验证的详细信息,请参阅 对联机终结点的客户端进行身份验证
描述 可选 终结点的说明。
标记 可选 终结点的标记字典。
交通 可选 有关如何跨部署路由流量的规则。 您将流量表示为键值对形式的字典,其中键代表部署名称,值代表该部署流量的百分比。 仅当终结点下的部署创建后,才能设置流量。 创建部署后,还可以更新联机终结点的流量。 有关如何使用镜像流量的详细信息,请参阅 将少量实时流量分配给新部署
镜像流量 可选 要镜像到部署的实时流量的百分比。 有关如何使用镜像流量的详细信息,请参阅 使用镜像流量测试部署

若要查看可以在创建终结点时指定的属性的完整列表,请参阅 CLI (v2) 联机终结点 YAML 架构。 有关适用于 Python 的 Azure 机器学习 SDK 版本 2,请参阅 ManagedOnlineEndpoint 类

定义部署

部署是托管执行实际推理的模型所需的一组资源。 下表描述了定义部署时要指定的关键属性。

属性 必需还是可选 描述
名称 必选 部署的名称。
终结点名称 必选 用于创建部署的终结点名称。
型号 可选 要用于部署的模型。 此值可以是对工作区中现有版本受控模型的引用,也可以是对内联模型规范的引用。 在本文的示例中, scikit-learn 模型确实会回归。
代码路径 可选 本地开发环境中文件夹的路径,其中包含用于评分模型的所有 Python 源代码。 可以使用嵌套目录和包。
评分脚本 可选 根据给定输入请求执行模型的 Python 代码。 此值可以是源代码文件夹中评分文件的相对路径。
评分脚本接收提交到已部署的 Web 服务的数据,并将此数据传递给模型。 然后,该脚本执行模型并将其响应返回给客户端。 评分脚本特定于你的模型,必须理解模型期望作为输入和作为输出返回的数据。
本文的示例使用 score.py 文件。 此 Python 代码必须具有 init 函数和 run 函数。 init在创建或更新模型后调用该函数。 例如,可以使用它在内存中缓存模型。 每次调用终结点时,都将调用 run 函数来执行实际评分和预测。
环境 必选 用于承载模型和代码的环境。 此值可以是对工作区中现有版本受控环境的引用,也可以是对内联环境规范的引用。 环境可以是具有 Conda 依赖项、Dockerfile 或已注册环境的 Docker 映像。
实例类型 必选 要用于部署的虚拟机大小。 有关支持的大小列表,请参阅托管联机终结点 SKU 列表
实例计数 必选 用于部署的实例数。 您根据预期的工作负荷来确定价值。 为了获得高可用性,建议至少使用三个实例。 Azure 机器学习为执行升级保留额外 20%。 有关详细信息,请参阅 Azure 机器学习联机终结点和批处理终结点

若要查看可以在创建部署时指定的属性的完整列表,请参阅 CLI (v2) 托管联机部署 YAML 架构。 有关 Python SDK 版本 2,请参阅 ManagedOnlineDeployment 类

创建联机终结点

首先设置终结点名称,然后对其进行配置。 在本文中,将使用 endpoints/online/managed/sample/endpoint.yml 文件来配置终结点。 该文件包含以下行:

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

下表描述了终结点 YAML 格式使用的密钥。 若要了解如何指定这些属性,请参阅 CLI (v2) 联机终结点 YAML 架构。 有关与托管联机终结点相关的限制的信息,请参阅 Azure 机器学习联机终结点和批处理终结点

密钥 描述
$schema (可选)YAML 架构。 若要查看 YAML 文件中的所有可用选项,可以在浏览器中查看上述代码块中的架构。
name 终结点的名称。
auth_mode 身份验证模式。 使用 key 可执行基于密钥的身份验证。 使用 aml_token 可执行基于 Azure 机器学习令牌的身份验证。 若要获取最新的令牌,请使用 az ml online-endpoint get-credentials 命令。

若要创建联机终结点,请执行以下操作:

  1. 通过运行以下 Unix 命令设置终结点名称。 将 YOUR_ENDPOINT_NAME 替换为唯一名称。

    export ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"
    

    重要

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

  2. 通过运行以下代码在云中创建终结点。 此代码使用endpoint.yml文件配置终结点:

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

创建 blue 部署

可以使用 endpoints/online/managed/sample/blue-deployment.yml 文件来配置名为 blue 的部署的关键元素。 该文件包含以下行:

$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 文件为终结点创建 blue 部署,请运行以下命令:

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

重要

--all-traffic 命令中,az ml online-deployment create 标志将 100% 的端点流量分配给新创建的 blue 部署。

在 blue-deployment.yaml 文件中,行 path 指定从何处上传文件。 Azure 机器学习 CLI 使用此信息上传文件并注册模型和环境。 作为生产最佳做法,应注册模型和环境,并在 YAML 代码中单独指定已注册的名称和版本。 使用模型的格式 model: azureml:<model-name>:<model-version> ,例如 model: azureml:my-model:1。 对于环境,请使用格式 environment: azureml:<environment-name>:<environment-version>,例如 environment: azureml:my-env:1

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

有关将模型注册为资产的详细信息,请参阅 使用 Azure CLI 或 Python SDK 注册模型。 有关创建环境的详细信息,请参阅 “创建自定义环境”。

确认现有部署

确认现有部署的一种方法是调用终结点,以便它可以就给定输入请求为你的模型评分。 通过 Azure CLI 或 Python SDK 调用终结点时,可以选择指定要接收传入流量的部署的名称。

注意

与 Azure CLI 或 Python SDK 不同,Azure 机器学习工作室要求在调用终结点时指定部署。

使用部署名称调用终结点

调用终结点时,可以指定要接收流量的部署的名称。 在这种情况下,Azure 机器学习会将终结点流量直接路由到指定的部署并返回其输出。 可以使用 --deployment-nameAzure 机器学习 CLI v2 的选项,也可以使用 deployment_namePython SDK v2 的选项来指定部署。

在不指定部署的情况下调用终结点

如果在未指定要接收流量的部署的情况下调用终结点,Azure 机器学习会根据流量控制设置将终结点的传入流量路由到终结点中的部署。

流量控制设置会将指定百分比的传入流量分配给终结点中的各个部署。 例如,如果流量规则指定终结点中的特定部署应接收 40% 时间的传入流量,Azure 机器学习会将 40% 的终结点流量路由到该部署。

若要查看现有终结点和部署的状态,请运行以下命令:

az ml online-endpoint show --name $ENDPOINT_NAME 

az ml online-deployment show --name blue --endpoint $ENDPOINT_NAME 

输出列出了有关 $ENDPOINT_NAME 终结点和 blue 部署的信息。

使用示例数据测试终结点

可以使用命令调用终结点 invoke 。 以下命令使用 sample-request.json JSON 文件发送示例请求:

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

扩展现有部署以处理更多流量

在按使用联机终结点部署机器学习模型并为其评分所述进行部署时,将 instance_count 值设置为部署 YAML 文件中的 1。 可以使用 update 命令进行扩展:

az ml online-deployment update --name blue --endpoint-name $ENDPOINT_NAME --set instance_count=2

注意

在上一个命令中, --set 该选项将替代部署配置。 你也可以更新 YAML 文件,并使用 update 选项将它作为输入传递给 --file 命令。

部署新模型,但不向其发送流量

创建名为 green 的新部署:

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

因为没有显式地为 green 部署分配任何流量,所以它没有分配任何流量。 可以使用以下命令验证事实:

az ml online-endpoint show -n $ENDPOINT_NAME --query traffic

测试新部署

虽然 green 部署分配了 0% 的流量,但可以使用 --deployment 选项直接调用:

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

如果要使用 REST 客户端直接调用部署而不经历流量规则处理过程,请设置以下 HTTP 头:azureml-model-deployment: <deployment-name>。 以下代码使用客户端进行 URL (cURL) 直接调用部署。 可以在 Unix 或适用于 Linux 的 Windows 子系统(WSL)环境中运行代码。 有关如何检索 $ENDPOINT_KEY 值的说明,请参阅 获取数据平面操作的密钥或令牌

# get the scoring uri
SCORING_URI=$(az ml online-endpoint show -n $ENDPOINT_NAME -o tsv --query scoring_uri)
# use curl to invoke the endpoint
curl --request POST "$SCORING_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --header "azureml-model-deployment: green" --data @endpoints/online/model-2/sample-request.json

使用镜像流量测试部署

测试 green 部署后,可以将一定百分比的实时流量复制并发送到 green 部署上,以将其镜像到终结点。 流量镜像(也称为影子复制)不会更改返回给客户端的结果,请求仍然 100% 流向 blue 部署。 流量的镜像百分比将被复制并提交到 green 部署,以便可以收集指标和日志记录,而不会影响客户端。

如果要验证新部署而不影响客户端,则可使用镜像。 例如,可以使用镜像来检查延迟是否在可接受的范围内,或者检查是否存在 HTTP 错误。 使用流量镜像或阴影测试新部署也称为影子测试。 在这种情况下,接收镜像流量的 green 部署也可以称为 影子部署

镜像具有以下限制:

  • Azure 机器学习 CLI 2.4.0 及更高版本以及 Python SDK 版本 1.0.0 及更高版本支持镜像。 如果使用旧版的 Azure 机器学习 CLI 或 Python SDK 更新终结点,则会丢失镜像流量设置。
  • Kubernetes 联机终结点目前不支持镜像。
  • 只能将流量镜像到终结点中的一个部署。
  • 可以镜像的最大流量百分比为 50%。 此上限限制 对终结点带宽配额的影响,其默认值为 5 MBps。 如果超出分配的配额,则终结点带宽会受到限制。 有关监视带宽限制的信息,请参阅 带宽限制

另请注意以下行为:

  • 可以将部署配置为仅接收实时流量或镜像流量,而不是同时接收这两者。
  • 调用终结点时,可以指定其任何部署的名称(甚至是影子部署)以返回预测。
  • 调用终结点并指定用于接收传入流量的部署名称时,Azure 机器学习不会将流量镜像到影子部署。 如果未指定部署,Azure 机器学习会将发送到终结点的流量镜像到影子部署。

即使将 green 部署设置为接收 10% 的镜像流量,客户端依然仅接收来自 blue 部署的预测。

显示流量流经终结点的示意图。所有流量都流向蓝色部署,其中 10% 的流量被复制到绿色部署。

使用以下命令镜像 10% 的流量并将其发送到 green 部署:

az ml online-endpoint update --name $ENDPOINT_NAME --mirror-traffic "green=10"

可以通过多次调用终结点来测试镜像流量,而无需指定用于接收传入流量的部署:

for i in {1..20} ; do
    az ml online-endpoint invoke --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json
done

您可以通过检查部署中的日志来确认指定百分比的流量是否已发送到green部署。

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

测试后,可以将镜像流量设置为零以禁用镜像:

az ml online-endpoint update --name $ENDPOINT_NAME --mirror-traffic "green=0"

将一小部分实时流量分配给新部署

测试 green 部署后,为其分配一小部分流量:

测试 green 部署后,为其分配一小部分流量:

az ml online-endpoint update --name $ENDPOINT_NAME --traffic "blue=90 green=10"

提示

总流量百分比必须是 0% 才能禁用流量,或 100% 才能启用流量。

部署 green 现在接收 10% 的实时总流量。 客户端从 bluegreen 部署接收预测。

显示流量流经终结点的关系图。blue 部署接收 90% 的流量,green 部署为 10%。

将所有流量发送到新部署

green 部署完全满意后,将所有流量切换至该部署。

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

az ml online-endpoint update --name $ENDPOINT_NAME --traffic "blue=0 green=100"

删除旧部署

使用以下步骤从托管联机终结点中删除单个部署。 删除单个部署不会影响托管联机终结点中的其他部署:

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

删除终结点和部署

如果不打算使用终结点和部署,则应该删除它们。 删除终结点时,也会删除其所有基础部署。

如果不打算使用终结点和部署,则应该删除它们。 删除终结点时,你还会删除其所有基础部署。

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