自訂批次部署中的輸出

發行項
12/19/2024

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

本指南說明如何建立產生自訂輸出和檔案的部署。您有時候需要更充分掌控從批次推斷作業撰寫為輸出的內容。這些案例包括下列情況：

您必須控制在輸出中寫入預測的方式。例如，如果資料是表格式，您想要將預測附加至原始資料。
您需要以不同的檔案格式撰寫預測，其格式不同於批次部署所支援的現成格式。
您的模型是一種產生模型，無法以表格式格式寫入輸出。例如，產生映像做為輸出的模型。
您的模型會產生多個表格式檔案，而不是單一檔案。例如，考慮多個案例來執行預測的模型。

批次部署可讓您直接寫入批次部署作業的輸出，以控制作業的輸出。在本教學課程中，您將了解如何部署模型與將預測附加至原始輸入資料，用 parquet 格式寫入輸出，以進行批次推斷和寫入輸出。

關於此範例

此範例示範如何部署模型來執行批次推斷，並自訂在輸出中撰寫預測的方式。模型是以 UCI 心臟疾病資料集為基礎。資料庫包含 76 個屬性，但本例使用其中 14 個屬性。此模型會嘗試預測病患是否有心臟疾病。值為 0 (沒有) 到 1 (有) 的整數值。

模型已使用 XGBBoost 分類器進行訓練，且所有必要的前置處理都已封裝為 scikit-learn 管線，讓此模型成為從原始資料到預測的端對端管線。

本文中的範例是以 azureml-examples (英文) 存放庫內含的程式碼範例為基礎。若要在本機執行命令，而不需要複製或貼上 YAML 和其他檔案，請使用下列命令來複製存放庫，並移至您程式代碼撰寫語言的資料夾：

Azure CLI
Python

git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples/cli

git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples/sdk/python

此範例的檔案位於：

cd endpoints/batch/deploy-models/custom-outputs-parquet

在 Jupyter notebook 中跟著做

您可以使用 Jupyter Notebook 來遵循此範例。在複製的存放庫中，開啟稱為 custom-output-batch.ipynb 的 notebook。

必要條件

Azure 訂用帳戶。如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。
Azure Machine Learning 工作區。若要建立工作區，請參閱管理 Azure Machine Learning 工作區。
Azure 機器學習工作區中的下列許可權：
- 若要建立或管理批次端點和部署：請使用已指派 Microsoft.MachineLearningServices/workspaces/batchEndpoints/* 許可權的擁有者、參與者或自定義角色。
- 若要在工作區資源群組中建立 Azure Resource Manager 部署：請使用已指派 Microsoft.Resources/deployments/write 工作區部署之資源群組中許可權的擁有者、參與者或自定義角色。
Azure 機器學習 CLI 或適用於 Python 的 Azure 機器學習 SDK：
- Azure CLI
- Python
執行下列命令來安裝 Azure CLI 和 mlAzure Machine Learning 的擴充功能：
```
az extension add -n ml
```
批次端點的管線元件部署是在 Azure CLI 的 ml 延伸模組 2.7 版中引進。使用 az extension update --name ml 命令來取得最新版本。
執行下列命令以安裝適用於 Python 的 Azure Machine Learning SDK：
```
pip install azure-ai-ml
```
在 SDK 1.7.0 版中引進 ModelBatchDeployment 和 PipelineComponentBatchDeployment 類別。使用 pip install -U azure-ai-ml 命令來取得最新版本。

連線到您的工作區

工作區是 Azure Machine Learning 的最上層資源。它提供集中的位置，讓您在使用 Azure 機器學習時，使用您建立的所有成品。在本節中，您會連線到要執行部署工作的工作區。

Azure CLI
Python

在下列命令中，輸入您的訂用帳戶識別碼、工作區名稱、資源組名和位置：

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

匯入必要的程式庫：

from azure.ai.ml import MLClient, Input, load_component
from azure.ai.ml.entities import BatchEndpoint, ModelBatchDeployment, ModelBatchDeploymentSettings, PipelineComponentBatchDeployment, Model, AmlCompute, Data, BatchRetrySettings, CodeConfiguration, Environment, Data
from azure.ai.ml.constants import AssetTypes, BatchDeploymentOutputAction
from azure.ai.ml.dsl import pipeline
from azure.identity import DefaultAzureCredential

設定工作區詳細資料，並取得工作區的控制代碼：

在下列命令中，輸入您的訂用帳戶識別碼、資源群組名稱和工作區名稱：

subscription_id = "<subscription>"
resource_group = "<resource-group>"
workspace = "<workspace>"

ml_client = MLClient(DefaultAzureCredential(), subscription_id, resource_group, workspace)

使用自訂輸出建立批次部署

在此範例中，您將建立可直接寫入批次部署作業之輸出資料夾的部署。部署會使用此功能來寫入自訂 parquet 檔案。

註冊模型

您只能使用批次端點來部署已註冊的模型。在此案例中，您的存放庫已有模型的本機複本，所以你只要在工作區的登錄中發佈模型即可。如果您已註冊您嘗試部署的模型，則可以略過此步驟。

Azure CLI
Python

MODEL_NAME='heart-classifier-sklpipe'
az ml model create --name $MODEL_NAME --type "custom_model" --path "model"

model_name = "heart-classifier-sklpipe"
model_description = "A heart condition classifier trained with XGBoosts and Scikit-Learn for feature processing."
model_local_path = "model"

model = ml_client.models.create_or_update(
    Model(
        name=model_name,
        path=model_local_path,
        type=AssetTypes.CUSTOM_MODEL,
        tags={"framework": "scikit-learn", "estimator": "xgboost"},
    )
)

建立評分指令碼

您需要建立評分指令碼，讀取批次部署所提供的輸入資料，然後傳回模型的分數。您也會直接寫入作業的輸出資料夾。總而言之，建議的評分指令碼如下所示：

以 CSV 檔案的形式讀取輸入資料。
在輸入資料上執行 MLflow 模型 predict 函式。
將預測附加至 pandas.DataFrame，以及輸入資料。
將資料寫入與輸入檔案相同名稱的檔案，但格式為 parquet。

code/batch_driver.py

import os
import pickle
import glob
import pandas as pd
from pathlib import Path
from typing import List


def init():
    global model
    global output_path

    # AZUREML_MODEL_DIR is an environment variable created during deployment
    # It is the path to the model folder
    # Please provide your model's folder name if there's one:
    output_path = os.environ["AZUREML_BI_OUTPUT_PATH"]
    model_path = os.environ["AZUREML_MODEL_DIR"]
    model_file = glob.glob(f"{model_path}/*/*.pkl")[-1]

    with open(model_file, "rb") as file:
        model = pickle.load(file)


