共用方式為


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

適用於: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-coreazureml-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-coreazureml-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_fileimage 定義內嵌環境。 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