使用批处理终结点进行批量评分

适用于:Azure CLI ml 扩展 v2(当前版本)

了解如何使用批处理终结点执行批量评分。 批处理终结点简化了承载用于批量评分的模型的过程,使你可以将工作重心放在机器学习而不是基础结构上。 有关详细信息,请参阅什么是 Azure 机器学习终结点?

本文介绍如何执行以下任务:

  • 创建批处理终结点和默认批处理部署
  • 使用 Azure CLI 启动批量评分作业
  • 监视批量评分作业执行进度并检查评分结果
  • 使用自动生成的代码和环境将新 MLflow 模型部署到现有终结点,而不影响现有流
  • 测试新部署,并将其设置为默认部署
  • 删除未使用的终结点和部署

先决条件

  • 必须拥有 Azure 订阅,才能使用 Azure 机器学习。 如果没有 Azure 订阅,可在开始前创建一个试用帐户。 立即试用免费版或付费版 Azure 机器学习

  • 安装 Azure CLI 和 ml 扩展。 按照安装、设置和使用 CLI (v2)中的安装步骤执行操作。

  • 如果没有 Azure 资源组,请创建一个,且你(或你使用的服务主体)必须具有 Contributor 权限。 有关资源组的创建,请参阅安装、设置和使用 CLI (v2)

  • 创建 Azure 机器学习工作区(如果没有)。 有关工作区的创建,请参阅安装、设置和使用 CLI (v2)

  • 为 Azure CLI 配置默认工作区和资源组。 机器学习 CLI 命令需要 --workspace/-w--resource-group/-g 参数。 配置默认值可以避免多次传入值。 可以在命令行中替代它们。 运行以下代码以设置默认值。 有关详细信息,请参阅安装、设置和使用 CLI (v2)

az account set -s "<subscription ID>"
az configure --defaults group="<resource group>" workspace="<workspace name>" location="<location>"

克隆示例存储库

运行以下命令来克隆 AzureML 示例存储库,并转到 cli 目录。 本文使用 /cli/endpoints/batch 中的资产,端到端工作示例为 /cli/batch-score.sh

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

设置终结点名称。 将 YOUR_ENDPOINT_NAME 替换为 Azure 区域内的唯一名称。

若是 Unix,运行此命令:

export ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"

若是 Windows,运行此命令:

set ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"

注意

批处理终结点名称在 Azure 区域内需是唯一的。 例如,chinanorth2 中只能有一个名为 mybatchendpoint 的批处理终结点。

创建计算

批处理终结点仅在云计算资源上运行,而不在本地运行。 云计算资源是可重用的虚拟计算机群集。 运行以下代码以创建 Azure 机器学习计算群集。 本文以下示例使用此处创建的名为 batch-cluster 的计算。 根据需要进行调整,并使用 azureml:<your-compute-name> 引用计算。

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

注意

此时不收取计算费用,因为在调用批处理终结点并提交批量评分作业之前,群集将保持为 0 个节点。 详细了解管理和优化 AmlCompute 的成本

了解批处理终结点和批处理部署

批处理终结点是客户端可以调用以触发批量评分作业的 HTTPS 终结点。 批量评分作业是对多个输入进行评分的作业(有关详细信息,请参阅什么是批处理终结点?)。 批处理部署是一组计算资源,承载执行实际批量评分的模型。 一个批处理终结点可以包含多个批处理部署。

提示

其中一个批处理部署将充当该终结点的默认部署。 调用终结点时,默认部署将用于执行实际的批量评分。 详细了解批处理终结点和批处理部署

以下 YAML 文件可定义批处理终结点,可以将其包含在用于创建批处理终结点的 CLI 命令中。 在存储库中,此文件位于 /cli/endpoints/batch/batch-endpoint.yml 中。

$schema: https://azuremlschemas.azureedge.net/latest/batchEndpoint.schema.json
name: mybatchedp
description: my sample batch endpoint
auth_mode: aad_token

下表介绍了终结点 YAML 的关键属性。 有关完整的批处理终结点 YAML 架构,请参阅 CLI (v2) 批处理终结点 YAML 架构

密钥 说明
$schema [可选] YAML 架构。 可以在浏览器中查看上述示例中的架构,以查看批处理终结点 YAML 文件的所有可用选项。
name 批处理终结点的名称。 在 Azure 区域级别需是唯一的。
auth_mode 批处理终结点的身份验证方法。 目前仅支持 Azure Active Directory 基于令牌的身份验证 (aad_token)。
defaults.deployment_name 将充当终结点默认部署的部署的名称。

