本文内容
批处理终结点可用于对大量数据执行长时间运行的批处理操作。 此类数据可以放在不同的位置。 某些类型的批处理终结点还可以接收文本参数作为输入。 本教程介绍如何指定文本参数输入,以及支持的不同类型或位置。
调用终结点之前
若要成功调用批处理终结点并创建作业,请确保具备以下各项条件:
有权限运行批处理终结点部署。 参阅批处理终结点上的授权 ,以了解所需的特定权限。
有一个有效的 Microsoft Entra ID 令牌,表示要调用终结点的安全主体。 此主体可以是用户主体或服务主体。 在任一情况下,一旦调用终结点,就会在与令牌关联的标识下创建批处理部署作业。 出于测试目的,可以使用自己的凭据进行调用,如下所示。
使用 Azure CLI 通过交互式身份验证或设备代码身份验证登录:
az cloud set -n AzureChinaCloud
az login
使用适用于 Python 的 Azure 机器学习 SDK 登录:
from azure.ai.ml import MLClient
from azure.identity import DefaultAzureCredentials
ml_client = MLClient.from_config(DefaultAzureCredentials())
如果在 Azure 机器学习计算外部运行,则需要指定部署终结点的工作区:
from azure.ai.ml import MLClient
from azure.identity import DefaultAzureCredentials
subscription_id = "<subscription>"
resource_group = "<resource-group>"
workspace = "<workspace>"
ml_client = MLClient(DefaultAzureCredentials(), subscription_id, resource_group, workspace)
为用户帐户获取有效令牌的最简单方法是使用 Azure CLI。 在控制台中运行以下命令:
az account get-access-token --resource https://studio.ml.azure.cn --query "accessToken" --output tsv
若要详细了解如何使用多种类型的凭据进行身份验证,请阅读批处理终结点上的授权 。
部署终结点的计算群集 有权读取输入数据。
提示
如果使用无凭据数据存储或外部 Azure 存储帐户作为数据输入,请确保为数据访问配置计算群集 。 计算群集的托管标识 用于装载 存储帐户。 作业(调用程序)的标识仍用于读取基础数据,以便实现精细访问控制。
批处理终结点提供使用者可用来创建批处理作业的持久 API。 可使用同一接口指定部署预期的输入和输出。 使用输入传递终结点执行作业所需的任何信息。
Batch 终结点支持两种类型的输入:
数据输入 ,这些输入是指向特定存储位置或 Azure 机器学习资产的指针。
文本输入 ,即要传递给作业的文本值(如数字或字符串)。
输入和输出的数量和类型取决于批处理部署的类型 。 模型部署始终需要一个数据输入并生成一个数据输出。 不支持文本输入。 但是,管道组件部署提供了一个更通用的构造来生成终结点,并允许指定任意数量的输入(数据和文本)和输出。
下表汇总了批处理部署的输入和输出:
提示
始终对输入和输出命名。 这些名称充当用于标识它们的关键值,并在调用期间传递实际值。 由于模型部署始终需要一个输入和输出,因此在调用期间会忽略该名称。 可以指定最能描述用例的名称,如“sales_estimation”。
数据输入是指指向数据放置位置的输入。 由于批处理终结点通常使用大量数据,因此不能在调用请求中传递输入数据, 而是指定批处理终结点查找数据时应转到的位置。 在目标计算上装载和流式传输输入数据以提高性能。
批处理终结点支持读取位于以下存储选项中的文件:
Azure 机器学习数据资产 ,包括文件夹(uri_folder
)和文件(uri_file
)。
Azure 机器学习数据存储 ,包括 Azure Blob 存储。
Azure 存储帐户 ,包括 Azure Blob 存储。
本地数据文件夹/文件(Azure 机器学习 CLI 或用于 Python 的 Azure 机器学习 SDK)。 但是,该操作会导致将本地数据上传到正在处理的工作区的默认 Azure 机器学习数据存储。
重要
弃用通知:FileDataset
类型的数据集 (V1) 已弃用,并且将来会停用。 依赖此功能的现有批处理终结点可以继续正常运行,但使用 GA CLIv2(2.4.0 和更高版本)或 GA REST API(2022-05-01 和更高版本)创建的批处理终结点将不支持 V1 数据集。
数据输出
数据输出是指批处理作业结果的放置位置。 输出由名称标识,Azure 机器学习会自动为每个命名输出分配唯一路径。 但是,如果需要,可以指定另一个路径。
重要
批处理终结点仅支持在 Azure Blob 存储数据存储中写入输出。
以下示例演示如何从数据资产 、数据存储 和 Azure 存储帐户 获取数据输入,以创建作业。
支持将 Azure 机器学习数据资产(以前称为数据集)作为作业的输入。 按照以下步骤使用 Azure 机器学习中已注册数据资产中存储的数据运行批处理终结点作业:
警告
目前不支持表类型 (MLTable
) 的数据资产。
首先创建数据资产。 此数据资产由包含多个 CSV 文件的文件夹组成,你将使用批处理终结点并行处理这些文件。 如果你的数据已注册为数据资产,则可以跳过此步骤。
在 YAML
中创建数据资产定义:
heart-dataset-unlabeled.yml
$schema: https://azuremlschemas.azureedge.net/latest/data.schema.json
name: heart-dataset-unlabeled
description: An unlabeled dataset for heart classification.
type: uri_folder
path: heart-classifier-mlflow/data
然后,创建数据资产:
az ml data create -f heart-dataset-unlabeled.yml
data_path = "heart-classifier-mlflow/data"
dataset_name = "heart-dataset-unlabeled"
heart_dataset_unlabeled = Data(
path=data_path,
type=AssetTypes.URI_FOLDER,
description="An unlabeled dataset for heart classification",
name=dataset_name,
)
创建数据资产:
ml_client.data.create_or_update(heart_dataset_unlabeled)
若要获取新创建的数据资产,请使用:
heart_dataset_unlabeled = ml_client.data.get(name=dataset_name, label="latest")
使用 Azure 机器学习 CLI、适用于 Python 的 Azure 机器学习 SDK 或 Azure 机器学习工作室以获取位置(区域)、工作区以及数据资产名称和版本。 稍后会需要它们。
创建输入或请求:
DATASET_ID=$(az ml data show -n heart-dataset-unlabeled --label latest | jq -r .id)
input = Input(path=heart_dataset_unlabeled.id)
正文
{
"properties": {
"InputData": {
"heart_dataset": {
"JobInputType" : "UriFolder",
"Uri": "azureml://locations/<location>/workspaces/<workspace>/data/<dataset_name>/versions/labels/latest"
}
}
}
}
注意
数据资产 ID 类似于 /subscriptions/<subscription>/resourcegroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/data/<data-asset>/versions/<version>
。 还可以使用 azureml:/<datasset_name>@latest
作为指定输入的方法。
运行终结点:
使用 --set
参数指定输入:
az ml batch-endpoint invoke --name $ENDPOINT_NAME \
--set inputs.heart_dataset.type="uri_folder" inputs.heart_dataset.path=$DATASET_ID
对于提供模型部署的终结点,可以使用 --input
参数来指定数据输入,因为模型部署始终只需要一个数据输入。
az ml batch-endpoint invoke --name $ENDPOINT_NAME --input $DATASET_ID
当指定多个输入时,参数 --set
往往会生成长命令。 在这些情况下,请将输入放在 YAML
文件中,并使用 --file
指定终结点调用所需的输入。
inputs.yml
inputs:
heart_dataset: azureml:/<datasset_name>@latest
az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml
提示
调用终结点时,inputs
与 input
有何区别?
一般情况下,可以将字典 inputs = {}
与 invoke
方法一起使用,以便向包含模型部署 或管道部署 的批处理终结点提供任意数量的所需输入。
对于模型部署 ,可以使用 input
来更简洁地指定部署的输入数据位置,因为模型部署始终只使用一个数据输入 。
调用 invoke
方法,使用 inputs
指定所需的输入:
job = ml_client.batch_endpoints.invoke(
endpoint_name=endpoint.name,
inputs={
"heart_dataset": input,
}
)
通过使用 input
指定输入数据的位置,进一步简化模型部署的 invoke
调用:
job = ml_client.batch_endpoints.invoke(
endpoint_name=endpoint.name,
input=input,
)
请求
POST jobs HTTP/1.1
Host: <ENDPOINT_URI>
Authorization: Bearer <TOKEN>
Content-Type: application/json
批量部署作业可以直接引用 Azure 机器学习注册数据存储中的数据。 在此示例中,你会首先将一些数据上传到 Azure 机器学习工作区中的默认数据存储,然后在其上运行批处理部署。 按照以下步骤使用数据存储中存储的数据运行批处理终结点作业。
访问 Azure 机器学习工作区中的默认数据存储。 如果你的数据位于其他存储中,可以改用该存储。 无需使用默认数据存储。
DATASTORE_ID=$(az ml datastore show -n workspaceblobstore | jq -r '.id')
注意
数据存储 ID 类似于 /subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/datastores/<data-store>
。
default_ds = ml_client.datastores.get_default()
使用 Azure 机器学习 CLI、适用于 Python 的 Azure 机器学习 SDK 或工作室获取数据存储信息。
提示
工作区中的默认 Blob 数据存储称为 workspaceblobstore。 如果你已知道工作区中默认数据存储的资源 ID,则可以跳过此步骤。
需要将一些示例数据上传到数据存储。 此示例假设已将存储库中包含的示例数据上传到 Blob 存储帐户的文件夹 heart-disease-uci-unlabeled
中的文件夹 sdk/python/endpoints/batch/deploy-models/heart-classifier-mlflow/data
。 在继续操作之前,请确保已完成该操作。
创建输入或请求:
将文件路径放在以下变量中:
DATA_PATH="heart-disease-uci-unlabeled"
INPUT_PATH="$DATASTORE_ID/paths/$DATA_PATH"
data_path = "heart-disease-uci-unlabeled"
input = Input(type=AssetTypes.URI_FOLDER, path=f"{default_ds.id}/paths/{data_path})
如果你的数据是文件,请更改 type=AssetTypes.URI_FILE
。
正文
{
"properties": {
"InputData": {
"heart_dataset": {
"JobInputType" : "UriFolder",
"Uri": "azureml:/subscriptions/<subscription>/resourceGroups/<resource-group/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/datastores/<data-store>/paths/<data-path>"
}
}
}
}
如果你的数据是文件,请改为使用 UriFile
作为类型。
注意
了解如何将路径 paths
追加到数据存储的资源 ID,以指示后面跟随的是它中的路径。
提示
还可以将 azureml://datastores/<data-store>/paths/<data-path>
用作指定输入的方法。
运行终结点:
使用 --set
参数指定输入:
az ml batch-endpoint invoke --name $ENDPOINT_NAME \
--set inputs.heart_dataset.type="uri_folder" inputs.heart_dataset.path=$INPUT_PATH
对于提供模型部署的终结点,可以使用 --input
参数来指定数据输入,因为模型部署始终只需要一个数据输入。
az ml batch-endpoint invoke --name $ENDPOINT_NAME --input $INPUT_PATH --input-type uri_folder
当指定多个输入时,参数 --set
往往会生成长命令。 在这些情况下,请将输入放在 YAML
文件中,并使用 --file
指定终结点调用所需的输入。
inputs.yml
inputs:
heart_dataset:
type: uri_folder
path: azureml://datastores/<data-store>/paths/<data-path>
az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml
如果你的数据是文件,请改为使用 uri_file
作为类型。
提示
调用终结点时,inputs
与 input
有何区别?
一般情况下,可以将字典 inputs = {}
与 invoke
方法一起使用,以便向包含模型部署 或管道部署 的批处理终结点提供任意数量的所需输入。
对于模型部署 ,可以使用 input
来更简洁地指定部署的输入数据位置,因为模型部署始终只使用一个数据输入 。
调用 invoke
方法,使用 inputs
指定所需的输入:
job = ml_client.batch_endpoints.invoke(
endpoint_name=endpoint.name,
inputs={
"heart_dataset": input,
}
)
通过使用 input
指定输入数据的位置,进一步简化模型部署的 invoke
调用:
job = ml_client.batch_endpoints.invoke(
endpoint_name=endpoint.name,
input=input,
)
请求
POST jobs HTTP/1.1
Host: <ENDPOINT_URI>
Authorization: Bearer <TOKEN>
Content-Type: application/json
Azure 机器学习批处理终结点可以从 Azure 存储帐户中的云位置(包括公有云和私有云)读取数据。 按照以下步骤使用存储帐户中存储的数据运行批处理终结点作业:
创建输入或请求:
INPUT_DATA = "https://azuremlexampledata.blob.core.chinacloudapi.cn/data/heart-disease-uci/data"
如果数据是文件:
INPUT_DATA = "https://azuremlexampledata.blob.core.chinacloudapi.cn/data/heart-disease-uci/data/heart.csv"
input = Input(
type=AssetTypes.URI_FOLDER,
path="https://azuremlexampledata.blob.core.chinacloudapi.cn/data/heart-disease-uci/data"
)
如果你的数据是文件,请更改 type=AssetTypes.URI_FILE
:
input = Input(
type=AssetTypes.URI_FILE,
path="https://azuremlexampledata.blob.core.chinacloudapi.cn/data/heart-disease-uci/data/heart.csv"
)
正文
{
"properties": {
"InputData": {
"heart_dataset": {
"JobInputType" : "UriFolder",
"Uri": "https://azuremlexampledata.blob.core.chinacloudapi.cn/data/heart-disease-uci/data"
}
}
}
}
如果你的数据是文件,请更改 JobInputType
:
正文
{
"properties": {
"InputData": {
"heart_dataset": {
"JobInputType" : "UriFile",
"Uri": "https://azuremlexampledata.blob.core.chinacloudapi.cn/data/heart-disease-uci/data/heart.csv"
}
}
}
}
运行终结点:
使用 --set
参数指定输入:
az ml batch-endpoint invoke --name $ENDPOINT_NAME \
--set inputs.heart_dataset.type="uri_folder" inputs.heart_dataset.path=$INPUT_DATA
对于提供模型部署的终结点,可以使用 --input
参数来指定数据输入,因为模型部署始终只需要一个数据输入。
az ml batch-endpoint invoke --name $ENDPOINT_NAME --input $INPUT_DATA --input-type uri_folder
当指定多个输入时,参数 --set
往往会生成长命令。 在这些情况下,请将输入放在 YAML
文件中,并使用 --file
指定终结点调用所需的输入。
inputs.yml
inputs:
heart_dataset:
type: uri_folder
path: https://azuremlexampledata.blob.core.chinacloudapi.cn/data/heart-disease-uci/data
az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml
如果你的数据是文件,请改为使用 uri_file
作为类型。
提示
调用终结点时,inputs
与 input
有何区别?
一般情况下,可以将字典 inputs = {}
与 invoke
方法一起使用,以便向包含模型部署 或管道部署 的批处理终结点提供任意数量的所需输入。
对于模型部署 ,可以使用 input
来更简洁地指定部署的输入数据位置,因为模型部署始终只使用一个数据输入 。
调用 invoke
方法,使用 inputs
指定所需的输入:
job = ml_client.batch_endpoints.invoke(
endpoint_name=endpoint.name,
inputs={
"heart_dataset": input,
}
)
通过使用 input
指定输入数据的位置,进一步简化模型部署的 invoke
调用:
job = ml_client.batch_endpoints.invoke(
endpoint_name=endpoint.name,
input=input,
)
请求
POST jobs HTTP/1.1
Host: <ENDPOINT_URI>
Authorization: Bearer <TOKEN>
Content-Type: application/json
使用数据输出创建作业
以下示例演示如何更改命名为 score
的输出的放置位置。 为了保持内容完整,这些示例还配置了命名为 heart_dataset
的输入。
使用 Azure 机器学习工作区中的默认数据存储来保存输出。 你可以使用工作区中的任何其他数据存储,只要它是 Blob 存储帐户即可。
DATASTORE_ID=$(az ml datastore show -n workspaceblobstore | jq -r '.id')
注意
数据存储 ID 类似于 /subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/datastores/<data-store>
。
default_ds = ml_client.datastores.get_default()
使用 Azure 机器学习 CLI、适用于 Python 的 Azure 机器学习 SDK 或工作室获取数据存储信息。
创建数据输出:
DATA_PATH="batch-jobs/my-unique-path"
OUTPUT_PATH="$DATASTORE_ID/paths/$DATA_PATH"
为了保持内容完整,还要创建一个数据输入:
INPUT_PATH="https://azuremlexampledata.blob.core.chinacloudapi.cn/data/heart-disease-uci/data"
data_path = "batch-jobs/my-unique-path"
output = Output(type=AssetTypes.URI_FOLDER, path=f"{default_ds.id}/paths/{data_path})
为了保持内容完整,我们还要创建一个数据输入:
input="https://azuremlexampledata.blob.core.chinacloudapi.cn/data/heart-disease-uci/data"
正文
{
"properties": {
"InputData": {
"heart_dataset": {
"JobInputType" : "UriFolder",
"Uri": "https://azuremlexampledata.blob.core.chinacloudapi.cn/data/heart-disease-uci/data"
}
},
"OutputData": {
"score": {
"JobOutputType" : "UriFile",
"Uri": "azureml:/subscriptions/<subscription>/resourceGroups/<resource-group/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/datastores/<data-store>/paths/<data-path>"
}
}
}
}
注意
了解如何将路径 paths
追加到数据存储的资源 ID,以指示后面跟随的是它中的路径。
运行部署:
使用参数 --set
指定输入:
az ml batch-endpoint invoke --name $ENDPOINT_NAME \
--set inputs.heart_dataset.path=$INPUT_PATH \
--set outputs.score.path=$OUTPUT_PATH
job = ml_client.batch_endpoints.invoke(
endpoint_name=endpoint.name,
inputs={ "heart_dataset": input },
outputs={ "score": output }
)
请求
POST jobs HTTP/1.1
Host: <ENDPOINT_URI>
Authorization: Bearer <TOKEN>
Content-Type: application/json
调用特定部署
Batch 终结点可以在同一终结点下托管多个部署。 除非用户另有指定,否则使用默认终结点。 可以按如下所示方法更改所使用的部署:
使用参数--deployment-name
或-d
指定部署的名称:
az ml batch-endpoint invoke --name $ENDPOINT_NAME --deployment-name $DEPLOYMENT_NAME --input $INPUT_DATA
使用参数deployment_name
指定部署的名称:
job = ml_client.batch_endpoints.invoke(
endpoint_name=endpoint.name,
deployment_name=deployment.name,
inputs={
"heart_dataset": input,
}
)
将标题azureml-model-deployment
添加到请求,包括要调用的部署的名称。
Request
POST jobs HTTP/1.1
Host: <ENDPOINT_URI>
Authorization: Bearer <TOKEN>
Content-Type: application/json
azureml-model-deployment: DEPLOYMENT_NAME
后续步骤