将流部署到联机终结点以通过 CLI 进行实时推理

项目
09/13/2024

在本文中，你将了解如何将流部署到托管联机终结点或 Kubernetes 联机终结点，以便通过 Azure 机器学习 v2 CLI 进行实时推理。

在开始之前，请确保你已正确测试你的流，并确信它已准备好部署到生产环境。要详细了解如何测试流，请参阅测试流。测试了你的流后，你将了解如何创建托管联机终结点和部署，以及如何使用该终结点进行实时推理。

本文介绍如何使用 CLI 体验。
本文未涉及 Python SDK。请改为参阅 GitHub 示例笔记本。要使用 Python SDK，你必须具有适用于 Azure 机器学习的 Python SDK v2。要了解更多，请参阅安装适用于 Azure 机器学习的 Python SDK v2。

重要

本文中标记了“（预览版）”的项目目前为公共预览版。该预览版在提供时没有附带服务级别协议，建议不要将其用于生产工作负载。某些功能可能不受支持或者受限。有关详细信息，请参阅适用于 Azure 预览版的补充使用条款。

先决条件

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

注意

托管联机终结点仅支持托管虚拟网络。如果你的工作区位于自定义 vnet 中，则可以部署到 Kubernetes 联机终结点，或部署到其他平台（例如 Docker）。

用于部署的虚拟机配额分配

对于托管联机终结点，Azure 机器学习将保留 20% 的计算资源用于执行升级。因此，如果在部署中请求给定数量的实例，则必须为 ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU 提供可用配额以避免出现错误。例如，如果你在部署中请求 Standard_DS3_v2 VM（带有四个内核）的 10 个实例，则你应该具有 48 个内核（12 个四核实例）的配额。若要查看使用情况和请求增加配额，请参阅在 Azure 门户中查看使用情况和配额。

将流备好以进行部署

每个流将会有一个文件夹，其中包含流的代码/提示、定义和其他工件。如果你已使用 UI 开发流，则可以从流详细信息页下载流文件夹。如果你已使用 CLI 或 SDK 开发流，则你应已有流文件夹。

本文将使用示例流“基本聊天”作为部署到 Azure 机器学习托管联机终结点的示例。

重要

如果你已在流中使用 additional_includes，则需要先使用 pf flow build --source <path-to-flow> --output <output-path> --format docker 获取流文件夹的解析版本。

设置默认工作区

使用以下命令设置 CLI 的默认工作区和资源组。

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

将流注册为模型（可选）

在联机部署中，你可以引用已注册的模型，也可以内联指定模型路径（上传模型文件的位置）。建议注册模型并在部署定义中指定模型名称和版本。使用 model:<model_name>:<version> 格式。

下面是聊天流的模型定义示例。

注意

如果流不是聊天流，则无需添加这些 properties。

$schema: https://azuremlschemas.azureedge.net/latest/model.schema.json
name: basic-chat-model
path: ../../../../examples/flows/chat/basic-chat
description: register basic chat flow folder as a custom model
properties:
  # In AuzreML studio UI, endpoint detail UI Test tab needs this property to know it's from prompt flow
  azureml.promptflow.source_flow_id: basic-chat
  
  # Following are properties only for chat flow 
  # endpoint detail UI Test tab needs this property to know it's a chat flow
  azureml.promptflow.mode: chat
  # endpoint detail UI Test tab needs this property to know which is the input column for chat flow
  azureml.promptflow.chat_input: question
  # endpoint detail UI Test tab needs this property to know which is the output column for chat flow
  azureml.promptflow.chat_output: answer

使用 az ml model create --file model.yaml 将模型注册到工作区。

定义终结点

若要定义终结点，需要指定：

