通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

  • 项目

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

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

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

重要

本文中标记了“（预览版）”的项目目前为公共预览版。 该预览版在提供时没有附带服务级别协议，建议不要将其用于生产工作负载。 某些功能可能不受支持或者受限。 有关详细信息，请参阅 Microsoft 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 联机终结点。

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

$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 （可选）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 计算目标。

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

重要

如果你的流使用基于 Microsoft Entra ID 的身份验证连接，则无论使用系统分配的标识还是用户分配的标识，都始终需要向托管标识授予相应资源的适当角色，这样才能对该资源进行 API 调用。 例如，如果你的 Azure OpenAI 连接使用基于 Microsoft Entra ID 的身份验证，则你需要向终结点托管标识授予相应 Azure OpenAI 资源的“认知服务 OpenAI 用户”或“认知服务 OpenAI 参与者”角色。

使用用户分配的标识

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

如果希望使用用户分配的标识，可以在 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 部分引用了注册的流模型。 还可以内联方式指定流模型路径。

$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:

  # "compute" mode is the default mode, if you want to deploy to serving mode, you need to set this env variable to "serving"
  PROMPTFLOW_RUN_MODE: serving

  # 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% 来执行升级。 有关详细信息，请参阅联机终结点限制。
环境变量 需要为从流部署的终结点设置以下环境变量：
-（必需）PROMPTFLOW_RUN_MODE: serving：指定要服务的模式
-（必需）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>

选项 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 的服务引擎。 你可以通过指定环境变量 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 响应，这通常表示需要按照上述指南来重新优化并发设置，或者需要对部署进行缩放。
  • 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>

注意

如果仅设置 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

后续步骤