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

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

警告

Microsoft Foundry 和 Azure 机器学习中的 Prompt flow 将于 2027 年 4 月 20 日退役。对于新开发，不再推荐使用提示流。请于 2027 年 4 月 20 日前将现有的 Prompt flow 应用和部署迁移到 Microsoft Agent Framework。

提示流容器映像不再接收更新，包括安全更新和包更新。这适用于 Prompt flow 运行时镜像，包括 promptflow-runtime、promptflow-runtime-stable 和 promptflow-python。

2027 年 4 月 20 日之后，提示流（包括 Microsoft Foundry 和 Azure 机器学习中的 Web 创作体验、VS Code 扩展和相关提示流容器映像）将不再受支持或可用。

如果应用程序依赖于提示流部署或运行时映像，请计划在停用日期之前将这些工作负荷移动到受支持的替代项，例如 Microsoft Agent Framework。有关迁移指南，请参阅提示流迁移指南和迁移代码示例。

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

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

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

重要

本文中标记为（预览）的项目目前以公共预览版提供。预览版在没有服务级别协议的情况下提供，不建议用于生产工作负荷。某些功能可能不受支持，或者可能具有受限功能。有关详细信息，请参阅 Microsoft Azure 预览版的使用条款。

先决条件

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

注意

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

部署的虚拟机配额分配

对于托管的在线终结点，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 机器学习托管在线终结点。

重要

如果您在流中使用 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 机器学习工作区连接机密读取者角色，以便终结点在执行推理时能够正确访问连接。 - 默认情况下，此属性为“disabled”。

如果创建 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资源来执行推理。有关详细信息，请参阅如何向终结点身份授予权限。

Scope	作用	为何需要
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"]'

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

重要

如果您的流文件夹中包含一个 requirements.txt 文件，且该文件包含执行流所需的依赖项，请按照使用自定义环境进行部署中的步骤，构建包含这些依赖项的自定义环境。

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

属性	描述
类型	部署的类型。将值设置为 `kubernetes`.
实例类型	在 Kubernetes 群集中创建的用于部署的实例类型。它表示该部署的计算资源请求和限制。有关更多详细信息，请参阅 “创建和管理实例类型”。

将在线终结点部署到 Microsoft 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% 的终结点流量分配给新创建的 blue 部署。尽管这种分配方式有助于开发和测试，但在生产环境中，你可能希望通过显式命令将流量切换到新部署版本。例如， 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_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，而不是工作区链接的那个。可以在部署 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 为 5,000 毫秒。最多可以设置 5 分钟，即 300,000 毫秒。以下示例演示如何在部署 YAML 文件中指定请求超时。有关部署架构的详细信息，请参阅托管联机部署架构。

request_settings:
  request_timeout_ms: 300000

重要

300,000 毫秒的超时 仅适用于来自 Prompt Flow 的托管联机部署。由非提示流管理的联机终结点的最大超时时间为 180 秒。

要表明此部署来自提示流，请按如下方式为模型添加属性（部署 YAML 中的内联模型规范或独立的模型规范 YAML）。

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

后续步骤

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

反馈

此页面是否有帮助？

Last updated on 2026-07-01