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

批处理终结点可用于对大量数据执行长时间运行的批处理操作。 此类数据可以放在不同的位置。 某些类型的批处理终结点还可以接收文本参数作为输入。 本教程介绍如何指定文本参数输入,以及支持的不同类型或位置。

调用终结点之前

若要成功调用批处理终结点并创建作业,请确保具备以下各项条件:

  • 有权限运行批处理终结点部署。 参阅批处理终结点上的授权,以了解所需的特定权限。

  • 有一个有效的 Microsoft Entra ID 令牌,表示要调用终结点的安全主体。 此主体可以是用户主体或服务主体。 在任一情况下,一旦调用终结点,就会在与令牌关联的标识下创建批处理部署作业。 出于测试目的,可以使用自己的凭据进行调用,如下所示。

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

      az cloud set -n AzureChinaCloud
    az login
    

    若要详细了解如何使用多种类型的凭据进行身份验证,请阅读批处理终结点上的授权

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

    提示

    如果使用无凭据数据存储或外部 Azure 存储帐户作为数据输入,请确保为数据访问配置计算群集计算群集的托管标识用于装载存储帐户。 作业(调用程序)的标识仍用于读取基础数据,以便实现精细访问控制。

了解输入和输出

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

Diagram showing how inputs and outputs are used in batch endpoints.

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

  • 数据输入,这些输入是指向特定存储位置或 Azure 机器学习资产的指针。
  • 文本输入,即要传递给作业的文本值(如数字或字符串)。

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

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

部署类型 输入的数量 支持的输入类型 输出的数量 支持的输出类型
模型部署 1 数据输入 1 数据输出

提示

始终对输入和输出命名。 这些名称充当用于标识它们的关键值,并在调用期间传递实际值。 由于模型部署始终需要一个输入和输出,因此在调用期间会忽略该名称。 可以指定最能描述用例的名称,如“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) 的数据资产。

  1. 首先创建数据资产。 此数据资产由包含多个 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
    
  2. 创建输入或请求:

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

    注意

    数据资产 ID 类似于 /subscriptions/<subscription>/resourcegroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/data/<data-asset>/versions/<version>。 还可以使用 azureml:/<datasset_name>@latest 作为指定输入的方法。

  3. 运行终结点:

    使用 --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 机器学习工作区中的默认数据存储。 如果你的数据位于其他存储中,可以改用该存储。 无需使用默认数据存储。

    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. 创建输入或请求:

    将文件路径放在以下变量中:

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

    注意

    了解如何将路径 paths 追加到数据存储的资源 ID,以指示后面跟随的是它中的路径。

    提示

    还可以将 azureml://datastores/<data-store>/paths/<data-path> 用作指定输入的方法。

  4. 运行终结点:

    使用 --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. 创建输入或请求:

    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. 运行终结点:

    使用 --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 的输出的放置位置。 为了保持内容完整,这些示例还配置了命名为 heart_dataset 的输入。

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

  2. 创建数据输出:

    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. 运行部署:

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

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

调用特定部署

Batch 终结点可以在同一终结点下托管多个部署。 除非用户另有指定,否则使用默认终结点。 可以按如下所示方法更改所使用的部署:

使用参数--deployment-name-d指定部署的名称:

az ml batch-endpoint invoke --name $ENDPOINT_NAME --deployment-name $DEPLOYMENT_NAME --input $INPUT_DATA

后续步骤