若要创建批处理部署,需要具备以下所有项:

  • 模型文件,或已在工作区中注册的使用 azureml:<model-name>:<model-version> 引用的模型。
  • 用于为模型评分的代码。
  • 运行模型的环境。 它可以是具有 Conda 依赖项的 Docker 映像,也可以是已在工作区中注册的使用 azureml:<environment-name>:<environment-version> 引用的环境。
  • 使用 azureml:<compute-name> 和资源设置引用的预先创建的计算。

有关如何引用 Azure ML 实体的详细信息,请参阅引用 Azure ML 实体

示例存储库包含所有必需的文件。 以下 YAML 文件使用所有必需输入和可选设置定义批处理部署。 可以将此文件包含在用于创建批处理部署的 CLI 命令中。 在存储库中,此文件位于 /cli/endpoints/batch/nonmlflow-deployment.yml 中。

$schema: https://azuremlschemas.azureedge.net/latest/batchDeployment.schema.json
name: nonmlflowdp
endpoint_name: mybatchedp
model: 
  path: ./mnist/model/
code_configuration:
  code: ./mnist/code/
  scoring_script: digit_identification.py
environment:
  conda_file: ./mnist/environment/conda.yml
  image: mcr.microsoft.com/azureml/openmpi3.1.2-ubuntu18.04:latest
compute: azureml:batch-cluster
resources:
  instance_count: 1
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

有关完整的批处理部署 YAML 架构,请参阅 CLI (v2) 批处理部署 YAML 架构

密钥 说明
$schema [可选] YAML 架构。 可以在浏览器中查看上述示例中的架构,以查看批处理部署 YAML 文件的所有可用选项。
name 部署的名称。
endpoint_name 要在其下创建部署的终结点的名称。
model 用于批量评分的模型。 该示例使用 path 以内联方式定义模型。 模型文件将自动上传并使用自动生成的名称和版本进行注册。 有关更多选项,请遵循模型架构。 对于生产方案,最佳做法应该是单独创建模型并在此处引用模型。 若要引用现有模型,请使用 azureml:<model-name>:<model-version> 语法。
code_configuration.code.path 包含用于为模型评分的所有 Python 源代码的本地目录。
code_configuration.scoring_script 上述目录中的 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-cluster 并使用 azureml:<compute-name> 语法引用它。
resources.instance_count 每个批量评分作业要使用的实例数。
max_concurrency_per_instance [可选] 每个实例的最大并行 scoring_script 运行数。
mini_batch_size [可选] scoring_script 可以在一次 run() 调用中处理的文件数。
output_action [可选] 应如何在输出文件中组织输出。 append_row 会将所有 run() 返回的输出结果合并到一个名为 output_file_name 的文件中。 summary_only 不会合并输出结果,而只会计算 error_threshold
output_file_name [可选] append_rowoutput_action 批量评分输出文件的名称。
retry_settings.max_retries [可选] 失败的 scoring_scriptrun() 的最大尝试次数。
retry_settings.timeout [可选] scoring_scriptrun() 对微型批进行评分的超时值(以秒为单位)。
error_threshold [可选] 应忽略的输入文件评分失败次数。 如果整个输入的错误计数超出此值,则批量评分作业将终止。 此示例使用 -1,指示允许失败任意次,而不会终止批量评分作业。
logging_level [可选] 日志详细程度。 值(以详细程度递增的顺序排列)为:WARNING、INFO 和 DEBUG。

了解评分脚本

如前文所述,code_configuration.scoring_script 必须包含两个函数:

  • init():对于任何成本较高或者一般性的准备工作,请使用此函数。 例如,使用它将模型加载到全局对象。 此函数将在进程开始时被调用一次。
  • run(mini_batch):将为每个 mini_batch 调用此函数并由它执行实际评分。
    • mini_batchmini_batch 值是文件路径列表。
    • responserun() 方法应返回 Pandas 数据帧或数组。 每个返回的输出元素指示输入 mini_batch 中成功运行一次输入元素。 请确保 run() 响应中包含足够的数据,以将输入与输出相关联。 根据此评分脚本填充生成的数据帧或数组。 希望输出多少信息以将输出值与输入值关联起来,这取决于你,例如,该数组可以表示包含模型输出和输入的元组的列表。 对结果的基数没有要求。 结果数据帧或数组中的所有元素将按原样写入输出文件(假设 output_action 不是 summary_only)。