def run(mini_batch: List[str]):
    for file_path in mini_batch:
        data = pd.read_csv(file_path)
        pred = model.predict(data)

        data["prediction"] = pred

        output_file_name = Path(file_path).stem
        output_file_path = os.path.join(output_path, output_file_name + ".parquet")
        data.to_parquet(output_file_path)

    return mini_batch

備註：

請注意環境變數 AZUREML_BI_OUTPUT_PATH 如何用來存取部署作業的輸出路徑。
init() 函式會填入稱為 output_path 的全域變數，稍後可用來知道要寫入的位置。
run 方法會傳回已處理檔案的清單。 run 函式必須傳回 list 或 pandas.DataFrame 物件。

警告

請注意，所有批次執行程式都會同時具有此路徑的寫入權限。這表示您必須考慮並行。在此情況下，確保每個執行程式都會使用輸入檔案名稱做為輸出資料夾的名稱，以寫入自己的檔案。

建立端點

您現在會建立名為 heart-classifier-batch 的批次端點以部署模型。

決定端點的名稱。端點名稱會出現在與端點相關聯的 URI 中；因此， 批次端點名稱在 Azure 區域內必須不重複。例如，westus2 中只能有一個名稱為 mybatchendpoint 的批次端點。
- Azure CLI
- Python
在此情況下，將端點的名稱放在變數中，方便您稍後參考。
```
ENDPOINT_NAME="heart-classifier-custom"
```
在此情況下，將端點的名稱放在變數中，方便您稍後參考。
```
endpoint_name = "heart-classifier-custom"
```

設定批次端點。

Azure CLI
Python

下列 YAML 檔案定義了批次端點：

endpoint.yml

$schema: https://azuremlschemas.azureedge.net/latest/batchEndpoint.schema.json
name: heart-classifier-batch
description: A heart condition classifier for batch inference
auth_mode: aad_token

endpoint = BatchEndpoint(
    name=endpoint_name,
    description="A heart condition classifier for batch inference",
)

建立端點：

Azure CLI
Python

az ml batch-endpoint create -n $ENDPOINT_NAME -f endpoint.yml

ml_client.batch_endpoints.begin_create_or_update(endpoint).result()

建立部署

請遵循後續步驟，使用先前的評分指令碼來建立部署：

先建立可執行評分指令碼的環境：

Azure CLI
Python

Azure Machine Learning CLI 不需要額外的步驟。環境定義會包含在部署檔案中。

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

取得對環境的參考：

environment = Environment(
    name="batch-mlflow-xgboost",
    conda_file="environment/conda.yaml",
    image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest",
)

建立部署。請注意，output_action 現在是設為 SUMMARY_ONLY。

注意

此範例假設您有一個名為 batch-cluster 的計算叢集。請據此變更名稱。

Azure CLI
Python

若要在已建立的端點下建立新部署，請建立 YAML 設定，如下所示。您可以檢查完整的批次端點 YAML 結構描述，以取得額外的屬性。

$schema: https://azuremlschemas.azureedge.net/latest/modelBatchDeployment.schema.json
endpoint_name: heart-classifier-batch
name: classifier-xgboost-custom
description: A heart condition classifier based on XGBoost and Scikit-Learn pipelines that append predictions on parquet files.
type: model
model: azureml:heart-classifier-sklpipe@latest
environment:
  name: batch-mlflow-xgboost
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
  conda_file: environment/conda.yaml
