通过

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

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

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

联机终结点是用于实时推理的终结点。 有两种类型的联机终结点：托管联机终结点和 Kubernetes 联机终结点。 关于差异的更多信息，请参阅 托管在线端点与 Kubernetes 在线端点。

托管联机终结点有助于以统包方式部署机器学习模型。 托管的在线端点以可扩展、完全托管的方式在 Azure 平台上使用强大的 CPU 和 GPU 机器。 托管在线端点负责服务、扩展、安全和监控模型。 此帮助可让你免于设置和管理底层基础结构的开销。

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

先决条件

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

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

  • （可选）在本地部署时，您必须在自己的计算机上安装 Docker 引擎。 我们 强烈建议 使用此选项，这样可以更轻松地调试问题。

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

  • 或者，可以在有限的时间内使用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 存储库，然后切换到存储库的 azureml-examples/cli 目录：

git clone --depth 1 https://github.com/Azure/azureml-examples
cd azureml-examples/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区域中唯一的名称。 有关命名规则的详细信息，请参阅 终结点限制。

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 参考。 有关与托管终结点相关的限制的信息，请参阅 Azure 机器学习联机终结点和批处理终结点。

Key 说明
$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 文件，其中包含配置部署所需的所有输入：

$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. 使用 endpoint YAML 以 Kubernetes 为目标，而不是以管理的终结点 YAML 为目标。 需要编辑 YAML，将 compute 的值更改为注册的计算目标的名称。 可以使用此 deployment.yaml，其中包含适用于 Kubernetes 部署的其他属性。

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

了解评分脚本

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

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

此示例使用前面克隆或下载的存储库中的 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 Engine。 Docker 引擎通常在计算机启动时启动。 如果它不启动，可以对 Docker 引擎进行故障排除。

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

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

在本地部署模型

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

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 正在创建资源。
Updating 正在更新资源。
Deleting 正在删除此资源。
Succeeded 创建或更新操作成功。
Failed 创建、更新或删除操作失败。

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

使用 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 属性。

在日志中查看调用操作的输出

在示例 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 定义提取到endpoints/online/managed/sample 文件夹中的单独 YAML 文件中，并使用命令az ml model create和az ml environment create。 若要详细了解这些命令，请运行 az ml model create -h 和 az ml environment create -h。

  1. 为模型创建 YAML 定义。 将文件命名 为model.yml：

    $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 endpoints/online/managed/sample/model.yml

  3. 为环境创建 YAML 定义。 将文件命名 为environment.yml：

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

  4. 注册环境：

    az ml environment create -n my-env -v 1 -f endpoints/online/managed/sample/environment.yml

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

重要

为部署定义自定义环境时，请确保 azureml-inference-server-http 包包含在 conda 文件中。 此包对于推理服务器正常运行至关重要。 如果你不熟悉如何创建自己的自定义环境，请使用我们的特选环境之一，例如 minimal-py-inference （对于不使用 mlflow的自定义模型）或 mlflow-py-inference （用于使用 mlflow模型）。 可以在Azure 机器学习工作室实例的 Environments 选项卡上找到这些特选环境。 或者，可以使用专用的推理基础镜像，例如 mcr.microsoft.com/azureml/minimal-py312-inference:latest 来定制轻量级环境。

配置使用注册资产的部署

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

在部署定义中使用注册资产（模型和环境）。 以下代码片段显示了 endpoints/online/managed/sample/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 文件中的部署定义使用了通用型 实例和非 GPU Docker 映像 Standard_DS3_v2。mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu22.04:latest 对于 GPU 计算，请选择 GPU 计算类型版本和 GPU Docker 映像。

有关受支持的常规用途和 GPU 实例类型，请参阅 托管联机终结点 SKU 列表。 有关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 标志添加到命令中。 但是，此选项停止部署状态的交互式显示。

    用于创建部署的代码 --all-traffic 中的 az ml online-deployment create 标志会将 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

检查联机部署的状态

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

若要查看容器的日志输出，请使用以下 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 标志的详细信息，请参阅 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 中的更改反映在基础“资源管理器”资源（端点和部署）中。 声明性方法促进了 GitOps：所有对终结点和部署的更改（即使是 ）都通过 YAML 实现。

    可以使用 泛型更新参数（如 --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集成

get-logs CLI 的命令或 get_logs SDK 方法仅提供自动选择实例的最后几百行日志。 但是，Log Analytics提供了一种持久存储和分析日志的方法。 有关如何使用日志记录的详细信息，请参阅 “使用日志”。

删除终结点和部署

使用以下命令删除终结点及其所有基础部署：

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

相关内容

  • Last updated on