该示例使用 /cli/endpoints/batch/mnist/code/digit_identification.py。 模型从 AZUREML_MODEL_DIR(部署期间创建的模型文件夹的路径)加载到 init() 中。 run(mini_batch) 循环访问 mini_batch 中的每个文件,执行实际模型评分并返回输出结果。

使用批处理终结点部署并运行批量评分

现在使用批处理终结点部署模型,并运行批量评分。

创建批处理终结点

创建批处理终结点的最简单方法是运行以下仅提供 --name 的代码。

az ml batch-endpoint create --name $ENDPOINT_NAME

还可以使用 YAML 文件创建批处理终结点。 在上面的命令中添加 --file 参数,并指定 YAML 文件路径。

创建批处理部署

运行以下代码以在批处理终结点下创建一个名为 nonmlflowdp 的批处理部署,并将其设置为默认部署。

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

提示

--set-default 参数将新创建的部署设置为终结点的默认部署。 这是一种简便的方法来创建终结点的新默认部署,尤其对于首次创建部署。 对于生产方案,最佳做法可能要创建一个新部署(而不将其设置为默认部署),验证该部署,并在稍后更新默认部署。 有关详细信息,请参阅部署新模型部分。

检查批处理终结点和部署详细信息

使用 show 检查终结点和部署详细信息。

若要检查批处理部署,请运行以下代码:

az ml batch-deployment show --name nonmlflowdp --endpoint-name $ENDPOINT_NAME

若要检查批处理终结点,请运行以下代码。 将新创建的部署设置为默认部署后,应会在响应的 defaults.deployment_name 中看到 nonmlflowdp

az ml batch-endpoint show --name $ENDPOINT_NAME

调用批处理终结点以启动批量评分作业

调用批处理终结点会触发批量评分作业。 调用响应中将返回作业 name,该作业可用于跟踪批量评分进度。 批量评分作业会在一段时间内运行。 它将整个输入拆分为多个 mini_batch,并在计算群集上并行处理它们。 一个 scoring_scriptrun() 接受一个 mini_batch 并通过实例上的一个进程来处理它。 批量评分作业输出将存储在云存储中,可以在工作区的默认 Blob 存储中,也可以在指定的存储中。

使用不同输入选项调用批处理终结点

可以使用 CLI 或 REST 对终结点执行 invoke 操作。 有关 REST 体验,请参阅将批处理终结点与 REST 一起使用

