使用 CLI 將流程部署至線上端點以進行即時推斷
在本文中，您將會了解如何將流程部署至受控線上端點或 Kubernetes 線上端點，以搭配 Azure Machine Learning 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/」的自訂角色。 如果您使用 Studio 來建立/管理在線端點/部署，您需要資源群組擁有者的額外許可權 “Microsoft.Resources/deployments/write”。 如需詳細資訊，請參閱管理對 Azure Machine Learning 工作區的存取。
注意
受控在線端點僅支援受控虛擬網路。 如果您的工作區位於自定義 vnet 中，您可以部署至 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 Machine Learning 受控線上端點的範例。
重要
如果您已在流程中使用 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 線上端點。
以下是預設會使用系統指派身分識別的端點定義範例。
$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 Machine Learning 權杖型驗證。 若要取得最新的權杖，請使用 az ml online-endpoint get-credentials 命令。 |
property: enforce_access_to_default_secret_stores (預覽) |
- 根據預設，端點會使用系統指派的身分識別。 此屬性僅適用於系統指派的身分識別。 - 這個屬性表示如果您有連線祕密讀者權限，端點系統指派的身分識別將會自動指派工作區的 Azure Machine Learning 工作區連線祕密讀者角色，讓端點在執行推斷時可以正確存取連線。 - 根據預設，此屬性為「已停用」。 |
如果您建立 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 區段參考已註冊的流程模型。 您也可以在行中指定流程模型路徑。
$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"]'
| 屬性 | 描述 |
|---|---|
| Name | 部署的名稱。 |
| 端點名稱 | 要在其下建立部署的端點名稱。 |
| 模型 | 要用於部署的模型。 此值可以是工作區中現有已建立版本模型的參考，也可以是內嵌模型規格。 |
| Environment | 用來裝載模型和程式碼的環境。 它包含： - image- inference_config：是用來建置服務容器以進行線上部署，包括 liveness route、readiness_route 和 scoring_route。 |
| 執行個體類型 | 要用於部署的 VM 大小。 如需支援的大小清單，請參閱受控線上端點 SKU 清單。 |
| 執行個體計數 | 要用於部署的執行個體數目。 根據您預期的工作負載做為值。 為了達到高可用性，建議您將值至少設定為 3。 我們會額外保留 20% 來執行升級。 如需詳細資訊，請參閱線上端點的限制。 |
| 環境變數 | 必須針對從流程部署的端點設定下列環境變數： - (必要) PROMPTFLOW_RUN_MODE: serving：指定服務的模式 - (必要) PRT_CONFIG_OVERRIDE：從工作區提取連線 - (選擇性) PROMPTFLOW_RESPONSE_INCLUDED_FIELDS:：在回應中有多個欄位時，使用此環境變數將會篩選在回應中公開的欄位。 例如，如果有兩個流程輸出：「答案」、「內容」，而您在端點回應中只想有「答案」，您可以將此環境變數設定為 '["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 新增至命令。 不過，這將停止部署狀態的互動式顯示。
重要
上述 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 Machine Learning 工作區，取得端點金鑰和端點 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 Machine Learning 環境。
在您的本機環境中，建立名為
image_build_with_reqirements的資料夾，其中包含下列檔案：|--image_build_with_reqirements | |--requirements.txt | |--Dockerfilerequirements.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 秒。
- 如果您要求時間大於 200 毫秒，請將
在微調上述參數時，您必須監視下列計量，以確保最佳效能和穩定性：
- 此部署的執行個體 CPU/記憶體使用率
- 非 200 回應 (4xx，5xx)
- 如果您收到 429 回應，這通常表示您必須遵循上述指南重新調整並行設定，或調整部署規模。
- Azure OpenAI 節流狀態
監視端點
收集一般計量
您可以檢視在線部署的一般計量（要求號碼、要求延遲、網路位元組、CPU/GPU/磁碟/記憶體使用率等等）。
在推斷期間收集追蹤數據和系統計量
您也可以在推斷時間將屬性新增至部署 yaml 檔案中的屬性 app_insights_enabled: true ，以收集追蹤數據和提示流程部署特定計量（令牌耗用量、流程延遲等）。 深入瞭解 提示流程部署的追蹤和計量。
提示流程特定計量和追蹤可以指定給工作區連結以外的其他 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
下一步
- 深入了解受控線上端點結構描述和受控線上部署結構描述。
- 深入了解如何在 UI 中測試端點和監視端點。
- 深入了解如何針對受控線上端點進行疑難排解。
- 針對提示流程部署進行疑難解答。
- 一旦您改善流程，並想要使用安全推出策略來部署改良的版本，請參閱安全推出線上端點。
- 深入了解將流程部署到其他平台，例如本機開發服務、Docker 容器、Azure App Service 等等。