在批次端點中部署用於評分的模型

  • 發行項

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

Batch 端點提供一個方便的方式，可部署在大量數據上執行推斷的模型。 這些端點可簡化裝載模型以進行批次評分的程式，讓您的焦點在於機器學習，而不是基礎結構。

在下列情況下，使用批次端點進行模型部署：

  • 您有耗費較長時間才能執行推斷的昂貴模型。
  • 您必須對分散在多個檔案中的大量數據執行推斷。
  • 您沒有低延遲需求。
  • 您可以利用平行處理。

在本文中，您會使用批次端點來部署機器學習模型，以解決傳統 MNIST（修改的國家標準與技術研究所）數位辨識問題。 接著，您部署的模型會針對大量數據執行批次推斷，在此案例中為圖像檔。 您一開始會建立使用 Torch 建立之模型的批次部署。 此部署會成為端點中的預設部署。 稍後，您會 建立使用 TensorFlow （Keras） 所建立模式的第二個部署 、測試第二個部署，然後將它設定為端點的預設部署。

若要遵循在本機執行本文中命令所需的程式代碼範例和檔案，請參閱 複製範例存放庫 一節。 程序代碼範例和檔案包含在 azureml-examples 存放庫中。

必要條件

在您遵循本文中的步驟之前，請確定您具備下列必要條件：

複製範例存放庫

本文中的範例是以 azureml-examples (英文) 存放庫內含的程式碼範例為基礎。 若要在本機執行命令，而不需要複製/貼上 YAML 和其他檔案，請複製存放庫，然後將目錄變更為該資料夾：

git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples/cli/endpoints/batch/deploy-models/mnist-classifier

準備您的系統

連線到您的工作區

首先，連線到您將在其中工作的 Azure Machine Learning 工作區。

如果您尚未設定 Azure CLI 的預設值，請儲存您的預設設定。 若要避免多次傳入訂用帳戶、工作區、資源群組和位置的值，請執行下列程序代碼：

az account set --subscription <subscription>
az configure --defaults workspace=<workspace> group=<resource-group> location=<location>

建立計算

Batch 端點會在計算叢集上執行，並支援 Azure 機器學習 計算叢集 （AmlCompute） 和 Kubernetes 叢集。 因此，叢集是共享資源，因此，一個叢集可以裝載一或多個批次部署（如有需要，以及其他工作負載）。

建立名為 batch-cluster的計算，如下列程式代碼所示。 您可以視需要調整，並使用 azureml:<your-compute-name>來參考計算。

az ml compute create -n batch-cluster --type amlcompute --min-instances 0 --max-instances 5

注意

您目前不會支付計算費用，因為叢集會保留在 0 個節點，直到叫用批次端點並提交批次評分作業為止。 如需計算成本的詳細資訊，請參閱 管理及優化 AmlCompute 的成本。

建立批次端點

批次端點是用戶端可以呼叫以觸發批次評分作業的 HTTPS 端點。 批次評分作業是評分多個輸入的工作。 批次部署是一組計算資源，裝載模型以執行實際批次評分（或批次推斷）。 一個 Batch 端點可以有多個 Batch 部署。 如需批次端點的詳細資訊，請參閱 什麼是批次端點？。

提示

其中一個批次部署可作為端點的預設部署。 叫用端點時，預設部署會執行實際的批次評分。 如需批次端點和部署的詳細資訊，請參閱 批次端點和批次部署。

  1. 將端點命名為 。 端點的名稱在 Azure 區域內必須是唯一的，因為名稱包含在端點的 URI 中。 例如，westus2 中只能有一個名稱為 mybatchendpoint 的批次端點。

    將端點的名稱放在變數中，以便稍後輕鬆參考它。

    ENDPOINT_NAME="mnist-batch"

  2. 設定批次端點

    下列 YAML 檔案會定義批次端點。 您可以使用此檔案搭配 CLI 命令來 建立批次端點。

    endpoint.yml

    $schema: https://azuremlschemas.azureedge.net/latest/batchEndpoint.schema.json