可以使用多个选项在 CLI invoke 中指定数据输入。

  • 选项 1-1:云中的数据

    使用 --input--input-type 可指定 Azure 机器学习已注册的数据存储或可公开访问的路径上的文件或文件夹。 指定单个文件时,可使用 --input-type uri_file,指定文件夹时,可使用 --input-type uri_folder

    当文件或文件夹位于 Azure ML 已注册的数据存储上时,URI 的语法为 azureml://datastores/<datastore-name>/paths/<path-on-datastore>/(适用于文件夹)和 azureml://datastores/<datastore-name>/paths/<path-on-datastore>/<file-name>(适用于特定文件)。 当文件或文件夹位于可公开访问的路径上时,URI 的语法为 https://<public-path>/(适用于文件夹)和 https://<public-path>/<file-name>(适用于特定文件)。

    有关数据 URI 的详细信息,请参阅 Azure 机器学习数据引用 URI

    此示例使用 https://pipelinedata.blob.core.chinacloudapi.cn/sampledata/mnist 中的一个文件夹中的公开可用数据,其中包含数以千计的手写数字。 调用响应中将返回批量评分作业的名称。 运行以下代码,使用此数据调用批处理终结点。 添加 --query name 后,调用响应中仅返回作业名称,该名称稍后将用于监视批量评分作业执行进度检查批量评分结果。 如果要查看完整的调用响应,请删除 --query name -o tsv。 有关 --query 参数的详细信息,请参阅查询 Azure CLI 命令输出

    JOB_NAME=$(az ml batch-endpoint invoke --name $ENDPOINT_NAME --input https://pipelinedata.blob.core.windows.net/sampledata/mnist --input-type uri_folder --query name -o tsv)
    
  • 选项 1-2:已注册的数据资产

    使用 --input 传入已注册 Azure 机器学习的 V2 数据资产(类型为 uri_fileurl_folder)。 无需在此选项中指定 --input-type。 此选项的语法为 azureml:<dataset-name>:<dataset-version>

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --input azureml:<dataset-name>:<dataset-version>
    
  • 选项 2:本地存储的数据

    使用 --input 传入本地存储的数据文件。 无需在此选项中指定 --input-type。 数据文件将自动作为文件夹上传到 Azure ML 数据存储,并传递到批处理评分作业。

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --input <local-path>
    

注意

  • 如果对批处理终结点使用现有的 V1 FileDataset,建议将它们迁移到 V2 数据资产,并在调用批处理终结点时直接引用它们。 目前仅支持类型 uri_folderuri_file 的数据资产。 使用 GA CLIv2(2.4.0 及更高版本)或 GA REST API(2022-05-01 及更高版本)创建的批处理终结点不支持 V1 数据集。
  • 还可使用 az ml dataset show 命令和 --query 参数提取从 V1 FileDataset 中提取的数据存储上的 URI 或路径,并将该信息用于调用。
  • 虽然使用早期 API 创建的批处理终结点将继续支持 V1 FileDataset,但我们将使用最新 API 版本添加更多 V2 数据资产支持,以提高可用性和灵活性。 有关 V2 数据资产的详细信息,请参阅使用 SDK v2 处理数据。 有关新的 V2 体验的详细信息,请参阅什么是 v2

配置输出位置并覆盖设置

默认情况下,批量评分结果存储在工作区的默认 Blob 存储中按作业名称(系统生成的 GUID)命名的某个文件夹内。 可以配置在调用批处理终结点时用于存储评分输出的位置。 使用 --output-path 配置 Azure 机器学习已注册的数据集中的任何文件夹。 指定文件夹时,--output-path 的语法与 --input 的语法相同,即都为 azureml://datastores/<datastore-name>/paths/<path-on-datastore>/。 不再需要前缀 folder:。 如果更喜欢在一个输出文件中包含所有评分结果(部署 YAML 中指定的 output_action=append_row),请使用 --set output_file_name=<your-file-name> 来配置新的输出文件名。

重要

必须使用唯一的输出位置。 如果输出文件已存在,批量评分作业将失败。

可以在调用时覆盖某些设置,以充分利用计算资源并提高性能:

  • 使用 --instance-count 覆盖 instance_count。 例如,对于较大的数据输入量,可能需要使用更多实例来加速端到端批量评分。
  • 使用 --mini-batch-size 覆盖 mini_batch_size。 微型批处理数由输入文件总计数和 mini_batch_size 确定。 mini_batch_size 较小就会生成更多微型批处理。 微型批处理可以并行运行,但可能需要额外计划并产生额外的调用开销。
  • 使用 --set 可覆盖其他设置,包括 max_retriestimeouterror_threshold。 这些设置可能会影响不同工作负载的端到端批量评分时间。

若要指定输出位置并在调用时覆盖设置,请运行以下代码。 该示例将输出存储在工作区的默认 Blob 存储中与终结点同名的文件夹中,并使用随机文件名来确保输出位置是唯一的。 此代码应可在 Unix 中运行。 替换为自己的唯一文件夹和文件名。

export OUTPUT_FILE_NAME=predictions_`echo $RANDOM`.csv
JOB_NAME=$(az ml batch-endpoint invoke --name $ENDPOINT_NAME --input https://pipelinedata.blob.core.windows.net/sampledata/mnist --input-type uri_folder --output-path azureml://datastores/workspaceblobstore/paths/$ENDPOINT_NAME --set output_file_name=$OUTPUT_FILE_NAME --mini-batch-size 20 --instance-count 5 --query name -o tsv)

监视批量评分作业执行进度

批量评分作业通常会花费一段时间来处理整个输入集。

可以使用 CLI job show 来查看作业。 运行以下代码,以检查上一次终结点调用中的作业状态。 若要详细了解作业命令,请运行 az ml job -h

STATUS=$(az ml job show -n $JOB_NAME --query status -o tsv)
echo $STATUS
if [[ $STATUS == "Completed" ]]
then
  echo "Job completed"
elif [[ $STATUS ==  "Failed" ]]
then
  echo "Job failed"
  exit 1
else 
  echo "Job status not failed or completed"
  exit 2
fi

检查批量评分结果

执行以下步骤以在作业完成时在 Azure 存储资源管理器中查看评分结果:

  1. 运行以下代码,在 Azure 机器学习工作室中打开批量评分作业。 invoke 的响应中还包含以 interactionEndpoints.Studio.endpoint 值的形式提供的作业工作室链接。
az ml job show -n $JOB_NAME --web
  1. 在作业图中,选择 batchscoring 步骤。
  2. 选择“输出 + 日志”选项卡,然后选择“显示数据输出”。
  3. 在“数据输出”中,选择图标以打开“存储资源管理器”。

显示在工作室中查看数据输出位置的屏幕截图

存储资源管理器中的评分结果类似以下示例页:

评分输出的屏幕截图

部署新模型

拥有批处理终结点后,可以继续优化模型并添加新部署。

创建承载 MLflow 模型的新批处理部署

若要在现有批处理终结点下创建新批处理部署而不将其设置为默认部署,请运行以下代码:

az ml batch-deployment create --name mlflowdp --endpoint-name $ENDPOINT_NAME --file endpoints/batch/mlflow-deployment.yml

请注意,未使用 --set-default。 如果再次对批处理终结点执行 show 操作,defaults.deployment_name 不应发生更改。

该示例使用经 MLflow 训练和跟踪的模型 (/cli/endpoints/batch/autolog_nyc_taxi)。 使用模型的元数据可以自动生成 scoring_scriptenvironment,无需在 YAML 文件中指定。 有关 MLflow 的详细信息,请参阅使用 MLflow 和 Azure 机器学习训练和跟踪 ML 模型

下面是该示例用于部署 MLflow 模型的 YAML 文件,其中仅包含所需的最少属性。 存储库中的源文件为 /cli/endpoints/batch/mlflow-deployment.yml

$schema: https://azuremlschemas.azureedge.net/latest/batchDeployment.schema.json
name: mlflowdp
endpoint_name: mybatchedp
model: 
  path: ./autolog_nyc_taxi
compute: azureml:batch-cluster

注意

scoring_scriptenvironment 自动生成仅支持 Python 函数模型风格和基于列的模型签名。

测试非默认批处理部署

若要测试新的非默认部署,请运行以下代码。 该示例使用不同的模型,该模型接受 https://pipelinedata.blob.core.chinacloudapi.cn/sampledata/nytaxi/taxi-tip-data.csv 中公开提供的 csv 文件。

JOB_NAME=$(az ml batch-endpoint invoke --name $ENDPOINT_NAME --deployment-name mlflowdp --input https://pipelinedata.blob.core.windows.net/sampledata/nytaxi/taxi-tip-data.csv --input-type uri_file --query name -o tsv)

echo "Show job detail"
az ml job show -n $JOB_NAME --web

echo "Stream job logs to console"
az ml job stream -n $JOB_NAME

STATUS=$(az ml job show -n $JOB_NAME --query status -o tsv)
echo $STATUS
if [[ $STATUS == "Completed" ]]
then
  echo "Job completed"
elif [[ $STATUS ==  "Failed" ]]
then
  echo "Job failed"
  exit 1
else 
  echo "Job status not failed or completed"
  exit 2
fi

请注意,--deployment-name 用于指定新的部署名称。 使用此参数可以对非默认部署执行 invoke 操作,且不会更新批处理终结点的默认部署。

更新默认批处理部署

若要更新终结点的默认批处理部署,请运行以下代码:

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

如果再次对批处理终结点执行 show 操作,defaults.deployment_name 应已设置为 mlflowdp。 无需使用 invoke 参数即可直接对批处理终结点执行 --deployment-name 操作。

(可选)更新部署

如果要更新部署(例如更新代码、模型、环境或设置),请更新 YAML 文件,然后运行 az ml batch-deployment update。 也可以使用 --set 在无 YAML 文件的情况下进行更新。 查看 az ml batch-deployment update -h 获取更多信息。

删除批处理终结点和部署

如果不打算使用旧的批处理部署,应运行以下代码将其删除。 --yes 用于确认删除。

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

运行以下代码以删除批处理终结点和所有基础部署。 不会删除批量评分作业。

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

后续步骤