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

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

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

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

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

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

  • Azure CLI
  • Python
  • REST

  为用户帐户获取有效令牌的最简单方法是使用 Azure CLI。 在控制台中，运行以下 Azure CLI 命令：

  az account get-access-token --resource https://studio.ml.azure.cn --query "accessToken" --output tsv
  

  提示

  使用 REST 时，建议使用服务主体调用批处理终结点。 有关详细信息，请参阅使用服务主体 (REST) 运行作业，了解如何使用 REST 获取服务主体的令牌。

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

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

  提示

  如果使用无凭据数据存储或外部 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

   使用 Azure 机器学习 CLI、适用于 Python 的 Azure 机器学习 SDK 或 Azure 机器学习工作室以获取位置（区域）、工作区以及数据资产名称和版本。 在后续过程中，你需要这些项。

2. 创建输入或请求：

   • Azure CLI
   • Python
   • REST

   正文

   {
       "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 格式来指定输入。

3. 运行终结点：

   • Azure CLI
   • Python
   • REST

   Request

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

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

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

   • Azure CLI
   • Python
   • REST

   使用 Azure 机器学习 CLI、适用于 Python 的 Azure 机器学习 SDK 或工作室获取数据存储信息。

   提示

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

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

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

3. 创建输入或请求：

   • Azure CLI
   • Python
   • REST

   正文

   {
       "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> 来指定输入。

4. 运行终结点：

   • Azure CLI
   • Python
   • REST

   Request

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

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

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

1. 创建输入或请求：

   • Azure CLI
   • Python
   • REST

   正文

   {
      "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"
              }
          }
      }
   }
   

2. 运行终结点：

   • Azure CLI
   • Python
   • REST

   Request

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

管道组件部署可以采用文本输入。 以下示例演示如何指定名为 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

   使用 Azure 机器学习 CLI、适用于 Python 的 Azure 机器学习 SDK 或工作室获取数据存储信息。

2. 创建数据输出：

   • Azure CLI
   • Python
   • REST

   正文

   {
       "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。 此格式指示后面的值是路径。

3. 运行部署：

   • Azure CLI
   • Python
   • REST

   Request

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

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