針對即時推斷執行新部署的安全推出

  • 發行項

適用於：Azure CLI ml 延伸模組 v2 (目前)Python SDK azure-ai-ml v2 (目前)

在本文中，您將瞭解如何在生產環境中部署新版本的機器學習模型，而不會造成任何中斷。 您將使用藍色-綠色部署策略（也稱為安全推出策略），將新版本的Web服務引入生產環境。 此策略可讓您在完全推出 Web 服務之前，將新版本的 Web 服務推出至一小部分的使用者或要求。

本文假設您使用的是在線端點，也就是用於在線（即時）推斷的端點。 線上端點有兩種類型：受控線上端點和 Kubernetes 線上端點。 如需端點的詳細資訊，以及受控在線端點與 Kubernetes 在線端點之間的差異，請參閱什麼是 Azure 機器學習 端點？。

本文的主要範例使用受控在線端點進行部署。 若要改用 Kubernetes 端點，請參閱本檔中的附註，內嵌於受控在線端點討論。

在本文中，您將了解如何：

  • 使用名為 「blue」 的部署來定義在線端點，以提供模型第 1 版
  • 調整藍色部署，使其可以處理更多要求
  • 將模型第 2 版（稱為「綠色」部署）部署到端點，但不會傳送部署即時流量
  • 隔離測試綠色部署
  • 將一百分比的即時流量鏡像到綠色部署以驗證
  • 將少量即時流量傳送至綠色部署
  • 將所有即時流量傳送至綠色部署
  • 刪除現在未使用的 v1 藍色部署

必要條件

