共用方式為

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

  • 發行項

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

在本文中，您將瞭解如何將模型部署至線上端點，以用於即時推斷。 首先，您將在本機電腦上部署模型，以針對任何錯誤執行偵錯。 接著，您將在 Azure 中部署及測試模型、檢視部署記錄，以及監視服務等級協定 (SLA)。 在本文結束時，您會擁有可用於即時推斷的可調整 HTTPS/REST 端點。

線上端點是用於即時推斷的端點。 線上端點有兩種類型：受控線上端點和 Kubernetes 線上端點。 若要進一步瞭解端點，以及受控線上端點與 Kubernetes 線上端點之間的差異，請參閱什麼是 Azure Machine Learning 端點？

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

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

必要條件

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

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

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

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

  • 確保已為部署分配足夠的虛擬機器 (VM) 配額。 Azure Machine Learning 會保留 20% 的計算資源，以在部分 VM SKU 上執行升級。 例如，如果您在部署中要求 10 個執行個體，則必須為 VM SKU 的每個核心數量預留 12 個配額。 若無法預留額外計算資源，便會發生錯誤。 部分 VM SKU 不必額外保留配額。 如需配額配置的詳細資訊，請參閱部署的虛擬機器配額配置。

  • 另一方面，您可以在一定時間內使用 Azure Machine Learning 提供的共用配額集區。 Azure Machine Learning 提供共用配額集區，供不同區域的使用者根據可用性，在有限時間內存取配額並執行測試。 當使用工作室將 Llama-2、Phi、Nemotron、Mistral、Dolly 和 Deci-DeciLM 模型從模型目錄部署到受控線上端點時，您可暫時存取 Azure Machine Learning 共用配額集區，以便進行測試。 如需共用配額集區的詳細資訊，請參閱 Azure Machine Learning 共用配額。

準備您的系統

設定環境變數

如果您尚未設定 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 新增至命令。 不過，此選項會停止以互動方式顯示部署狀態。

    重要

    用於建立部署之程式碼 az ml online-deployment create 中的 --all-traffic 旗標，會將 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 Machine Learning 的存取權。

    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

相關內容