共用方式為

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

  • 發行項

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

在本文中，您將了解如何在生產環境中部署新版的機器學習模型，而不造成任何中斷。 您將使用藍綠部署策略 (也稱為安全推出策略)，將新版的 Web 服務引進到實際執行環境。 此策略可讓您在完全推出 Web 服務之前，將新版的 Web 服務推出至一小部分的使用者或要求。

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

本文中的主要範例使用受控線上端點進行部署。 若要改為使用 Kubernetes 端點，請參閱本文件中的附註與受控線上端點討論。

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

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

必要條件

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

  • 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 Machine Learning 權杖型驗證 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) 受控線上部署 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

建立「藍色」部署

在本文中，您將使用 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

重要

az ml online-deployment create 中的 --all-traffic 旗標會將 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 管理 Azure Machine Learning 環境 (v2) (部分機器翻譯)。

確認您現有的部署

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

注意

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

使用部署名稱叫用端點

如果您使用將接收流量的部署名稱叫用端點，Azure Machine Learning 會將端點的流量直接路由傳送到指定的部署，並傳回其輸出。 您可以針對 CLI v2 (部分機器翻譯) 使用 --deployment-name 選項，或針對 SDK v2 (部分機器翻譯) 使用 deployment_name 選項來指定部署。

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

如果您在沒有指定將接收流量之部署的情況下叫用端點，Azure Machine Learning 會將端點的傳入流量根據流量控制設定路由傳送至端點中的部署。

流量控制設定會將指定百分比的傳入流量配置到端點中的每個部署。 例如，如果您的流量規則指定您端點中的特定部署將會接收當下 40% 的傳入流量，Azure Machine Learning 便會將 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

縮放現有部署以處理更多流量

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

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

注意

請注意，在上述命令中我們使用 --set 來覆寫部署設定。 或者，您也可以更新 yaml 檔案，並使用 --file 輸入將該檔案作為輸入傳遞到 update 命令中。

部署新的模型，但還不要向其傳送任何流量

建立名為 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 Machine Learning 並不會針對鏡像部署進行流量鏡像。 Azure Machine Learning 只會在您未指定部署的情況下，將傳送至端點的流量對鏡像部署進行流量鏡像。

現在，讓我們將綠色部署設定為接收 10% 的鏡像流量。 用戶端仍然只會從藍色部署接收預測。

顯示 10% 流量鏡像到一個部署的圖表。

下列命令會將 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%。 用戶端將會同時接收到來自 blue 和 green 部署的預測。

顯示部署之間流量分割的圖表。

將所有流量傳送給新的部署

當您覺得 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

相關內容