遵循本文中的步驟之前，請確定您已滿足下列必要條件：

  • Azure 角色型存取控制 (Azure RBAC) 可用來授與 Azure Machine Learning 作業的存取權。 若要執行本文中的步驟，您必須為使用者帳戶指派 Azure Machine Learning 工作區的擁有者或參與者角色，或允許 Microsoft.MachineLearningServices/workspaces/onlineEndpoints/* 的自訂角色。 如需詳細資訊，請參閱管理對 Azure Machine Learning 工作區的存取。

  • (選擇性) 如要執行本機部署，您必須在本機電腦上安裝 Docker 引擎。 強烈建議您使用此選項，以更輕鬆地執行問題偵錯。

準備您的系統

設定環境變數

如果您尚未設定 Azure CLI 的預設值，請儲存您的預設設定。 如要避免多次傳遞訂閱、工作區和資源群組的值，請執行下列程式碼：

az account set --subscription <subscription id>
az configure --defaults workspace=<Azure Machine Learning workspace name> group=<resource group>

複製範例存放庫

如要遵循本文，請先複製範例存放庫 (azureml-examples)。 然後，移至存放庫的 cli/ 目錄：

git clone --depth 1 https://github.com/Azure/azureml-examples
cd azureml-examples
cd cli

提示

使用 --depth 1 僅將最新的認可複製到存放庫。 這可縮短完成作業的時間。

本教學課程中的命令位於 目錄中的 cli 檔案deploy-safe-rollout-online-endpoints.sh中，而 YAML 組態檔位於endpoints/online/managed/sample/子目錄中。

注意

Kubernetes 線上端點的 YAML 組態檔位於 endpoints/online/kubernetes/ 子目錄中。

定義端點和部署

線上端點用於線上 (即時) 推斷。 在線端點包含已準備好接收客戶端數據的部署，並即時傳送回應。

定義端點

下表列出當您定義端點時要指定的索引鍵屬性。

屬性 描述
Name 必要。 端點的名稱。 其在 Azure 區域中必須是唯一的。 如需命名規則的詳細資訊，請參閱端點限制 (部分機器翻譯)。
驗證模式 端點的驗證方法。 選擇金鑰型驗證key和 Azure 機器學習 令牌型驗證 aml_token。 金鑰不會過期，但權杖會過期。 如需驗證的詳細資訊，請參閱向線上端點進行驗證。
描述 端點的描述。
標籤 端點標記的字典。
交通流量 如何跨部署路由傳送流量的規則。 將流量表示為索引鍵/值組的字典，其中索引鍵代表部署名稱和值代表該部署流量的百分比。 您只能在建立端點下的部署時設定流量。 您也可以在建立部署之後更新在線端點的流量。 如需如何使用鏡像流量的詳細資訊，請參閱 將少量即時流量配置給新的部署。
鏡像流量 要鏡像至部署的即時流量百分比。 如需如何使用鏡像流量的詳細資訊，請參閱 使用鏡像流量測試部署。

若要查看您可以在建立端點時指定之屬性的完整清單，請參閱 CLI （v2） 在線端點 YAML 架構 或 SDK （v2） ManagedOnlineEndpoint 類別。

定義部署

部署是裝載執行實際推斷之模型所需的一組資源。 下表描述定義部署時所要指定的索引鍵屬性。

屬性 描述
Name 必要。 部署的名稱。
端點名稱 必要。 要建立部署的端點名稱。
模型 要用於部署的模型。 此值可以是工作區中現有已建立版本模型的參考，也可以是內嵌模型規格。 在此範例中，我們有一個可執行迴歸的 scikit-learn 模型。
程式碼路徑 本機開發環境上的目錄路徑，包含用來對模型進行評分的所有 Python 原始程式碼。 您可以使用巢狀目錄和套件。
評分指令碼 在指定的輸入要求上執行模型的 Python 程式代碼。 此值可以是原始程式碼目錄中評分檔案的相對路徑。
評分指令碼會接收提交給已部署 Web 服務的資料，並將資料傳遞給模型。 然後，此指令碼會執行模型，並將其回應傳回給用戶端。 評分指令碼是模型專用的，其必須了解模型預期的輸入資料和傳回的輸出資料。
在此範例中，我們有一個「score.py」檔案。 此 Python 程式碼必須具有 init() 函式與 run() 函式。 建立或更新模型之後，即會呼叫 init() 函式 (例如，您可使用該函式來快取記憶體中的模型)。 每次引動端點時會呼叫 run() 函式，以執行實際評分和預測。
Environment 必要。 用來裝仔模型和程式碼的環境。 此值可以是工作區中現有已建立版本環境的參考，也可以是內嵌環境規格。 環境可以是具有 Conda 相依性的 Docker 映像、Dockerfile 或已註冊的環境。
執行個體類型 必要。 要用於部署的 VM 大小。 如需支援的大小清單，請參閱受控線上端點 SKU 清單。
執行個體計數 必要。 要用於部署的執行個體數目。 根據您預期的工作負載做為值。 為了達到高可用性，建議您將值至少設定為 3。 我們會額外保留 20% 來執行升級。 如需詳細資訊，請參閱 在線端點的限制。

若要查看您可以在建立部署時指定之屬性的完整清單，請參閱 CLI （v2） Managed Online Deployment YAML 架構 或 SDK （v2） ManagedOnlineDeployment 類別。

建立在線端點

請先設定端點的名稱，然後加以設定。 在本文中，您將使用 endpoints/online/managed/sample/endpoint.yml 檔案來設定端點。 下列代碼段顯示檔案的內容：

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: key

下表說明端點 YAML 格式的參考。 若要了解如何指定這些屬性，請參閱線上端點 YAML 參考。 如需與受控在線端點相關的限制資訊，請參閱 在線端點的限制。

關鍵 描述
$schema (選擇性) YAML 結構描述。 若要查看 YAML 檔案中的所有可用選項，您可以在瀏覽器內檢視上述程式碼片段中的結構描述。
name 端點的名稱。
auth_mode 使用 key 進行金鑰式驗證。 使用 aml_token 進行 Azure Machine Learning 權杖型驗證。 若要取得最新的權杖，請使用 az ml online-endpoint get-credentials 命令。

若要建立線上端點：

  1. 設定您的端點名稱：

    針對 Unix，執行此指令 （以唯一名稱取代 YOUR_ENDPOINT_NAME ）：

    export ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"

    重要

    端點名稱在 Azure 區域內必須是唯一的。 例如，在 Azure westus2 區域中，只能有一個名稱為 的 my-endpoint端點。

  2. 在雲端中建立端點：

    執行下列程式代碼以使用 endpoint.yml 檔案來設定端點：

    az ml online-endpoint create --name $ENDPOINT_NAME -f endpoints/online/managed/sample/endpoint.yml

建立 『blue』 部署

在本文中，您將使用 endpoints/online/managed/sample/blue-deployment.yml 檔案來設定部署的主要層面。 下列代碼段顯示檔案的內容：

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-endpoint
model:
  path: ../../model-1/model/
code_configuration:
  code: ../../model-1/onlinescoring/
  scoring_script: score.py
environment: 
  conda_file: ../../model-1/environment/conda.yaml
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
instance_type: Standard_DS3_v2
instance_count: 1

若要為您的端點建立名為 blue 的部署，請執行下列命令以使用 blue-deployment.yml 檔案來設定

az ml online-deployment create --name blue --endpoint-name $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml --all-traffic

重要

--all-traffic中的 az ml online-deployment create 旗標會將 100% 的端點流量配置至新建立的藍色部署。

在檔案中 blue-deployment.yaml ，我們會指定要 path 內嵌上傳檔案的位置。 CLI 會自動上傳檔案，並註冊模型和環境。 就生產最佳做法而言，您應註冊模型和環境，並在 YAML 中個別指定註冊的名稱和版本。 使用表單 model: azureml:my-model:1 或 environment: azureml:my-env:1。

註冊時，您可將 model 和 environment 的 YAML 定義擷取至個別的 YAML 檔案，並使用 az ml model create 與 az ml environment create 命令。 如要深入瞭解這些命令，請執行 az ml model create -h 和 az ml environment create -h。

如需將模型註冊為資產的詳細資訊，請參閱使用 CLI 在 Machine Learning 中將模型註冊為資產。 如需建立環境的詳細資訊，請參閱使用 CLI 和 SDK (v2) 管理 Azure Machine Learning 環境。

確認現有的部署

確認現有部署的其中一種方法是叫用端點，以便為模型評分以取得指定的輸入要求。 當您透過 CLI 或 Python SDK 叫用端點時，您可以選擇指定將接收傳入流量的部署名稱。

注意

不同於 CLI 或 Python SDK，Azure Machine Learning 工作室 要求您在叫用端點時指定部署。

使用部署名稱叫用端點

如果您使用將接收流量的部署名稱叫用端點，Azure 機器學習 會將端點的流量直接路由傳送至指定的部署，並傳回其輸出。 您可以使用 --deployment-name CLI v2 的選項，或 deployment_name SDK v2 的選項來指定部署。

在未指定部署的情況下叫用端點

如果您在未指定接收流量的部署的情況下叫用端點，Azure 機器學習 會根據流量控制設定，將端點的連入流量路由傳送至端點中的部署。

流量控制設定會配置指定百分比的連入流量到端點中的每個部署。 例如，如果您的流量規則指定端點中的特定部署將接收傳入流量 40% 的時間，Azure 機器學習 會將端點流量的 40% 路由傳送至該部署。

您可以執行下列命令來檢視現有端點和部署的狀態：

az ml online-endpoint show --name $ENDPOINT_NAME 

az ml online-deployment show --name blue --endpoint $ENDPOINT_NAME

您應該會看到和 所 $ENDPOINT_NAME 識別的端點，稱為的部署 blue。

使用範例數據測試端點

您可以使用 命令叫用 invoke 端點。 我們將使用 json 檔案傳送樣本要求。

az ml online-endpoint invoke --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json

調整現有的部署以處理更多流量

在使用在線端點部署和評分機器學習模型中所述的部署中，您會將 設定instance_count為部署 yaml 檔案中的值1。 您可以使用 命令相應放大 update ：

az ml online-deployment update --name blue --endpoint-name $ENDPOINT_NAME --set instance_count=2

注意

請注意，在上述命令中，我們使用 --set 來覆寫部署組態。 或者，您也可以更新 yaml 檔案，並使用輸入將它當做輸入傳遞給 update 命令 --file 。

部署新的模型，但尚未傳送任何流量

建立名為 green的新部署：

az ml online-deployment create --name green --endpoint-name $ENDPOINT_NAME -f endpoints/online/managed/sample/green-deployment.yml

由於我們尚未明確配置任何流量給 green，因此沒有配置給它的零個流量。 您可以使用 命令來確認：

az ml online-endpoint show -n $ENDPOINT_NAME --query traffic

測試新的部署

雖然 green 已配置 0% 的流量，但您可以藉由指定名稱來直接叫 --deployment 用它：

az ml online-endpoint invoke --name $ENDPOINT_NAME --deployment-name green --request-file endpoints/online/model-2/sample-request.json

如果您想要使用 REST 用戶端直接叫用部署而不經過流量規則，請設定下列 HTTP 標頭： azureml-model-deployment: <deployment-name>。 下列代碼段會使用 curl 來直接叫用部署。 代碼段應該在 Unix/WSL 環境中運作：

# get the scoring uri
SCORING_URI=$(az ml online-endpoint show -n $ENDPOINT_NAME -o tsv --query scoring_uri)
# use curl to invoke the endpoint
curl --request POST "$SCORING_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --header "azureml-model-deployment: green" --data @endpoints/online/model-2/sample-request.json

使用鏡像流量測試部署

測試 green 部署之後，您可以 鏡像 （或複製）一百分比的即時流量。 流量鏡像（也稱為陰影）不會變更傳回給客戶端的結果，要求仍會將 100% 流向 blue 部署。 流量的鏡像百分比會複製並提交至 green 部署，讓您可以收集計量和記錄，而不會影響您的用戶端。 當您想要驗證新的部署而不會影響用戶端時，鏡像非常有用。 例如，您可以使用鏡像來檢查延遲是否在可接受的範圍內，或檢查是否有 HTTP 錯誤。 使用流量鏡像/陰影測試來測試新的部署，也稱為 陰影測試。 接收鏡像流量的部署（在此案例中為 green 部署）也可以稱為 陰影部署。

鏡像具有下列限制：

  • CLI 支援鏡像 （v2） （2.4.0 版或更新版本） 和 Python SDK （v2） （1.0.0 版或更新版本）。 如果您使用舊版的 CLI/SDK 來更新端點，您將失去鏡像流量設定。
  • Kubernetes 在線端點目前不支援鏡像。
  • 您可以將流量鏡像到端點中的一個部署。
  • 您可以鏡像的流量百分比上限為 50%。 此限制是減少對端點頻寬配額的影響（預設為 5 MBPS），如果您超過配置的配額，您的端點頻寬就會受到節流。 如需監視頻寬節流的資訊，請參閱 監視受控在線端點。

另請注意下列行為：

  • 部署可以設定為只接收即時流量或鏡像流量，而不是兩者。
  • 當您叫用端點時，您可以指定其任何部署的名稱，甚至是陰影部署，以傳回預測。
  • 當您使用將接收連入流量的部署名稱叫用端點時，Azure 機器學習 不會將流量鏡像到陰影部署。 Azure 機器學習 當您未指定部署時，會從傳送至端點的流量鏡像到陰影部署的流量。

現在，讓我們設定綠色部署以接收 10% 的鏡像流量。 用戶端仍會收到來自藍色部署的預測。

Diagram showing 10% traffic mirrored to one deployment.

下列命令會鏡像 10% 的流量到 green 部署：

az ml online-endpoint update --name $ENDPOINT_NAME --mirror-traffic "green=10"

您可以叫用端點數次來測試鏡像流量，而不需指定部署來接收傳入流量：

for i in {1..20} ; do
    az ml online-endpoint invoke --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json
done

您可以檢視來自部署的記錄，以確認流量的特定百分比已傳送至 green 部署：

az ml online-deployment get-logs --name blue --endpoint $ENDPOINT_NAME

測試之後，您可以將鏡像流量設定為零以停用鏡像：

az ml online-endpoint update --name $ENDPOINT_NAME --mirror-traffic "green=0"

將少量即時流量配置至新部署

測試 green 部署之後，請配置一小部分流量給它：

az ml online-endpoint update --name $ENDPOINT_NAME --traffic "blue=90 green=10"

提示

總流量百分比必須加總到 0% （若要停用流量），或 100% （啟用流量）。

現在，您的 green 部署會接收 10% 的所有即時流量。 用戶端會收到 來自和 green 部署的預測blue。

Diagram showing traffic split between deployments.

將所有流量傳送至您的新部署

一旦您完全滿意您的 green 部署，請將所有流量切換至該部署。

az ml online-endpoint update --name $ENDPOINT_NAME --traffic "blue=0 green=100"

拿掉舊的部署

使用下列步驟，從受控在線端點刪除個別部署。 刪除個別部署會影響受控在線端點中的其他部署：

az ml online-deployment delete --name blue --endpoint $ENDPOINT_NAME --yes --no-wait

刪除端點和部署

如果您不打算使用端點和部署，您應該將其刪除。 刪除端點也會刪除其所有基礎部署。

az ml online-endpoint delete --name $ENDPOINT_NAME --yes --no-wait

相關內容