为批处理终结点创建作业和输入数据

通过批处理终结点，可对大量数据执行长时间运行的批处理操作。 数据可以位于不同的位置，例如分散的区域中。 某些类型的批处理终结点还可以接收文本参数作为输入。

本文介绍如何为批处理终结点指定参数输入并创建部署作业。 该流程支持处理不同类型的数据。 有关示例，请参阅了解输入和输出。

先决条件

若要成功调用批处理终结点并创建作业，请确保完成以下先决条件：

• 运行批处理终结点部署的权限。 AzureML 数据科学家、参与者和所有者角色可用于运行部署。 对于自定义角色定义，请参阅批处理终结点上的授权以查看所需的特定权限。

• 一个有效的 Microsoft Entra ID 令牌，表示要调用终结点的安全主体。 此主体可以是用户主体或服务主体。 调用终结点后，Azure 机器学习会在与令牌关联的标识下创建一个批处理部署作业。 可以使用自己的凭据进行调用，具体过程如下。

  • Azure CLI
  • Python
  • REST

  使用 Azure CLI 通过交互式身份验证或设备代码身份验证登录：

    az cloud set -n AzureChinaCloud
  az login
  

  若要详细了解如何使用不同类型的凭据启动批处理部署作业，请参阅如何使用不同类型的凭据运行作业。

• 部署终结点的计算群集有权读取输入数据。

  提示

  如果使用无凭据数据存储或外部 Azure 存储帐户作为数据输入，请确保为数据访问配置计算群集。 计算群集的托管标识用于装载存储帐户。 作业（调用方）的标识仍用于读取基础数据，这样就可以实现精细访问控制。

创建作业基础知识

若要通过批处理终结点创建作业，请调用该终结点。 可以使用 Azure CLI、适用于 Python 的 Azure 机器学习 SDK 或 REST API 调用来完成调用。 以下示例显示了接收单个输入数据文件夹进行处理的批处理终结点的调用的基础知识。 有关具有不同输入和输出的示例，请参阅了解输入和输出。

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --input https://azuremlexampledata.blob.core.chinacloudapi.cn/data/heart-disease-uci/data

job = ml_client.batch_endpoints.invoke(
    endpoint_name=endpoint.name,
    inputs={
        "heart_dataset": 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"
           }
        }
    }
}

POST jobs HTTP/1.1
Host: <ENDPOINT_URI>
Authorization: Bearer <TOKEN>
Content-Type: application/json

调用特定部署

Batch 终结点可以在同一终结点下托管多个部署。 除非用户另有指定，否则使用默认终结点。 可以通过以下过程更改要使用的部署。

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --deployment-name $DEPLOYMENT_NAME \
                            --input https://azuremlexampledata.blob.core.chinacloudapi.cn/data/heart-disease-uci/data

job = ml_client.batch_endpoints.invoke(
    endpoint_name=endpoint.name,
    deployment_name=deployment.name,
    inputs={
        "heart_dataset": 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"
           }
        }
    }
}

POST jobs HTTP/1.1
Host: <ENDPOINT_URI>
Authorization: Bearer <TOKEN>
Content-Type: application/json
azureml-model-deployment: DEPLOYMENT_NAME

配置作业属性

可以在调用时配置已创建的作业中的一些属性。

配置试验名称

使用以下过程配置试验名称。

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --experiment-name "my-batch-job-experiment" \
                            --input https://azuremlexampledata.blob.core.chinacloudapi.cn/data/heart-disease-uci/data

job = ml_client.batch_endpoints.invoke(
    endpoint_name=endpoint.name,
    experiment_name="my-batch-job-experiment",
    inputs={
        "heart_dataset": 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"
           }
        },
        "properties":
        {
            "experimentName": "my-batch-job-experiment"
        }
    }
}

POST jobs HTTP/1.1
Host: <ENDPOINT_URI>
Authorization: Bearer <TOKEN>
Content-Type: application/json

了解输入和输出

批处理终结点提供使用者可用来创建批处理作业的持久 API。 可使用同一接口指定部署预期的输入和输出。 使用输入传递终结点执行作业所需的任何信息。

Batch 终结点支持两种类型的输入：

• 数据输入：指向特定存储位置或 Azure 机器学习资产的指针。
• 文本输入：要传递给作业的文本值（如数字或字符串）。

输入和输出的数量和类型取决于批处理部署的类型。 模型部署始终需要一个数据输入并生成一个数据输出。 不支持文本输入。 但是，管道组件部署提供了一个更通用的构造来生成终结点，并允许指定任意数量的输入（数据和文本）和输出。

下表汇总了批处理部署的输入和输出：

浏览数据输入

数据输入是指指向数据放置位置的输入。 由于批处理终结点通常使用大量数据，因此不能在调用请求中传递输入数据。 而是指定批处理终结点查找数据时应转到的位置。 在目标计算上装载和流式传输输入数据以提高性能。

批处理终结点支持读取位于以下存储选项中的文件：

• Azure 机器学习数据资产，包括文件夹 (uri_folder) 和文件 (uri_file)。
• Azure 机器学习数据资产，包括 Azure Blob 存储。
• Azure 存储帐户，包括 Azure Blob 存储。
• 本地数据文件夹/文件（Azure 机器学习 CLI 或用于 Python 的 Azure 机器学习 SDK）。 但是，该操作会导致将本地数据上传到正在处理的工作区的默认 Azure 机器学习数据存储。

浏览文本输入

