使用線上端點部署和評分機器學習模型

  • 發行項

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

在本文中，您將瞭解如何將模型部署至在線端點，以用於即時推斷。 您一開始會在本機計算機上部署模型，以偵錯任何錯誤。 然後，您會在 Azure 中部署及測試模型、檢視部署記錄，以及監視服務等級協定 （SLA）。 在本文結束時，您會擁有可用於即時推斷的可調整 HTTPS/REST 端點。

線上端點是用於即時推斷的端點。 線上端點有兩種類型：受控線上端點和 Kubernetes 線上端點。 如需受控在線端點與 Kubernetes 在線端點之間端點差異的詳細資訊，請參閱什麼是 Azure 機器學習 端點？

受控線上端點可協助您以周全的方式部署機器學習模型。 受控線上端點會以可調整且完全受控的方式，在 Azure 中使用強大的 CPU 和 GPU 機器。 受控線上端點負責服務、調整、保護和監視您的模型，讓您免除設定和管理基礎結構的額外負荷。

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

必要條件

適用於：Azure CLI ml 延伸模組 v2 (目前)

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

  • Azure 角色型存取控制 (Azure RBAC) 可用來授與 Azure Machine Learning 作業的存取權。 若要執行本文中的步驟，您必須為使用者帳戶指派 Azure Machine Learning 工作區的擁有者或參與者角色，或允許 Microsoft.MachineLearningServices/workspaces/onlineEndpoints/* 的自訂角色。 如果您使用 Studio 來建立/管理在線端點/部署，您需要資源群組擁有者的額外許可權 “Microsoft.Resources/deployments/write”。 如需詳細資訊，請參閱管理對 Azure Machine Learning 工作區的存取。

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

  • 請確定您有足夠的虛擬機器 （VM） 配額已配置用於部署。 Azure 機器學習 保留 20% 的計算資源，以在某些 VM SKU 上執行升級。 例如，如果您在部署中要求 10 個實例，則 VM SKU 的每個核心數目都必須有 12 個配額。 無法考慮額外的計算資源會導致錯誤。 有一些 VM SKU 可免除額外的配額保留。 如需配額配置的詳細資訊，請參閱 部署的虛擬機配額配置。

  • 或者，您可以使用 Azure 機器學習 共用配額集區的配額一段時間。 用戶可以從此集區存取配額，以在有限的時間內執行測試。 當您使用 Studio 將 Llama-2、Phi、Nemotron、Mistral、Dolly 和 Deci-DeciLM 模型從模型類別目錄部署到受控在線端點時，Azure 機器學習 可讓您在短時間內存取其共用配額集區，以便執行測試。 如需共用配額集區的詳細資訊，請參閱 Azure 機器學習 共用配額。

準備您的系統

設定環境變數

如果您尚未設定 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-local-endpoint.sh 和 deploy-managed-online-endpoint.sh 中，而 YAML 設定檔則位於 endpoints/online/managed/sample/ 子目錄中。

注意

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

定義端點

若要定義在線端點，請指定端點名稱和驗證模式。 如需受控在線端點的詳細資訊，請參閱 在線端點。

設定端點名稱

若要設定端點名稱，請執行下列命令。 將取代 YOUR_ENDPOINT_NAME 為 Azure 區域中唯一的名稱。 如需命名規則的詳細資訊，請參閱端點限制。

針對 Linux，請執行此命令：

export ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"

設定端點

下列程式碼片段顯示 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 權杖型驗證。
用於 aad_token Microsoft Entra 令牌型驗證（預覽）。
如需驗證的詳細資訊，請參閱 驗證在線端點的用戶端。

定義部署

部署是託管執行實際推斷模型所需的一組資源。 在此範例中，您會部署scikit-learn模型，該模型會執行回歸，並使用評分腳本 score.py 在指定的輸入要求時執行模型。

若要瞭解部署的主要屬性，請參閱 在線部署。

設定部署

您的部署組態會使用您想要部署的模型位置。

下列程式碼片段顯示 endpoints/online/managed/sample/blue-deployment.yml 檔案，以及所有要設定部署所需的輸入：

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-deployment.yml檔案會指定下列部署屬性：

  • model - 使用 path 內嵌指定模型屬性（上傳檔案的來源）。 CLI 會自動上傳模型檔案，並以自動產生的名稱註冊模型。
  • environment - 使用內嵌定義來包含上傳檔案的來源，CLI 會自動上傳 conda.yaml 檔案並註冊環境。 稍後，若要建置環境，部署會針對基底映像使用 image （在此範例 mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest中為 ），而 conda_file 相依性會安裝在基底映射之上。
  • code_configuration - 在部署期間，評分模型的 Python 來源等本機檔案會從開發環境上傳。

如需關於 YAML 結構描述的詳細資訊，請參閱線上端點 YAML 參考。

注意

若要使用 Kubernetes 端點，而不是以受控在線端點作為計算目標：

  1. 使用 Azure Machine Learning 工作室建立 Kubernetes 叢集做為計算目標，並將其連結至 Azure Machine Learning 工作區。
  2. 使用端點 YAML 以 Kubernetes 為目標，而不是受控端點 YAML。 您必須編輯 YAML，將的值 compute 變更為已註冊計算目標的名稱。 您可以使用此 deployment.yaml ，其具有適用於 Kubernetes 部署的其他屬性。

本文中用於受控在線端點的所有命令也適用於 Kubernetes 端點，但下列不適用於 Kubernetes 端點的功能除外：

瞭解評分指令碼

提示

適用於線上端點的評分指令碼格式，與先前版本的 CLI 和 Python SDK 中使用的格式相同。

中指定的 code_configuration.scoring_script 評分腳本必須具有函 init() 式和函 run() 式。

此範例使用 score.py file：score.py

import os
import logging
import json
import numpy
import joblib


def init():
    """
    This function is called when the container is initialized/started, typically after create/update of the deployment.
    You can write the logic here to perform init operations like caching the model in memory
    """
    global model
    # AZUREML_MODEL_DIR is an environment variable created during deployment.
    # It is the path to the model folder (./azureml-models/$MODEL_NAME/$VERSION)
    # Please provide your model's folder name if there is one
    model_path = os.path.join(
        os.getenv("AZUREML_MODEL_DIR"), "model/sklearn_regression_model.pkl"
    )
    # deserialize the model file back into a sklearn model
    model = joblib.load(model_path)
    logging.info("Init complete")


def run(raw_data):
    """
    This function is called for every invocation of the endpoint to perform the actual scoring/prediction.
    In the example we extract the data from the json input and call the scikit-learn model's predict()
    method and return the result back
    """
    logging.info("model 1: request received")
    data = json.loads(raw_data)["data"]
    data = numpy.array(data)
    result = model.predict(data)
    logging.info("Request processed")
    return result.tolist()

初始化或啟動容器時，會呼叫 init() 函式。 初始化作業通常會在建立或更新部署後立即執行。 函 init 式是寫入全域初始化作業的邏輯位置，例如在記憶體中快取模型（如此 score.py 檔案所示）。

每次叫用端點時都會呼叫 函 run() 式，並執行實際的評分和預測。 在此 score.py 檔案中，函run()式會從 JSON 輸入擷取數據、呼叫 scikit-learn 模型的 predict() 方法，然後傳回預測結果。

使用本機端點在本機部署和偵錯

強烈建議您在本機測試您的端點，以在部署至 Azure 之前驗證和偵錯您的程式代碼和組態。 Azure CLI 和 Python SDK 支援本機端點和部署，Azure Machine Learning 工作室和 ARM 範本則不支援。

若要在本機部署，就必須安裝和執行 Docker 引擎。 Docker 引擎通常會在電腦啟動時啟動。 若未啟動，您可針對 Docker 引擎進行疑難排解。

提示

您可以使用 Azure Machine Learning 推斷 HTTP 伺服器 Python 套件，在沒有 Docker 引擎的情況下於本機偵錯評分指令碼。 使用推斷伺服器進行偵錯可協助您先偵錯評分指令碼再部署至本機端點，以在不受部署容器設定影響的情況下進行偵錯。

如需在部署至 Azure 之前在本機偵錯在線端點的詳細資訊，請參閱 在線端點偵錯。

在本機部署模型

先建立端點。 (選擇性) 針對本機端點，您可以跳過此步驟，並直接在下一個步驟中建立部署，這會接著建立必要的中繼資料。 在本機部署模型適用於開發和測試用途。

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

現在，請在端點下方建立名為 blue 的部署。

az ml online-deployment create --local -n blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml

--local 旗標會指示 CLI 在 Docker 環境中部署端點。

提示

使用 Visual Studio Code 在本機測試和偵錯端點。 如需詳細資訊，請參閱在 Visual Studio Code 中從本機偵錯線上端點。

確認本機部署成功

檢查部署狀態，以查看是否已部署模型，而不會發生錯誤：

az ml online-endpoint show -n $ENDPOINT_NAME --local

輸出應如下列 JSON 所示： provisioning_state 是 Succeeded。

{
  "auth_mode": "key",
  "location": "local",
  "name": "docs-endpoint",
  "properties": {},
  "provisioning_state": "Succeeded",
  "scoring_uri": "http://localhost:49158/score",
  "tags": {},
  "traffic": {}
}

下表包含 provisioning_state 的可能值：

值 Description
建立中 正在建立資源。
更新中 正在更新資源。
刪除中 正在刪除資源。
已成功 建立/更新作業成功。
失敗 建立/更新/刪除作業失敗。

使用您的模型叫用本機端點以評分資料

使用 命令叫用 invoke 端點來評分模型，並傳遞儲存在 JSON 檔案中的查詢參數：

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

若您想要使用 REST 用戶端 (例如 curl)，您必須具有評分 URI。 如要取得評分 URI，請執行 az ml online-endpoint show --local -n $ENDPOINT_NAME。 在傳回的資料中，尋找 scoring_uri 屬性。

檢閱記錄以取得叫用作業的輸出

在範例 score.py 檔案中，run() 方法會將某些輸出記錄至主控台。

您可以使用 get-logs 命令來檢視此輸出：

az ml online-deployment get-logs --local -n blue --endpoint $ENDPOINT_NAME

將線上端點部署至 Azure

接下來，將線上端點部署至 Azure。 最佳做法是生產環境，建議您註冊您將在部署中使用的模型和環境。

註冊您的模型和環境

建議您在部署至 Azure 之前先註冊模型和環境，以便在部署期間指定其已註冊的名稱和版本。 註冊您的資產可讓您重複使用資產，而不需要在每次建立部署時上傳它們，進而增加重現性和可追蹤性。

注意

不同於部署至 Azure，本機部署不支援使用已註冊的模型和環境。 相反地，本機部署會使用本機模型檔案，並且只使用具有本機檔案的環境。 若要部署至 Azure，您可以使用本機或已註冊的資產（模型和環境）。 在本文的這一節中，部署至 Azure 會使用已註冊的資產，但您可以選擇改用本機資產。 如需上傳本機檔案以用於本機部署的部署組態範例，請參閱 設定部署。

若要註冊模型和環境，請使用 表單 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。

  1. 建立模型的 YAML 定義：

    $schema: https://azuremlschemas.azureedge.net/latest/model.schema.json
name: my-model
path: ../../model-1/model/

  2. 註冊模型：

    az ml model create -n my-model -v 1 -f ./model.yaml

  3. 建立環境的 YAML 定義：

    $schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json
name: my-env
image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
conda_file: ../../model-1/environment/conda.yaml

  4. 註冊環境：

    az ml environment create -n my-env -v 1 -f ./environment.yaml

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

設定使用已註冊資產的部署

您的部署組態會使用您想要部署的已註冊模型和已註冊的環境。

在您的部署定義中使用已註冊的資產（模型和環境）。 下列代碼段顯示檔案 endpoints/online/managed/sample/blue-deployment-with-registered-assets.yml ，其中包含設定部署所需的所有輸入：

blue-deployment-with-registered-assets.yml

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-endpoint
model: azureml:my-model:1
code_configuration:
  code: ../../model-1/onlinescoring/
  scoring_script: score.py
environment: azureml:my-env:1
instance_type: Standard_DS3_v2
instance_count: 1

使用不同的 CPU 和 GPU 執行個體類型和映像

您可以在部署定義中針對本機部署和部署至 Azure 指定 CPU 或 GPU 實例類型和映像。

您在 blue-deployment-with-registered-assets.yml 檔案中的部署定義使用一般用途類型Standard_DS3_v2實例和非 GPU Docker 映射 mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest。 針對 GPU 計算，請選擇 GPU 計算類型 SKU 和 GPU Docker 映像。

如需支援的一般用途和 GPU 執行個體類型，請參閱支援受控線上端點的 VM SKU。 如需 Azure Machine Learning CPU 和 GPU 基礎映像的清單，請參閱Azure Machine Learning 基礎映像 (英文)。

注意

若要使用 Kubernetes，而不是受控端點作為計算目標，請參閱 Kubernetes 計算目標簡介。

接下來，將線上端點部署至 Azure。

部署至 Azure

  1. 在 Azure 雲端中建立端點。

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

  2. 在端點下建立名為 blue 的部署。

    az ml online-deployment create -name blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment-with-registered-assets.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" 。

若要對部署中的錯誤進行偵錯，請參閱 針對在線端點部署進行疑難解答。

檢查端點的狀態

  1. show使用 命令，在 中provisioning_state顯示端點和部署的資訊：

    az ml online-endpoint show -n $ENDPOINT_NAME

  2. 使用 list 命令，以資料表格式列出工作區中的所有端點：

    az ml online-endpoint list --output table

檢查線上部署的狀態

檢查記錄查看是否已部署模型，且未發生錯誤。

  1. 若要查看容器的記錄輸出，請使用下列 CLI 命令：

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

    根據預設，系統會從推斷伺服器容器中提取記錄。 若要查看儲存體初始設定式容器中的記錄，請新增 --container storage-initializer 旗標。 如需部署記錄的詳細資訊，請參閱取得容器記錄。

使用模型叫用端點以評分資料

  1. invoke使用您選擇的指令或 REST 用戶端來叫用端點並評分一些資料：

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

  2. 取得用來向端點驗證的金鑰：

    提示

    您可以將 Microsoft Entra 安全性主體指派給允許 Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/action 和 Microsoft.MachineLearningServices/workspaces/onlineEndpoints/listkeys/action 的自訂角色，藉以控制哪些主體可取得驗證金鑰。 如需管理工作區授權的詳細資訊，請參閱管理 Azure 機器學習 工作區的存取權。

    ENDPOINT_KEY=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -o tsv --query primaryKey)

  3. 使用 curl 來評分數據。

    SCORING_URI=$(az ml online-endpoint show -n $ENDPOINT_NAME -o tsv --query scoring_uri)

curl --request POST "$SCORING_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --data @endpoints/online/model-1/sample-request.json

    請注意，您會使用 show 和 get-credentials 命令來取得驗證認證。 另請注意，您使用 --query 旗標只篩選所需的屬性。 若要深入瞭解 --query 旗標，請參閱 查詢 Azure CLI 命令輸出。

  4. 如要查看叫用記錄，請再次執行 get-logs。

(選擇性) 更新部署

若您想要更新程式碼、模型或環境，請更新 YAML 檔案，然後執行 az ml online-endpoint update 命令。

注意

若您在單一 update 命令中更新執行個體計數 (以縮放部署) 以及其他模型設定 (例如程式碼、模型或環境)，系統會先執行縮放作業，然後再套用其他更新。 在生產環境中，最好是個別執行這些作業。

瞭解 update 如何運作：

  1. 開啟 online/model-1/onlinescoring/score.py 檔案。

  2. 變更 init() 函式的最後一行：在 logging.info("Init complete") 後方新增 logging.info("Updated successfully")。

  3. 儲存檔案。

  4. 執行此命令：

    az ml online-deployment update -n blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment-with-registered-assets.yml

    注意

    使用 YAML 進行更新為宣告式。 也就是說，YAML 中的變更會反映在基礎 Azure Resource Manager 資源 (端點和部署)。 宣告式方法可輔助 GitOps：所有的端點與部署變更 (甚至是 instance_count)皆會經過 YAML。

    提示

    • 您可以搭配使用泛型更新參數 (例如 --set 參數) 與 CLI update 命令，來覆寫 YAML 中的屬性，或設定特定屬性，而不需要在 YAML 檔案中傳遞這些屬性。 在開發和測試案例中，針對單一屬性使用 --set 特別有用。 例如，若要擴大第一個部署的 instance_count 值，您可以使用 --set instance_count=2 旗標。 不過，由於 YAML 並未更新，此技巧無法輔助 GitOps。
    • 不一定要指定 YAML 檔案。 例如，如果您要針對指定的部署測試不同的並行設定，則可以嘗試使用 az ml online-deployment update -n blue -e my-endpoint --set request_settings.max_concurrent_requests_per_instance=4 environment_variables.WORKER_COUNT=4 之類的命令。 這麼做會保留所有現有設定，只更新指定的參數。

  5. 由於您已修改 init() 函式 (會在建立或更新端點時執行)，因此訊息 Updated successfully 會出現在記錄中。 藉由執行下列動作來擷取記錄：

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

此 update 命令亦適用於本機部署。 使用相同的 az ml online-deployment update 命令搭配 --local 旗標。

本節中部署的更新是就地滾動更新的範例。

  • 針對受控線上端點，部署一次會將 20% 的節點更新為新的設定。 也就是說，如果部署有10個節點，則一次更新2個節點。
  • 針對 Kubernetes 在線端點，系統會反覆建立具有新組態的新部署實例，並刪除舊的部署實例。
  • 針對生產環境的使用方式，您應考慮藍綠部署，其為更新 Web 服務提供了更安全的替代方案。

(選擇性) 設定自動調整

自動調整會自動執行正確的資源量，以處理應用程式的負載。 受控線上端點透過與 Azure 監視器自動調整功能的整合，支援自動調整。 如要設定自動調整，請參閱如何自動調整線上端點。

(選擇性) 使用 Azure 監視器監視 SLA

如要根據您的 SLA 來檢視計量和設定警示，請完成監視線上端點中所述的步驟。

(選擇性) 與記錄分析整合

CLI 的 get-logs 命令或 SDK 的 get_logs 方法只會從自動選取的執行個體提供過去數百行的記錄。 不過，記錄分析會提供一種方式來永久儲存和分析記錄。 如需使用記錄功能的詳細資訊，請參閱監視線上端點。

刪除端點和部署

刪除端點及其所有基礎部署：

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

相關內容