name: mnist-batch
description: A batch endpoint for scoring images from the MNIST dataset.
tags:
  type: deep-learning

    下表描述端點的重要屬性。 如需完整的 Batch 端點 YAML 結構描述，請參閱 CLI (v2) Batch 端點 YAML 結構描述。

    關鍵 描述
    name Batch 端點的名稱。 在 Azure 區域層級必須是唯一的。
    description 批次端點的描述。 這個屬性為選擇性。
    tags 要包含在端點中的標籤。 這個屬性為選擇性。

  3. 建立端點：

    執行下列程式代碼來建立批次端點。

    az ml batch-endpoint create --file endpoint.yml  --name $ENDPOINT_NAME

建立 Batch 部署

模型部署是一組用於裝載實際執行推斷的模型所需的資源。 若要建立批次模型部署，您需要下列專案：

  • 工作區中已註冊的模型
  • 要評分模型的程序代碼
  • 已安裝模型相依性的環境
  • 預先建立的計算和資源設定

  1. 首先，註冊要部署的模型—熱門數字辨識問題的火炬模型（MNIST）。 批次部署只能部署在工作區中註冊的模型。 如果想要部署的模型已註冊，您可以略過此步驟。

    提示

    模型會與部署相關聯，而不是與端點相關聯。 這表示，只要不同的模型（或模型版本）部署在不同的部署中，單一端點可以在相同的端點下提供不同的模型（或模型版本）。

    MODEL_NAME='mnist-classifier-torch'
az ml model create --name $MODEL_NAME --type "custom_model" --path "deployment-torch/model"

  2. 現在可以建立評分指令碼了。 批次部署需要評分指令碼，以指出應該如何執行指定的模型，以及必須如何處理輸入資料。 Batch 端點支援在 Python 中建立的腳本。 在此情況下，您會部署模型，以讀取代表數位的影像檔，並輸出對應的數位。 評分指令碼如下所示：

    注意

    針對 MLflow 模型，Azure Machine Learning 會自動產生評分指令碼，因此您不需要提供評分指令碼。 如果您的模型是 MLflow 模型，您可以略過此步驟。 如需批次端點如何使用 MLflow 模型的詳細資訊，請參閱在批次部署中使用 MLflow 模型一文。

    警告

    如果您要在批次端點下部署自動化機器學習 （AutoML） 模型，請注意 AutoML 提供的評分腳本僅適用於在線端點，且並非針對批次執行而設計。 如需如何為您的批次部署建立評分腳本的資訊，請參閱 撰寫批次部署的評分腳本。

    deployment-torch/code/batch_driver.py

    import os
import pandas as pd
import torch
import torchvision
import glob
from os.path import basename
from mnist_classifier import MnistClassifier
from typing import List


def init():
    global model
    global device

    # AZUREML_MODEL_DIR is an environment variable created during deployment
    # It is the path to the model folder
    model_path = os.environ["AZUREML_MODEL_DIR"]
    model_file = glob.glob(f"{model_path}/*/*.pt")[-1]

    model = MnistClassifier()
    model.load_state_dict(torch.load(model_file))
    model.eval()

    device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")


def run(mini_batch: List[str]) -> pd.DataFrame:
    print(f"Executing run method over batch of {len(mini_batch)} files.")

    results = []
    with torch.no_grad():
        for image_path in mini_batch:
            image_data = torchvision.io.read_image(image_path).float()
            batch_data = image_data.expand(1, -1, -1, -1)
            input = batch_data.to(device)

            # perform inference
            predict_logits = model(input)

            # Compute probabilities, classes and labels
            predictions = torch.nn.Softmax(dim=-1)(predict_logits)
            predicted_prob, predicted_class = torch.max(predictions, axis=-1)

            results.append(
                {
                    "file": basename(image_path),
                    "class": predicted_class.numpy()[0],
                    "probability": predicted_prob.numpy()[0],
                }
            )

    return pd.DataFrame(results)

  3. 建立您執行批次部署所在的環境。 環境應該包含批次端點所需的套件 azureml-core 和 azureml-dataset-runtime[fuse]，以及程式代碼執行所需的任何相依性。 在此情況下，已在檔案中 conda.yaml 擷取相依性：

    deployment-torch/environment/conda.yaml

    name: mnist-env
