使用 CLI 将流部署到联机终结点进行实时推理

本文介绍如何将流部署到 托管联机终结点或 Kubernetes 联机终结点，以便与 Azure 机器学习 v2 CLI 实时推理配合使用。

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

• 本文介绍如何使用 CLI 体验。
• 本文未介绍Python SDK。 请查看 GitHub 上的示例笔记本。 若要使用 Python SDK，必须具有用于Azure 机器学习的 Python SDK v2。 若要了解详细信息，请参阅 安装 Python SDK v2 for Azure 机器学习。

先决条件

• Azure CLI以及针对Azure CLI的Azure 机器学习扩展。 有关详细信息，请参阅安装、设置和使用 CLI （v2）。
• Azure 机器学习工作区。 如果您没有，请使用快速入门：创建工作区资源文章中的步骤来创建一个。
• Azure基于角色的访问控制（Azure RBAC）用于授予对Azure 机器学习中操作的访问权限。 若要执行本文中的步骤，您的用户帐户必须被分配为Azure 机器学习工作区的所有者或贡献者角色，或者拥有允许“Microsoft.MachineLearningServices/workspaces/onlineEndpoints/”的自定义角色。 如果使用 Studio 创建或管理在线端点和部署，则需要来自资源组所有者的另一个权限“Microsoft.Resources/deployments/write”。 有关详细信息，请参阅 管理对 Azure 机器学习工作区的访问。

部署的虚拟机配额分配

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

准备好流以进行部署

每个流都有一个文件夹，其中包含流的代码/提示、定义和其他项目。 如果已使用 UI 开发流程，可以从流程详情页下载流程文件夹。 如果已使用 CLI 或 SDK 开发流，则应已拥有流文件夹。

本文使用示例流“basic-chat”作为示例部署到 Azure 机器学习托管在线终结点。

设置默认工作区

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

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

将流注册为模型（可选）

在联机部署中，可以引用已注册的模型，或直接在部署脚本或配置中指定模型路径（从何处上传模型文件）。 建议在部署定义中注册模型并指定模型名称和版本。 使用表单 model:<model_name>:<version>。

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

$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 联机终结点。

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

$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

如果创建 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>

定义部署

部署是托管执行实际推理的模型所需的一组资源。

下面是部署定义示例，其中 model 该部分引用已注册的流模型。 还可以直接指定流模型路径。

$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"]'

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

将在线终结点部署到 Microsoft Azure

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

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

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

az ml online-deployment create --file blue-deployment.yml --all-traffic

检查终结点和部署的状态

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

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 机器学习 工作区中的Endpoints>Consume>Basic consumption info中获取终结点密钥和终结点 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 机器学习 环境。

1. 在本地环境中，创建一个名为 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
     

2. 将部署定义 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 的服务引擎。 可以通过指定环境变量fastapi来使用PROMPTFLOW_SERVING_ENGINE服务引擎。

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_instancePROMPTFLOW_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 响应，这通常表示需要按照上述指南重新优化并发设置或缩放部署。
• Azure OpenAI 限制状态

监视终结点

收集常规指标

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

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

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

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

environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

常见错误

调用终结点时发生上游请求超时问题

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

request_settings:
  request_timeout_ms: 300000

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

后续步骤

• 详细了解 托管联机终结点架构 和 托管联机部署架构。
• 详细了解如何在 UI 中测试终结点 并 监视终结点。
• 详细了解如何对托管联机终结点进行故障排除。
• 提示流部署故障排除。
• 一旦您改进了流程，并希望使用安全的推出策略部署改进的版本，请参阅在线端点的安全推出。
• 详细了解 部署流程到其他平台，例如本地开发服务、Docker 容器、Azure 应用服务等