將流程部署到線上端點以進行即時推論，使用 CLI

在本文中，您將學習如何將流程部署到受管線上端點或 Kubernetes 線上端點，並利用 Azure Machine Learning v2 CLI 進行即時推論。

開始之前，確保您已測試流程，並確認其已準備好部署至生產環境。 想了解更多關於測試流程的方法，請參見 測試你的流程。 測試流程後，你會學會如何建立受管理的線上端點與部署，以及如何用端點進行即時推論。

• 本文將介紹如何使用 CLI 體驗。
• 本文未涵蓋 Python SDK。 請參考 GitHub 範例筆記本。 要使用 Python SDK，你必須擁有 Python SDK v2 for Azure Machine Learning。 欲了解更多，請參閱 安裝 Python SDK v2 for Azure Machine Learning。

先決條件

• Azure CLI 和 Azure CLI 的 Azure Machine Learning 擴充功能。 更多資訊請參閱安裝、設定與使用 CLI （v2）
• 一個 Azure Machine Learning 工作空間。 如果你還沒有，請使用 快速入門：建立工作區資源文章 中的步驟來建立。
• Azure 角色基礎存取控制（Azure RBAC）用於授權 Azure Machine Learning 中的操作存取權。 要執行本文中的步驟，您的使用者帳號必須被指定為 Azure Machine Learning 工作空間的擁有者或貢獻者角色，或是自訂角色，允許「Microsoft.MachineLearningServices/workspaces/onlineEndpoints/“。 如果你使用 Studio 來建立及管理線上端點和部署作業，則需要資源群組擁有者授與另一項權限「Microsoft.Resources/deployments/write」。 欲了解更多資訊，請參閱 管理Azure Machine Learning工作區存取權。

部署虛擬機的配額分配

對於受管理的線上端點，Azure Machine Learning 會保留 20% 的運算資源用於升級。 因此，如果你在部署中請求一定數量的實例，必須確保 ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU 的配額可用，以避免錯誤。 舉例來說，如果你在部署中請求 10 個 Standard_DS3_v2 虛擬機（附四個核心），你應該會有 48 個核心（12 個實例各四個核心）的配額。 欲查看您的使用量並申請配額增加，請參閱在Azure入口網站查看您的使用量與配額。

準備流程以便部署

每個流程都有一個資料夾，裡面包含程式碼、提示、定義及流程的其他產物。 如果你用介面開發流程，可以從流程細節頁面下載 flow 資料夾。 如果你是用 CLI 或 SDK 來開發流程，你已經有 flow 資料夾了。

本文以 範例流程「basic-chat」作為範例，部署到Azure Machine Learning受管理的線上端點。

設定預設工作區

請使用以下指令設定 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 Azure Machine Learning studio, the endpoint Test tab uses this property to identify a 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 Machine Learning 的憑證式認證之間選擇。 金鑰不會過期，但代幣會過期。 欲了解更多認證資訊，請參閱 「認證至線上端點」。
• 可選擇地，在端點上加入描述和標籤。
• 如果您想部署到連線到工作區的 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

另外，請在 Client ID 檔案中的 environment_variables 下指定使用者指派身分的 deployment.yaml，如下例所示。 您可以在 Azure 入口網站中，受控識別的 Client ID 內找到 Overview。

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 線上部署，請指定以下屬性：

將你的線上端點部署到 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 Machine Learning 工作區的 Endpoints>Consume>Basic consumption info 中取得端點金鑰和端點 URI。

進階配置

使用流程開發的不同連線進行部署

建議您在部署期間覆寫流程的連線。

例如，如果你的 flow.dag.yaml 檔案使用名為 my_connection的連線，你可以透過加入部署 yaml 的環境變數來覆蓋該連線，如下所示：

選項一：覆寫連線名稱

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 Machine Learning 環境。

Prompt flow 執行階段映像已凍結，且不再接收安全性或套件更新。 latest以下範例中的標籤並不表示圖片會收到更新。 此範例僅用於維護現有部署，同時規劃遷移。

1. 在你的本地環境中，建立一個名為 image_build_with_requirements 資料夾的資料夾，裡面包含以下檔案：

|--image_build_with_requirements
  |  |--requirements.txt
  |  |--Dockerfile
  ```
  - The `requirements.txt` file, inherited from the flow folder, tracks the dependencies of the flow. 

  - The `Dockerfile` with content similar to the following example: 

      ```dockerfile
      FROM mcr.microsoft.com/azureml/promptflow/promptflow-runtime:latest
      COPY ./requirements.txt .
      RUN pip install -r requirements.txt
      ```

1. Replace the environment section in the deployment definition YAML file with the following content:

  ```yaml
  environment: 
    build:
      path: image_build_with_requirements
      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
  ```

### Use FastAPI serving engine (preview)

By default, prompt flow serving uses the Flask serving engine. Starting from prompt flow SDK version 1.10.0, FastAPI-based serving engine is supported. You can use the `fastapi` serving engine by specifying an environment variable `PROMPTFLOW_SERVING_ENGINE`.

```yaml
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，而不是連結到的工作區。 你可以在部署 yaml 檔案中指定環境變數如下。 你可以在 Azure 入口網站的總覽頁面找到你的 Application Insights 的連接字串。

environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

常見錯誤

取用端點時的上游要求逾時問題

這個錯誤通常是因為超時造成的。 預設 request_timeout_ms 值為 5,000 毫秒。 你可以設定到最多 5 分鐘，也就是 300,000 毫秒。 以下範例說明如何在部署 YAML 檔案中指定請求逾時。 欲了解更多部署架構資訊，請參閱 管理線上部署架構。

request_settings:
  request_timeout_ms: 300000

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

下一步

• 了解更多關於 受管線上端點架構 與 受管線上部署架構的資訊。
• 了解更多如何在 UI 中測試端點並監控端點。
• 了解更多如何排除受管線上端點故障的方法。
• 疑難排解提示流程部署。
• 若要使用安全部署策略來部署更完善的流程版本，請參閱 線上端點的安全部署。
• 了解更多關於 deploy 流程到其他平台，例如本地開發服務、Docker 容器、Azure APP 服務等。