终结点名称：终结点的名称。在 Azure 区域中必须具有唯一性。有关命名规则的详细信息，请参阅终结点限制。
身份验证模式：终结点的身份验证方法。在基于密钥的身份验证和基于 Azure 机器学习令牌的身份验证之间进行选择。密钥不会过期，但令牌会过期。有关身份验证的详细信息，请参阅向联机终结点进行身份验证。（可选）可以向终结点添加说明和标记。
（可选）可以向终结点添加说明和标记。
如果要部署到附加到你的工作区的 Kubernetes 群集（已启用 AKS 或 Arc 的群集），可以将流部署为 Kubernetes 联机终结点。

下面是一个终结点定义示例，该示例默认使用系统分配的标识。

托管联机终结点
Kubernetes 联机终结点

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: basic-chat-endpoint
auth_mode: key
properties:
# this property only works for system-assigned identity.
# if the deploy user has access to connection secrets, 
# the endpoint system-assigned identity will be auto-assigned connection secrets reader role as well
  enforce_access_to_default_secret_stores: enabled

$schema: https://azuremlschemas.azureedge.net/latest/kubernetesOnlineEndpoint.schema.json
name: basic-chat-endpoint
compute: azureml:<Kubernetes compute name>
auth_mode: key

重要

密钥	说明
`$schema`	（可选）YAML 架构。若要查看 YAML 文件的所有可用选项，可在浏览器中查看上述代码片段中的架构。
`name`	终结点的名称。
`auth_mode`	使用 `key` 可执行基于密钥的身份验证。使用 `aml_token` 可执行基于 Azure 机器学习令牌的身份验证。若要获取最新的令牌，请使用 `az ml online-endpoint get-credentials` 命令。
`property: enforce_access_to_default_secret_stores`（预览版）	- 默认情况下，该终结点将使用系统分配的标识。此属性仅适用于系统分配的标识。 - 此属性意味着如果你具有连接机密读取者权限，则终结点的系统分配的标识将自动分配有工作区的 Azure 机器学习工作区连接机密读取者角色，以便终结点在执行推理时可以正确访问连接。 - 默认情况下禁用此属性。

如果创建 Kubernetes 联机终结点，则需要指定以下附加属性：

密钥	说明
`compute`	要向其部署终结点的 Kubernetes 计算目标。

有关终结点的更多配置，请参阅托管联机终结点架构。

使用用户分配的标识

默认情况下，当你创建联机终结点时，系统会自动为你生成一个系统分配的托管标识。还可以为终结点指定一个现有的用户分配的托管标识。

如果希望使用用户分配的标识，可以在 endpoint.yaml 中指定以下附加属性：

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

此外，还需要在 deployment.yaml 中的 environment_variables 下指定用户分配标识的 Client ID，如下所示。可以在 Azure 门户中托管标识的 Overview 中找到 Client ID。

environment_variables:
  AZURE_CLIENT_ID: <client_id_of_your_user_assigned_identity>

重要

你需要在创建终结点之前向用户分配的标识授予以下权限，以便它可以访问 Azure 资源来进行推理。详细了解如何向终结点标识授予权限。

作用域	角色	为什么需要它
Azure 机器学习工作区	Azure 机器学习工作区连接机密读取者角色或具有“Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action”权限的自定义角色	获取工作区连接
工作区容器注册表	ACR 拉取	拉取容器映像
工作区默认存储	存储 Blob 数据读取者	从存储加载模型
（可选）Azure 机器学习工作区	工作区指标编写器	部署终结点后，如果要监视与终结点相关的指标（如 CPU/GPU/磁盘/内存利用率），则需要向标识授予此权限。

定义部署

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

下面是部署定义示例，其中 model 部分引用了注册的流模型。还可以内联方式指定流模型路径。

托管联机终结点
Kubernetes 联机终结点

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: basic-chat-endpoint
model: azureml:basic-chat-model:1
  # You can also specify model files path inline
  # path: examples/flows/chat/basic-chat
environment: 
  image: mcr.microsoft.com/azureml/promptflow/promptflow-runtime:latest
  # inference config is used to build a serving container for online deployments
  inference_config:
    liveness_route:
      path: /health
      port: 8080
    readiness_route:
      path: /health
      port: 8080
    scoring_route:
      path: /score
      port: 8080