文本输入是指可以在调用时表示和解析的输入，如字符串、数字和布尔值。 在管道组件部署过程中，通常使用文本输入将参数传递给终结点。 批处理终结点支持以下文本类型：

• string
• boolean
• float
• integer

仅在管道组件部署中支持文本输入。 请参阅使用文本输入创建作业，了解如何指定这些作业。

浏览数据输出

数据输出是指批处理作业结果的放置位置。 每个输出都有一个可识别的名称，Azure 机器学习会自动为每个已命名的输出分配唯一路径。 可以根据需要指定另一个路径。

使用数据输入创建作业

以下示例演示如何从数据资产、数据存储和 Azure 存储帐户获取数据输入，以创建作业。

使用数据资产中的输入数据

支持将 Azure 机器学习数据资产（以前称为数据集）作为作业的输入。 按照以下步骤使用 Azure 机器学习中已注册数据资产中存储的数据运行批处理终结点作业。

1. 首先创建数据资产。 此数据资产由包含多个 CSV 文件的文件夹组成，你可以使用批处理终结点并行处理这些文件。 如果你的数据已注册为数据资产，则可以跳过此步骤。

   • Azure CLI
   • Python
   • REST

   在 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
   

2. 创建输入或请求：

   • Azure CLI
   • Python
   • REST

   DATASET_ID=$(az ml data show -n heart-dataset-unlabeled --label latest | jq -r .id)
   

3. 运行终结点：

   • Azure CLI
   • Python
   • REST

   使用 --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
   

使用数据存储中的输入数据

可以通过批量部署作业直接引用 Azure 机器学习注册数据存储中的数据。 在此示例中，你会首先将一些数据上传到 Azure 机器学习工作区中的默认数据存储，然后在其上运行批处理部署。 按照以下步骤使用数据存储中存储的数据运行批处理终结点作业。

1. 访问 Azure 机器学习工作区中的默认数据存储。 如果你的数据位于其他存储中，可以改用该存储。 无需使用默认数据存储。

   • Azure CLI
   • Python
   • REST

   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>。

   提示

   工作区中的默认 Blob 数据存储称为 workspaceblobstore。 如果你已知道工作区中默认数据存储的资源 ID，则可以跳过此步骤。

2. 将一些示例数据上传到数据存储。

   此示例假设已将存储库中包含的示例数据上传到 Blob 存储帐户的文件夹 heart-disease-uci-unlabeled 中的文件夹 sdk/python/endpoints/batch/deploy-models/heart-classifier-mlflow/data。 请务必先完成此步骤，然后再继续。

3. 创建输入或请求：

   • Azure CLI
   • Python
   • REST

   将文件路径放在 INPUT_PATH 变量中：

   DATA_PATH="heart-disease-uci-unlabeled"
   INPUT_PATH="$DATASTORE_ID/paths/$DATA_PATH"
   

   请注意如何将路径的 paths 变量追加到数据存储的资源 ID。 此格式指示后面的值是路径。

   提示

   还可以使用格式 azureml://datastores/<data-store>/paths/<data-path> 来指定输入。

4. 运行终结点：

   • Azure CLI
   • Python
   • REST

   使用 --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 类型作为输入。

使用 Azure 存储帐户中的输入数据

Azure 机器学习批处理终结点可以从 Azure 存储帐户中的云位置（包括公有云和私有云）读取数据。 按照以下步骤使用存储帐户中存储的数据运行批处理终结点作业。

若要详细了解从存储帐户读取数据所需的其他配置，请参阅 配置计算群集以便进行数据访问。

1. 创建输入或请求：

   • Azure CLI
   • Python
   • REST

   设置 INPUT_DATA 变量：

   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"
   

2. 运行终结点：

   • Azure CLI
   • Python
   • REST

   使用 --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 类型作为输入。

使用文本输入创建作业

管道组件部署可以采用文本输入。 以下示例演示如何指定名为 score_mode 的输入，其类型为 string，值为 append：

inputs:
  score_mode:
    type: string
    default: append

az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.score_mode.type="string" inputs.score_mode.default="append"

job = ml_client.batch_endpoints.invoke(
    endpoint_name=endpoint.name, 
    inputs = { 
        'score_mode': Input(type="string", default="append")
        }
)

{
    "properties": {
        "InputData": {
            "score_mode": {
                "JobInputType" : "Literal",
                "Value": "append"
            }
        }
    }
}

POST jobs HTTP/1.1
Host: <ENDPOINT_URI>
Authorization: Bearer <TOKEN>
Content-Type: application/json

使用数据输出创建作业

以下示例演示如何更改命名为 score 的输出的放置位置。 为了保持内容完整，这些示例还配置了命名为 heart_dataset 的输入。

1. 使用 Azure 机器学习工作区中的默认数据存储来保存输出。 可以使用工作区中的任何其他数据存储，只要它是 Blob 存储帐户即可。

   • Azure CLI
   • Python
   • REST

   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>。

2. 创建数据输出：

   • Azure CLI
   • Python
   • REST

   设置 OUTPUT_PATH 变量：

   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"
   

   注意

   请注意如何将路径的 paths 变量追加到数据存储的资源 ID。 此格式指示后面的值是路径。

3. 运行部署：

   • Azure CLI
   • Python
   • REST

   使用 --set 参数指定输入：

   az ml batch-endpoint invoke --name $ENDPOINT_NAME \
       --set inputs.heart_dataset.path=$INPUT_PATH \
       --set outputs.score.path=$OUTPUT_PATH
   

相关内容

• 自定义模型部署批处理部署中的输出
• 从 Azure 数据工厂调用批处理终结点