code_configuration:
  code: code
  scoring_script: batch_driver.py
compute: azureml:batch-cluster
resources:
  instance_count: 2
settings:
  max_concurrency_per_instance: 2
  mini_batch_size: 2
  output_action: summary_only
  retry_settings:
    max_retries: 3
    timeout: 300
  error_threshold: -1
  logging_level: info

接著，使用下列命令建立部署：

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

若要在建立的端點下建立新的部署，請使用下列指令碼：

deployment = ModelBatchDeployment(
    name="classifier-xgboost-custom",
    description="A heart condition classifier based on XGBoost which writes outputs in parquet format.",
    endpoint_name=endpoint.name,
    model=model,
    environment=environment,
    code_configuration=CodeConfiguration(
        code="code",
        scoring_script="batch_driver.py",
    ),
    compute=compute_name,
    settings=ModelBatchDeploymentSettings(
        mini_batch_size=2,
        instance_count=2,
        max_concurrency_per_instance=2,
        output_action=BatchDeploymentOutputAction.SUMMARY_ONLY,
        retry_settings=BatchRetrySettings(max_retries=3, timeout=300),
        logging_level="info",
    ),
)

接著，使用下列命令建立部署：

ml_client.batch_deployments.begin_create_or_update(deployment).result()

此時，我們的批次端點已可供使用。

測試部署

為了測試您的端點，請使用此存放庫中且可與模型搭配使用的未標記資料作為範例。批次端點只能處理位於雲端且可從 Azure Machine Learning 工作區存取的資料。在此範例中，您將其上傳至 Azure Machine Learning 資料存放區。您將建立可用來叫用端點以進行評分的資料資產。不過，請注意，批次端點可接受可放置在多個位置類型的資料。

使用儲存體帳戶中的資料叫用端點：
- Azure CLI
- Python
```
JOB_NAME = $(az ml batch-endpoint invoke --name $ENDPOINT_NAME --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data --query name -o tsv)
```
注意

公用程式 jq 可能不會在每次安裝時進行安裝。您可以在 GitHub 上取得指示。
提示

叫用端點時，inputs 和 input 參數之間有何差異？

一般而言，您可以使用字典 inputs = {} 參數搭配 invoke 方法，為批次端點提供任意數目的必要輸入，其中包含模型部署或管線部署。

就模型部署而言，您可以使用 input 參數作為較簡易的方式，以指定部署的輸入資料位置。這種方法的運作方式是，模型部署一律只要一個資料輸入。

設定輸入：
```
input = Input(
    type=AssetTypes.URI_FOLDER,
    path="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data",
)
```
建立作業：
```
job = ml_client.batch_endpoints.invoke(
    endpoint_name=endpoint.name, deployment_name=deployment.name, input=input
)
```
命令傳回時，就會立即啟動批次工作。您可以監視工作的狀態，直到工作完成為止：
- Azure CLI
- Python
```
az ml job show -n $JOB_NAME --web
```
```
ml_client.jobs.get(job.name)
```

分析輸出

作業會產生名為 score 的具名輸出，其中會放置所有產生的檔案。由於您直接寫入目錄，每個輸入檔各有一個檔案，因此您可以預期具有相同數目的檔案。在此特定範例中，將輸出檔案命名為與輸入相同，但它們會有 parquet 副檔名。

注意

請注意，predictions.csv 也會包含在輸出資料夾中。此檔案包含已處理檔案的摘要。

您可以使用工作名稱來下載工作的結果：

Azure CLI
Python

若要下載預測，請使用下列命令：

az ml job download --name $JOB_NAME --output-name score --download-path ./

ml_client.jobs.download(name=scoring_job.name, download_path=".", output_name="score")

下載檔案之後，您可以使用慣用的工具來開啟。下列範例會使用 Pandas 資料框架載入預測。

import pandas as pd
import glob

output_files = glob.glob("named-outputs/score/*.parquet")
score = pd.concat((pd.read_parquet(f) for f in output_files))
score

輸出如下所示：

年齡	sex	...	thal	prediction
63	1	...	fixed	0
67	1	...	一般	1
67	1	...	reversible	0
37	1	...	一般	0

執行下列程式碼，以刪除 Batch 端點和所有基礎部署。不會刪除批次評分作業。

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

執行下列程式碼，以刪除 Batch 端點和所有基礎部署。不會刪除批次評分作業。

ml_client.batch_endpoints.begin_delete(endpoint_name).result()

共用方式為

自訂批次部署中的輸出

關於此範例

在 Jupyter notebook 中跟著做

必要條件

連線到您的工作區

使用自訂輸出建立批次部署

註冊模型

建立評分指令碼

建立端點

建立部署

測試部署

分析輸出

清除資源

意見反應

其他資源

共用方式為

自訂批次部署中的輸出

關於此範例

在 Jupyter notebook 中跟著做

必要條件

連線到您的工作區

使用自訂輸出建立批次部署

註冊模型

建立評分指令碼

建立端點

建立部署

測試部署

分析輸出

清除資源

相關內容

意見反應

其他資源