instance_type: Standard_E16s_v3
instance_count: 1
environment_variables:
  # for pulling connections from workspace
  PRT_CONFIG_OVERRIDE: deployment.subscription_id=<subscription_id>,deployment.resource_group=<resource_group>,deployment.workspace_name=<workspace_name>,deployment.endpoint_name=<endpoint_name>,deployment.deployment_name=<deployment_name>

  # (Optional) When there are multiple fields in the response, using this env variable will filter the fields to expose in the response.
  # For example, if there are 2 flow outputs: "answer", "context", and I only want to have "answer" in the endpoint response, I can set this env variable to '["answer"]'.
  # If you don't set this environment, by default all flow outputs will be included in the endpoint response.
  # PROMPTFLOW_RESPONSE_INCLUDED_FIELDS: '["category", "evidence"]'

$schema: https://azuremlschemas.azureedge.net/latest/kubernetesOnlineDeployment.schema.json
name: blue
type: kubernetes
endpoint_name: basic-chat-endpoint
model: azureml:basic-chat-model:1
  # You can also specify model files path inline
  # path: examples/flows/chat/basic-chat
environment: 
  image: mcr.microsoft.com/azureml/promptflow/promptflow-runtime:latest
  # inference config is used to build a serving container for online deployments
  inference_config:
    liveness_route:
      path: /health
      port: 8080
    readiness_route:
      path: /health
      port: 8080
    scoring_route:
      path: /score
      port: 8080
instance_type: <kubernetes custom instance type>
instance_count: 1
environment_variables:

  # for pulling connections from workspace
  PRT_CONFIG_OVERRIDE: deployment.subscription_id=<subscription_id>,deployment.resource_group=<resource_group>,deployment.workspace_name=<workspace_name>,deployment.endpoint_name=<endpoint_name>,deployment.deployment_name=<deployment_name>

  # (Optional) When there are multiple fields in the response, using this env variable will filter the fields to expose in the response.
  # For example, if there are 2 flow outputs: "answer", "context", and I only want to have "answer" in the endpoint response, I can set this env variable to '["answer"]'.
  # If you don't set this environment, by default all flow outputs will be included in the endpoint response.
  # PROMPTFLOW_RESPONSE_INCLUDED_FIELDS: '["category", "evidence"]'

Attribute	描述
名称	部署的名称。
终结点名称	要在其下创建部署的终结点的名称。
型号	要用于部署的模型。此值可以是对工作区中现有版本受控模型的引用，也可以是对内联模型规范的引用。
环境	用于承载模型和代码的环境。该结构包含： - `image` - `inference_config`：用于为联机部署生成服务容器，包括 `liveness route`、`readiness_route`、`scoring_route`。
实例类型	用于部署的 VM 大小。有关支持的大小列表，请参阅托管联机终结点 SKU 列表。
实例计数	用于部署的实例数。请根据预期的工作负载确定值。为实现高可用性，建议将值至少设置为 `3`。我们保留额外的 20% 来执行升级。有关详细信息，请参阅联机终结点限制。
环境变量	需要为从流部署的终结点设置以下环境变量： -（必需）`PRT_CONFIG_OVERRIDE`：用于从工作区拉取连接 -（可选）`PROMPTFLOW_RESPONSE_INCLUDED_FIELDS:`：当响应中有多个字段时，使用此 env 变量将筛选要在响应中公开的字段。例如，如果有两个流输出："answer"、"context"，并且你只想终结点响应包含 "answer"，则可以将此 env 变量设置为 '["answer"]'。

重要

如果流文件夹中有一个 requirements.txt 文件，其中包含执行流所需的依赖项，则需要按照使用自定义环境步骤进行部署中的说明生成自定义环境（包括依赖项）。

如果创建 Kubernetes 联机部署，则需要指定以下附加属性：