channels:
  - conda-forge
dependencies:
  - python=3.8.5
  - pip<22.0
  - pip:
    - torch==1.13.0
    - torchvision==0.14.0
    - pytorch-lightning
    - pandas
    - azureml-core
    - azureml-dataset-runtime[fuse]

    重要

    azureml-core 和 azureml-dataset-runtime[fuse] 是批次部署所需的套件，應該包含在環境相依性中。

    指定環境，如下所示：

    環境定義會以匿名環境的形式包含在部署定義本身。 您將在部署的下列幾行中看到：

    environment:
  name: batch-torch-py38
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
  conda_file: environment/conda.yaml

    警告

    批次部署不支援策展環境。 您必須指定自己的環境。 您一律可以使用策展環境的基礎映像作為自己的映像以簡化程序。

  4. 建立部署定義

    deployment-torch/deployment.yml

    $schema: https://azuremlschemas.azureedge.net/latest/modelBatchDeployment.schema.json
name: mnist-torch-dpl
description: A deployment using Torch to solve the MNIST classification dataset.
endpoint_name: mnist-batch
type: model
model:
  name: mnist-classifier-torch
  path: model
code_configuration:
  code: code
  scoring_script: batch_driver.py
environment:
  name: batch-torch-py38
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
  conda_file: environment/conda.yaml
compute: azureml:batch-cluster
resources:
  instance_count: 1
settings:
  max_concurrency_per_instance: 2
  mini_batch_size: 10
  output_action: append_row
  output_file_name: predictions.csv
  retry_settings:
    max_retries: 3
    timeout: 30
  error_threshold: -1
  logging_level: info

    下表描述批次部署的主要屬性。 如需完整 Batch 部署 YAML 結構描述，請參閱 CLI (v2) Batch 部署 YAML 結構描述。

    關鍵 描述
    name 部署的名稱。
    endpoint_name 要在其下建立部署的端點名稱。
    model 用於 Batch 評分的模型。 此範例會使用 path 定義內嵌模型。 此定義可讓模型檔案自動上傳並註冊為自動產生的名稱和版本。 如需更多選項， 請參閱模型架構 。 作為生產案例的最佳做法，您應該個別建立模型並在這裡參考該模型。 若要參考現有的模型，請使用 azureml:<model-name>:<model-version> 語法。
    code_configuration.code 用於模型評分的所有 Python 原始程式碼目錄。
    code_configuration.scoring_script 目錄中的 code_configuration.code Python 檔案。 這個檔案必須有一個 init() 函式和個 run() 函式。 針對任何代價高昂或常見的準備使用 函 init() 式（例如，在記憶體中載入模型）。 init() 只會在程序開始時呼叫一次。 使用 run(mini_batch) 來為每個項目評分；mini_batch 的值為檔案路徑的清單。 run() 函式應該傳回 Pandas 資料框架或陣列。 每個傳回的元素表示 mini_batch 中輸入元素的一個成功執行。 如需如何撰寫評分腳本的詳細資訊，請參閱 瞭解評分腳本。
    environment 用來評分模型的環境。 範例會使用 conda_file 和 image 定義內嵌環境。 conda_file 相依性將安裝在 image 上。 系統會以自動產生的名稱和版本註冊環境。 如需更多選項， 請參閱環境架構 。 作為生產案例的最佳做法，您應該個別建立環境並在這裡參考該環境。 若要參考現有的環境，請使用 azureml:<environment-name>:<environment-version> 語法。
    compute 要執行 Batch 評分的計算。 此範例會使用 batch-cluster 在開頭建立的 azureml:<compute-name> ，並使用 語法來參考它。
    resources.instance_count 每個 Batch 評分作業要使用的執行個體數目。
    settings.max_concurrency_per_instance [選用] 每個執行個體的平行 scoring_script 執行數目上限。
    settings.mini_batch_size [選用] scoring_script 可以在一個 run() 呼叫中處理的檔案數目。
    settings.output_action [選用] 輸出應在輸出檔案中的組織方式。 append_row 會將所有 run() 傳回的輸出結果合併成一個名為 output_file_name 的單一檔案。 summary_only 不會合併輸出結果，而且只會計算 error_threshold。
    settings.output_file_name [選用] append_rowoutput_action 的 Batch 評分輸出檔案名稱。
    settings.retry_settings.max_retries [選用] 失敗的 scoring_scriptrun() 嘗試次數。
    settings.retry_settings.timeout [選用] 用於評分迷你 Batch 的 scoring_scriptrun() 的逾時 (以秒為單位)。
    settings.error_threshold [選用] 應忽略的輸入檔案評分失敗數目。 如果整個輸入的錯誤計數超過此值，Batch 評分作業便會終止。 此範例會使用 -1，這表示會允許任何數目的失敗，而不需要終止 Batch 評分作業。
    settings.logging_level [選用] 記錄詳細程度。 增加詳細程度中的值為：WARNING、INFO 和 DEBUG。
    settings.environment_variables [選用] 要針對每個批次評分作業設定的環境變數名稱-值組的字典。

  5. 建立部署：

    執行下列程式代碼以在批次端點下建立批次部署，並將其設定為預設部署。

    az ml batch-deployment create --file deployment-torch/deployment.yml --endpoint-name $ENDPOINT_NAME --set-default

    提示

    --set-default 參數會將新建立的部署設定為端點的預設部署。 這是建立新端點預設部署的便利方式，特別是在第一次建立部署時。 在生產案例的最佳做法中，您可能想要建立新的部署，而不將它設定為預設值。 確認部署如預期般運作，然後稍後更新預設部署。 如需實作此程式的詳細資訊，請參閱 部署新的模型 一節。

  6. 檢查批次端點和部署詳細資料。

    使用 show 來檢查端點和部署詳細數據。 若要檢查 Batch 部署，請執行下列程式碼：

    DEPLOYMENT_NAME="mnist-torch-dpl"
