使用 CLI 將流程部署至線上端點以進行即時推斷

發行項
02/04/2025

在本文中，您將瞭解如何將流程部署至受控在線端點或 Kubernetes 在線端點，以便與 Azure 機器學習 v2 CLI 實時推斷搭配使用。

開始之前，請確定您已正確測試流程，並確信已準備好部署至生產環境。若要深入了解測試流程，請參閱測試流程。測試流程之後，您將瞭解如何建立受控在線端點和部署，以及如何使用端點進行即時推斷。

本文涵蓋如何使用 CLI 體驗。
本文未涵蓋 Python SDK。請改為參閱 GitHub 範例筆記本。若要使用 Python SDK，您必須具有適用於 Azure Machine Learning 的 Python SDK v2。若要深入了解，請參閱安裝適用於 Azure Machine Learning 的 Python SDK v2。

重要

本文中標示為 (預覽) 的項目目前處於公開預覽狀態。此預覽版本會在沒有服務等級協定的情況下提供，不建議用於實際執行工作負載。可能不支援特定功能，或可能已經限制功能。如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。

必要條件

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/」的自訂角色。如果您使用工作室來建立/管理線上端點/部署，則需要向資源群組擁有者要求其他權限「Microsoft.Resources/deployments/write」。如需詳細資訊，請參閱管理對 Azure Machine Learning 工作區的存取。

注意

受控線上端點僅支援受控虛擬網路。如果您的工作區位於自定義虛擬網路中，您可以部署至 Kubernetes 在線端點，或部署至 Docker 等其他平臺。

為部署配置的虛擬機器配額

針對受控線上端點，Azure Machine Learning 會保留 20% 的計算資源以執行升級。因此，如果您在部署中要求指定數目的執行個體，則必須有 ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU 的配額可供使用，才能避免收到錯誤。例如，如果您在部署中要求 10 個 Standard_DS3_v2 VM (隨附四個核心) 執行個體，則應該有 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 Machine Learning 權杖型驗證之間進行選擇。金鑰不會過期，但權杖會過期。如需驗證的詳細資訊，請參閱向線上端點進行驗證。 (選擇性) 您可以在端點中新增描述和標籤。
(選擇性) 您可以在端點中新增描述和標籤。
如果您想要部署到連結至工作區的 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 Machine Learning 權杖型驗證。若要取得最新的權杖，請使用 `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

此外，您也需要在 environment_variables 底下指定使用者指派身分識別的 Client ID，deployment.yaml 如下所示。您可以在 Azure 入口網站中受控識別的 Overview 中找到 Client ID。

environment_variables:
  AZURE_CLIENT_ID: <client_id_of_your_user_assigned_identity>

重要

您必須在建立端點之前，將下列權限授與使用者指派的身分識別，才能存取 Azure 資源來執行推斷。深入了解如何將權限授與端點身分識別。

範圍	角色	需要的原因
Azure Machine Learning 工作區	Azure 機器學習工作區連接秘密讀者角色或具有「Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action」的自訂角色	取得工作區連線
工作區容器登錄	ACR 提取	提取容器映像
工作區預設儲存體	儲存體 Blob 資料讀者	從儲存體載入模型
(選擇性) Azure Machine Learning 工作區	工作區計量寫入器	部署端點之後，如果您想要監視端點的相關計量，例如 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"]'

屬性	描述
Name	部署的名稱。
端點名稱	要在其下建立部署的端點名稱。
模型	要用於部署的模型。此值可以是工作區中現有已建立版本模型的參考，也可以是內嵌模型規格。
Environment	用來裝載模型和程式碼的環境。它包含： - `image` - `inference_config`：是用來建置服務容器以進行線上部署，包括 `liveness route`、`readiness_route` 和 `scoring_route`。
執行個體類型	要用於部署的 VM 大小。如需支援的大小清單，請參閱受控線上端點 SKU 清單。
執行個體計數	要用於部署的執行個體數目。根據您預期的工作負載做為值。為了達到高可用性，建議您將值至少設定為 `3`。我們會額外保留 20% 來執行升級。如需詳細資訊，請參閱線上端點的限制。
環境變數	必須針對從流程部署的端點設定下列環境變數： - (必要) `PRT_CONFIG_OVERRIDE`：從工作區提取連線 - （選擇性） `PROMPTFLOW_RESPONSE_INCLUDED_FIELDS:`：當回應中有多個字段時，使用此 env 變數會篩選要公開在回應中的字段。例如，如果有兩個流程輸出：「答案」、「內容」，而您在端點回應中只想有「答案」，您可以將此環境變數設定為 '["answer"]'。

重要

如果您的流程資料夾有 requirements.txt 檔案，其中包含執行流程所需的相依性，您必須遵循使用自訂環境進行部署的步驟 (部分機器翻譯) 來建置自訂環境，包括相依性。

如果您建立 Kubernetes 在線部署，您必須指定下列屬性：

屬性	描述
類型	部署的類型。將值設定為 `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 新增至命令。不過，這會停止部署狀態的互動式顯示。

重要

--all-traffic先前az ml online-deployment create的旗標會將 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 Machine Learning 工作區，取得端點金鑰和端點 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 回應，這通常表示您必須遵循上述指南重新調整並行設定，或調整部署規模。
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 是 5000。您可以指定最多 5 分鐘，也就是 300,000 毫秒。下列範例示範如何在部署 YAML 檔案中指定要求逾時。在此處深入了解部署結構描述。

request_settings:
  request_timeout_ms: 300000

重要

300,000 毫秒逾時 僅適用於來自提示流程的受控在線部署。非提示流程受控在線端點的最大值為180秒。

您必須確定您已新增模型的屬性，如下所示（部署 yaml 中的內嵌模型規格或獨立模型規格 yaml），以指出這是來自提示流程的部署。

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

下一步

深入了解受控線上端點結構描述和受控線上部署結構描述。
深入了解如何在 UI 中測試端點和監視端點。
深入了解如何針對受控線上端點進行疑難排解。
針對提示流程部署進行疑難排解。
一旦您改善流程，並想要使用安全推出策略來部署改良的版本，請參閱安全推出線上端點。
深入了解將流程部署到其他平台，例如本機開發服務、Docker 容器、Azure App Service 等等。

共用方式為