Attribute	说明
类型	部署的类型。将值设置为 `kubernetes`。
实例类型	在 Kubernetes 群集中创建的用于部署的实例类型，表示部署的请求/上限计算资源。有关详细信息，请参阅创建和管理实例类型。

将联机终结点部署到 Azure

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

az ml online-endpoint create --file endpoint.yml

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

az ml online-deployment create --file blue-deployment.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"。

检查终结点和部署的状态

要检查终结点的状态，请运行以下代码：

az ml online-endpoint show -n basic-chat-endpoint

要检查部署的状态，请运行以下代码：

az ml online-deployment get-logs --name blue --endpoint basic-chat-endpoint

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

可以创建一个如下所示的 sample-request.json 文件：

{
  "question": "What is Azure Machine Learning?",
  "chat_history":  []
}

az ml online-endpoint invoke --name basic-chat-endpoint --request-file sample-request.json

还可以使用 HTTP 客户端调用它，例如使用curl：

ENDPOINT_KEY=<your-endpoint-key>
ENDPOINT_URI=<your-endpoint-uri>

curl --request POST "$ENDPOINT_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --data '{"question": "What is Azure Machine Learning?", "chat_history":  []}'

可从 Azure 机器学习工作区的“终结点”>“使用”>“基本使用信息”中获取终结点密钥和终结点 URI。

高级配置

使用与流开发不同的连接进行部署

你可能希望在部署期间替代流的连接。

例如，如果 flow.dag.yaml 文件使用名为 my_connection 的连接，则可通过添加部署 yaml 的环境变量来替代它，如下所示：

选项 1：替代连接名称

environment_variables:
  my_connection: <override_connection_name>

如果要替代连接的特定字段，可以通过添加命名模式为 <connection_name>_<field_name> 的环境变量来替代。例如，如果流使用名为 my_connection 的连接和名为 chat_deployment_name 的配置密钥，服务后端默认会尝试从环境变量“MY_CONNECTION_CHAT_DEPLOYMENT_NAME”中检索 chat_deployment_name。如果未设置环境变量，它将使用流定义中的原始值。

选项 2：通过引用资产进行替代