az ml batch-deployment show --name $DEPLOYMENT_NAME --endpoint-name $ENDPOINT_NAME

執行批次端點和存取結果

叫用批次端點會觸發批次評分作業。 作業 name 會從叫用回應傳回，可用來追蹤批次評分進度。 在批次端點中執行評分模型時，您必須指定輸入資料的路徑，讓端點可以找到您想要評分的數據。 下列範例示範如何針對儲存在 Azure 儲存體帳戶中的 MNIST 資料集範例資料，啟動新的作業。

您可以使用 Azure CLI、Azure Machine Learning SDK 或 REST 端點來執行和叫用批次端點。 如需這些選項的詳細資訊，請參閱 建立批次端點的作業和輸入數據。

注意

平行處理如何運作？

批次部署會在檔案層級散發工作，這表示包含 100 個檔案、迷你批次為 10 個檔案的資料夾，會產生 10 個批次，每個批次各有 10 個檔案。 請注意，不論涉及的檔案大小為何，都會發生這種情況。 如果您的檔案太大而無法以大型迷你批次處理，建議您將檔案分割成較小的檔案，以達到較高層級的平行處理原則，或減少每個迷你批次的檔案數目。 目前，批次部署無法考慮檔案大小散發中的扭曲。

JOB_NAME=$(az ml batch-endpoint invoke --name $ENDPOINT_NAME --input https://azuremlexampledata.blob.core.windows.net/data/mnist/sample --input-type uri_folder --query name -o tsv)

批次端點支援讀取位於不同位置的檔案或資料夾。 若要深入瞭解支持的類型以及如何指定它們，請參閱 從批次端點作業存取數據。

監視批次作業執行進度

Batch 評分作業通常需要一些時間來處理整個輸入集。

下列程式碼會檢查作業狀態，並輸出 Azure Machine Learning 工作室的連結以取得進一步的詳細資料。

az ml job show -n $JOB_NAME --web

檢查批次評分結果

作業輸出會儲存在雲端記憶體、工作區的預設 Blob 記憶體或您指定的記憶體中。 若要瞭解如何變更預設值，請參閱 設定輸出位置。 下列步驟可讓您在作業完成時，在 Azure 儲存體 Explorer 中檢視評分結果：

  1. 執行下列程序代碼，以在 Azure Machine Learning 工作室 中開啟批次評分作業。 invoke 的回應中也包含了作業的工作室連結，做為 interactionEndpoints.Studio.endpoint 的值。

    az ml job show -n $JOB_NAME --web

  2. 在執行的圖表中，選取 batchscoring 步驟。

  3. 選取 [輸出 + 記錄] 索引標籤，然後選取 [顯示資料輸出]。

  4. 從 [資料輸出] 中，選取圖示以開啟儲存體總管。

    顯示檢視數據輸出位置的 Studio 螢幕快照。

    儲存體總管中的評分結果類似下列範例頁面：

    評分輸出的螢幕快照。

設定輸出位置

根據預設，批次評分結果會儲存在工作區的預設 Blob 存放區中，以作業名稱命名的資料夾內（系統產生的 GUID）。 您可以設定在叫用 Batch 端點時，儲存評分輸出的位置。

使用 output-path 可在 Azure Machine Learning 已註冊的資料存放區中設定任何資料夾。 當您指定資料夾時，--output-path 的語法與 --input 相同，也就是 azureml://datastores/<datastore-name>/paths/<path-on-datastore>/。 使用 --set output_file_name=<your-file-name> 來設定新的輸出檔案名稱。

OUTPUT_FILE_NAME=predictions_`echo $RANDOM`.csv
OUTPUT_PATH="azureml://datastores/workspaceblobstore/paths/$ENDPOINT_NAME"

JOB_NAME=$(az ml batch-endpoint invoke --name $ENDPOINT_NAME --input https://azuremlexampledata.blob.core.windows.net/data/mnist/sample --output-path $OUTPUT_PATH --set output_file_name=$OUTPUT_FILE_NAME --query name -o tsv)

警告

您必須使用唯一的輸出位置。 如果輸出檔案存在，Batch 評分作業將會失敗。

重要

不同於輸入，輸出只能儲存在 Azure 機器學習 Blob 記憶體帳戶上執行的數據存放區中。

覆寫每個作業的部署組態

當您叫用批次端點時，可以覆寫某些設定，以充分利用計算資源並改善效能。 您可以根據每個工作設定下列設定：

  • 實例計數：使用此設定來覆寫要從計算叢集要求的實例數目。 例如，針對較大量的資料輸入，您可能會想要使用更多執行個體來加速端對端 Batch 評分。
  • 迷你批次大小：使用此設定來覆寫要包含在每個迷你批次中的檔案數目。 迷你批次數目取決於輸入檔案計數總計和迷你批次大小。 較小的迷你批次大小會產生更多迷你批次。 迷你 Batch 可以平行執行，但可能會有額外的排程和叫用負荷。
  • 可以覆寫其他設定，例如 重試次數上限、 逾時和 錯誤臨界值 。 這些設定可能會影響不同工作負載的端對端批次評分時間。
JOB_NAME=$(az ml batch-endpoint invoke --name $ENDPOINT_NAME --input https://azuremlexampledata.blob.core.windows.net/data/mnist/sample --mini-batch-size 20 --instance-count 5 --query name -o tsv)

將部署新增至端點

擁有具備部署的批次端點之後，您可以繼續調整您的模型，並新增部署。 當您在相同端點下開發及部署新模型時，批次端點會繼續提供預設部署。 部署不會影響彼此。

在此範例中，您會新增第二個部署，其使用使用 Keras 和 TensorFlow 建置的模型來解決相同的 MNIST 問題。

新增第二個部署

  1. 建立您執行批次部署所在的環境。 在環境中包含您的程式碼執行所需的任何相依性。 您也需要新增連結庫 azureml-core，因為批次部署必須能夠運作。 下列環境定義具有使用 TensorFlow 執行模型所需的程式庫。

    環境定義會以匿名環境的形式包含在部署定義本身中。

    environment:
  name: batch-tensorflow-py38
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
  conda_file: environment/conda.yaml

    所使用的 conda 檔案如下所示：

    deployment-keras/environment/conda.yaml

    name: tensorflow-env
channels:
  - conda-forge
dependencies:
  - python=3.8.5
  - pip
  - pip:
    - pandas
    - tensorflow
    - pillow
    - azureml-core
    - azureml-dataset-runtime[fuse]

  2. 為模型建立評分指令碼：

    deployment-keras/code/batch_driver.py

    import os
import numpy as np
import pandas as pd
import tensorflow as tf
from typing import List
from os.path import basename
from PIL import Image
from tensorflow.keras.models import load_model


def init():
    global model

    # AZUREML_MODEL_DIR is an environment variable created during deployment
    model_path = os.path.join(os.environ["AZUREML_MODEL_DIR"], "model")

    # load the model
    model = load_model(model_path)


def run(mini_batch: List[str]) -> pd.DataFrame:
    print(f"Executing run method over batch of {len(mini_batch)} files.")

    results = []
    for image_path in mini_batch:
        data = Image.open(image_path)
        data = np.array(data)
        data_batch = tf.expand_dims(data, axis=0)

        # perform inference
        pred = model.predict(data_batch)

        # Compute probabilities, classes and labels
        pred_prob = tf.math.reduce_max(tf.math.softmax(pred, axis=-1)).numpy()
        pred_class = tf.math.argmax(pred, axis=-1).numpy()

        results.append(
            {
                "file": basename(image_path),
                "class": pred_class[0],
                "probability": pred_prob,
            }
        )

    return pd.DataFrame(results)

  3. 建立部署定義

    deployment-keras/deployment.yml

    $schema: https://azuremlschemas.azureedge.net/latest/modelBatchDeployment.schema.json
name: mnist-keras-dpl
description: A deployment using Keras with TensorFlow to solve the MNIST classification dataset.
endpoint_name: mnist-batch
type: model
model: 
  name: mnist-classifier-keras
  path: model
code_configuration:
  code: code
  scoring_script: batch_driver.py
environment:
  name: batch-tensorflow-py38
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
  conda_file: environment/conda.yaml
compute: azureml:batch-cluster
resources:
  instance_count: 1
settings:
  max_concurrency_per_instance: 2
  mini_batch_size: 10
  output_action: append_row
  output_file_name: predictions.csv

  4. 建立部署：

    執行下列程式碼，在批次端點下建立批次部署，並將其設定為預設部署。

    az ml batch-deployment create --file deployment-keras/deployment.yml --endpoint-name $ENDPOINT_NAME

    提示

    在此情況下，遺漏 --set-default 參數。 作為生產案例的最佳做法，請建立新的部署，而不將它設定為預設值。 然後確認它，並在稍後更新預設部署。

測試非預設 Batch 部署

若要測試新的非預設部署，您必須知道您要執行的部署名稱。

DEPLOYMENT_NAME="mnist-keras-dpl"
JOB_NAME=$(az ml batch-endpoint invoke --name $ENDPOINT_NAME --deployment-name $DEPLOYMENT_NAME --input https://azuremlexampledata.blob.core.windows.net/data/mnist/sample --input-type uri_folder --query name -o tsv)

請注意 --deployment-name 是用來指定要執行的部署。 此參數可讓您在不更新批次端點的預設部署的情況下，進行 invoke 非預設部署。

更新預設 Batch 部署

雖然您可以在端點內叫用特定部署，但您通常會想要叫用端點本身，並讓端點決定要使用的部署—默認部署。 您可以變更預設部署（因此，變更服務部署的模型），而不需變更與使用者叫用端點的合約。 使用下列程式代碼來更新預設部署：

az ml batch-endpoint update --name $ENDPOINT_NAME --set defaults.deployment_name=$DEPLOYMENT_NAME

刪除 Batch 端點和部署

如果您不會使用舊的批次部署，請執行下列程式代碼來刪除它。 --yes 用來確認刪除。

az ml batch-deployment delete --name mnist-torch-dpl --endpoint-name $ENDPOINT_NAME --yes

執行下列程式代碼來刪除批次端點及其所有基礎部署。 將不會刪除批次評分作業。

az ml batch-endpoint delete --name $ENDPOINT_NAME --yes

相關內容