自訂批次部署中的輸出

發行項
04/07/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 的筆記本。

必要條件

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

Azure 訂用帳戶。如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。試用免費或付費版本的 Azure Machine Learning。
Azure Machine Learning 工作區。如果您沒有帳戶，請使用管理 Azure 機器學習工作區一文中的步驟來建立一個工作區。
請確定您在工作區中具有下列權限：
- 建立或管理批次端點和部署：使用允許 Microsoft.MachineLearningServices/workspaces/batchEndpoints/*的擁有者、參與者或自定義角色。
- 在工作區資源群組中建立ARM部署：使用可在部署工作區的資源群組中使用擁有 Microsoft.Resources/deployments/write 者、參與者或自定義角色。
您必須安裝下列軟體，才能使用 Azure Machine Learning：
- Azure CLI
- Python
Azure CLI 和適用於 Azure Machine Learning 的 ml 擴充功能。
```
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
```
注意

類別 ModelBatchDeployment 和 PipelineComponentBatchDeployment 是在 SDK 1.7.0 版中引進。使用 pip install -U azure-ai-ml 來取得其最後一個版本。

連線到您的工作區

工作區是 Azure Machine Learning 的最上層資源，其提供一個集中位置來處理您在使用 Azure Machine Learning 時建立的所有成品。在本節中，我們將連線到您將執行部署工作的工作區。

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 如何用來存取部署作業的輸出路徑。
函式會填入稱為 output_path 的init()全域變數，以供稍後用來知道寫入位置。
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()

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

測試部署

若要測試您的端點，請使用位於此存放庫中的未標記數據的範例，此範例可與模型搭配使用。 Batch 端點只能處理位於雲端的數據，而且可從 Azure 機器學習工作區存取。在此範例中，您會將它上傳至 Azure 機器學習資料存放區。您將建立可用來叫用端點進行評分的數據資產。不過，請注意，批次端點可接受可放置在多個位置類型的資料。

使用記憶體帳戶的資料叫用端點：
- 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 中跟著

必要條件

連線到您的工作區

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

註冊模型

建立評分指令碼

建立端點

建立部署

測試部署

分析輸出

清除資源

相關內容

意見反應

意見反應

其他資源