在批次端點中部署用於評分的模型
適用於:Azure CLI ml 延伸模組 v2 (目前)Python SDK azure-ai-ml v2 (目前)
Batch 端點提供一個方便的方式,可部署在大量數據上執行推斷的模型。 這些端點可簡化裝載模型以進行批次評分的程式,讓您的焦點在於機器學習,而不是基礎結構。
在下列情況下,使用批次端點進行模型部署:
- 您有耗費較長時間才能執行推斷的昂貴模型。
- 您必須對分散在多個檔案中的大量數據執行推斷。
- 您沒有低延遲需求。
- 您可以利用平行處理。
在本文中,您會使用批次端點來部署機器學習模型,以解決傳統 MNIST(修改的國家標準與技術研究所)數位辨識問題。 接著,您部署的模型會針對大量數據執行批次推斷,在此案例中為圖像檔。 您一開始會建立使用 Torch 建立之模型的批次部署。 此部署會成為端點中的預設部署。 稍後,您會 建立使用 TensorFlow (Keras) 所建立模式的第二個部署 、測試第二個部署,然後將它設定為端點的預設部署。
若要遵循在本機執行本文中命令所需的程式代碼範例和檔案,請參閱 複製範例存放庫 一節。 程序代碼範例和檔案包含在 azureml-examples 存放庫中。
必要條件
在您遵循本文中的步驟之前,請確定您具備下列必要條件:
Azure 訂用帳戶。 如果您沒有 Azure 訂用帳戶,請在開始前建立免費帳戶。 試用免費或付費版本的 Azure Machine Learning。
Azure Machine Learning 工作區。 如果您沒有工作區,請使用如何管理工作區一文中的步驟來建立。
若要執行下列工作,請確定您在工作區中具有這些許可權:
若要建立/管理批次端點和部署:使用擁有者角色、參與者角色或允許
Microsoft.MachineLearningServices/workspaces/batchEndpoints/*
的自定義角色。若要在工作區資源群組中建立ARM部署:使用擁有者角色、參與者角色,或允許在部署工作區的資源群組中自定義角色
Microsoft.Resources/deployments/write
。
您必須安裝下列軟體,才能使用 Azure 機器學習:
Azure CLI 和適用於 Azure Machine Learning 的
ml
擴充功能。az extension add -n ml
複製範例存放庫
本文中的範例是以 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 部署。 如需批次端點的詳細資訊,請參閱 什麼是批次端點?。
提示
其中一個批次部署可作為端點的預設部署。 叫用端點時,預設部署會執行實際的批次評分。 如需批次端點和部署的詳細資訊,請參閱 批次端點和批次部署。
將端點命名為 。 端點的名稱在 Azure 區域內必須是唯一的,因為名稱包含在端點的 URI 中。 例如,
westus2
中只能有一個名稱為mybatchendpoint
的批次端點。設定批次端點
下列 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
要包含在端點中的標籤。 這個屬性為選擇性。 建立端點:
建立 Batch 部署
模型部署是一組用於裝載實際執行推斷的模型所需的資源。 若要建立批次模型部署,您需要下列專案:
- 工作區中已註冊的模型
- 要評分模型的程序代碼
- 已安裝模型相依性的環境
- 預先建立的計算和資源設定
首先,註冊要部署的模型—熱門數字辨識問題的火炬模型(MNIST)。 批次部署只能部署在工作區中註冊的模型。 如果想要部署的模型已註冊,您可以略過此步驟。
提示
模型會與部署相關聯,而不是與端點相關聯。 這表示,只要不同的模型(或模型版本)部署在不同的部署中,單一端點可以在相同的端點下提供不同的模型(或模型版本)。
現在可以建立評分指令碼了。 批次部署需要評分指令碼,以指出應該如何執行指定的模型,以及必須如何處理輸入資料。 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)
建立您執行批次部署所在的環境。 環境應該包含批次端點所需的套件
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
警告
批次部署不支援策展環境。 您必須指定自己的環境。 您一律可以使用策展環境的基礎映像作為自己的映像以簡化程序。
建立部署定義
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_row
output_action
的 Batch 評分輸出檔案名稱。settings.retry_settings.max_retries
[選用] 失敗的 scoring_script
run()
嘗試次數。settings.retry_settings.timeout
[選用] 用於評分迷你 Batch 的 scoring_script
run()
的逾時 (以秒為單位)。settings.error_threshold
[選用] 應忽略的輸入檔案評分失敗數目。 如果整個輸入的錯誤計數超過此值,Batch 評分作業便會終止。 此範例會使用 -1
,這表示會允許任何數目的失敗,而不需要終止 Batch 評分作業。settings.logging_level
[選用] 記錄詳細程度。 增加詳細程度中的值為:WARNING、INFO 和 DEBUG。 settings.environment_variables
[選用] 要針對每個批次評分作業設定的環境變數名稱-值組的字典。 建立部署:
執行下列程式代碼以在批次端點下建立批次部署,並將其設定為預設部署。
az ml batch-deployment create --file deployment-torch/deployment.yml --endpoint-name $ENDPOINT_NAME --set-default
提示
--set-default
參數會將新建立的部署設定為端點的預設部署。 這是建立新端點預設部署的便利方式,特別是在第一次建立部署時。 在生產案例的最佳做法中,您可能想要建立新的部署,而不將它設定為預設值。 確認部署如預期般運作,然後稍後更新預設部署。 如需實作此程式的詳細資訊,請參閱 部署新的模型 一節。檢查批次端點和部署詳細資料。
執行批次端點和存取結果
叫用批次端點會觸發批次評分作業。 作業 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 中檢視評分結果:
執行下列程序代碼,以在 Azure Machine Learning 工作室 中開啟批次評分作業。
invoke
的回應中也包含了作業的工作室連結,做為interactionEndpoints.Studio.endpoint
的值。az ml job show -n $JOB_NAME --web
在執行的圖表中,選取
batchscoring
步驟。選取 [輸出 + 記錄] 索引標籤,然後選取 [顯示資料輸出]。
從 [資料輸出] 中,選取圖示以開啟儲存體總管。
儲存體總管中的評分結果類似下列範例頁面:
設定輸出位置
根據預設,批次評分結果會儲存在工作區的預設 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 問題。
新增第二個部署
建立您執行批次部署所在的環境。 在環境中包含您的程式碼執行所需的任何相依性。 您也需要新增連結庫
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]
為模型建立評分指令碼:
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)
建立部署定義
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
建立部署:
測試非預設 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