environment_variables:
  my_connection: ${{azureml://connections/<override_connection_name>}}

注意

只能引用同一工作区中的连接。

使用自定义环境进行部署

本部分介绍如何使用 Docker 生成上下文来指定部署环境（假设你了解 Docker 和 Azure 机器学习环境）。

在本地环境中，创建名为 image_build_with_reqirements 的文件夹并包含以下文件：
```
|--image_build_with_reqirements
|  |--requirements.txt
|  |--Dockerfile
```
- requirements.txt 应从流文件夹继承，该文件夹已用于跟踪流的依赖项。
- Dockerfile 内容如下所示：
```
FROM mcr.microsoft.com/azureml/promptflow/promptflow-runtime:latest
COPY ./requirements.txt .
RUN pip install -r requirements.txt
```

将部署定义 yaml 文件中的环境部分替换为以下内容：

environment: 
  build:
    path: image_build_with_reqirements
    dockerfile_path: Dockerfile
  # deploy prompt flow is BYOC, so we need to specify the inference config
  inference_config:
    liveness_route:
      path: /health
      port: 8080
    readiness_route:
      path: /health
      port: 8080
    scoring_route:
      path: /score
      port: 8080

使用 FastAPI 服务引擎（预览版）

默认情况下，提示流服务将使用 FLASK 服务引擎。从提示流 SDK 版本 1.10.0 开始，支持基于 FastAPI 的服务引擎。你可以通过指定环境变量 PROMPTFLOW_SERVING_ENGINE 来使用 fastapi 服务引擎。

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

为部署配置并发

将流部署到联机部署时，你需要为并发配置两个环境变量：PROMPTFLOW_WORKER_NUM 和 PROMPTFLOW_WORKER_THREADS。此外，你还需要设置 max_concurrent_requests_per_instance 参数。

下面是有关如何在 deployment.yaml 文件中进行配置的示例。

request_settings:
  max_concurrent_requests_per_instance: 10
environment_variables:
  PROMPTFLOW_WORKER_NUM: 4
  PROMPTFLOW_WORKER_THREADS: 1

PROMPTFLOW_WORKER_NUM：此参数确定将在一个容器中启动的工作进程（进程）的数目。默认值等于 CPU 核心数，最大值是 CPU 核心数的两倍。
PROMPTFLOW_WORKER_THREADS：此参数确定将在一个工作进程中启动的线程的数目。默认值为 1。

注意

将 PROMPTFLOW_WORKER_THREADS 设置为大于 1 的值时，请确保流代码是线程安全的。
max_concurrent_requests_per_instance：部署允许的每个实例的最大并发请求数。默认值为 10。

建议使用的 max_concurrent_requests_per_instance 值取决于你的请求时间：
- 如果请求时间大于 200 毫秒，请将 max_concurrent_requests_per_instance 设置为 PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS。
- 如果请求时间小于或等于 200 毫秒，请将 max_concurrent_requests_per_instance 设置为 (1.5-2) * PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS。这可以通过允许某些请求在服务器端排队来提高总吞吐量。
- 如果要发送跨区域请求，可以将阈值从 200 毫秒更改为 1 秒。

在优化上述参数时，你需要监视以下指标，以确保最佳性能和稳定性：

此部署的实例 CPU/内存利用率
非 200 响应（4xx、5xx）
- 如果收到 429 响应，这通常表示需要按照上述指南来重新优化并发设置，或者需要对部署进行缩放。

监视终结点

收集常规指标

你可以查看联机部署的常规指标（请求编号、请求延迟、网络字节数、CPU/GPU/磁盘/内存利用率等）。

在推理期间收集跟踪数据和系统指标

你还可以通过在部署 yaml 文件中添加属性 app_insights_enabled: true，在推理时间将跟踪数据和特定于提示流部署的指标（令牌消耗、流延迟等）收集到工作区链接的 Application Insights。详细了解提示流部署的跟踪和指标。

除了工作区链接的 Application Insights，还可以将特定于提示流的指标和跟踪指定给其他 Application Insights。你可以在部署 yaml 文件中指定环境变量，如下所示。可以在 Azure 门户的“概述”页面中找到 Application Insights 的连接字符串。

environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

注意

如果仅设置 app_insights_enabled: true 但工作区没有链接的 Application Insights，则部署不会失败，但不会收集任何数据。如果你同时指定 app_insights_enabled: true 和上述环境变量，则跟踪数据和指标将发送到工作区链接的 Application Insights。因此，如果你要指定不同的 Application Insights，只需保留环境变量即可。

常见错误

使用终结点时的上游请求超时问题

此类错误通常由超时引起。 request_timeout_ms 默认为 5000。最多可以指定为 5 分钟，即 300000 毫秒。下面的示例演示如何在部署 yaml 文件中指定请求超时。在此处了解有关部署架构的详细信息。

request_settings:
  request_timeout_ms: 300000

注意

300,000 毫秒超时仅适用于从提示流进行的托管联机部署。需要确保已为模型添加如下属性（部署 yaml 中的内联模型规范或独立的模型规范 yaml），以表明这是来自提示流的部署。

properties:
  # indicate a deployment from prompt flow
  azureml.promptflow.source_flow_id: <value>

后续步骤

详细了解托管联机终结点架构和托管联机部署架构。
详细了解如何在 UI 中测试终结点和监视终结点。
详细了解如何对托管联机终结点进行故障排除。
提示流部署故障排除。
改进了你的流后，如果希望通过安全推出策略部署改进的版本，请参阅联机终结点的安全推出。
详细了解如何将流部署到其他平台，例如本地开发服务、Docker 容器、Azure APP 服务等。

通过