获取广度和深度批量预测结果

本页面介绍如何使用 Google Cloud 控制台或 Vertex AI API 向经过训练的分类或回归模型发出批量预测请求。

批量预测请求是异步请求（与在线预测不同，在线预测是同步请求）。您可以直接从模型资源请求批量预测，而无需将模型部署到端点。对于表格数据，如果您不需要获得即时响应并且希望通过一个请求处理累积数据，则可以使用批量预测。

如需发出批量预测请求，请指定输入源和 Vertex AI 存储预测结果所采用的输出格式。

准备工作

您必须先训练模型，然后才能发出批量预测请求。

输入数据

批量预测请求的输入数据是模型用来进行预测的数据。对于分类或回归模型，您可以采用以下两种格式之一提供输入数据：

  • BigQuery 表
  • Cloud Storage 中的 CSV 对象

我们建议您为输入数据使用与训练模型时相同的格式。例如，如果您使用 BigQuery 中的数据训练模型，那么最好使用 BigQuery 表作为批量预测的输入。由于 Vertex AI 会将所有 CSV 输入字段视为字符串，因此混用不同的训练和输入数据格式可能会导致错误。

您的数据源中的表格数据必须包含用于训练模型的所有列（按任意顺序）。您可以添加不属于训练数据的列，或者属于训练数据但不用于训练的列。这些额外的列会包含在输出中，但不会影响预测结果。

输入数据要求

BigQuery 表

如果您选择 BigQuery 表作为输入，则必须确保：

  • BigQuery 数据源表不得大于 100 GB。
  • 如果该表属于其他项目，您必须向该项目中的 Vertex AI 服务账号授予 BigQuery Data Editor 角色。

CSV 文件

如果您选择 Cloud Storage 中的 CSV 对象作为输入，则必须确保：

  • 数据源必须以包含列名称的标题行开头。
  • 每个数据源对象不得大于 10 GB。可以包含多个文件，但总大小不得超过 100 GB。
  • 如果 Cloud Storage 存储桶位于其他项目中，则您必须将 Storage Object Creator 角色授予该项目中的 Vertex AI 服务账号。
  • 所有字符串必须用英文双引号 (") 括起来。

输出格式

批量预测请求的输出格式不必与用于输入的格式相同。例如，如果您将 BigQuery 表用作输入，您也可以将结果输出到 Cloud Storage 中的 CSV 对象。

向模型发出批量预测请求

如需发出批量预测请求，您可以使用 Google Cloud 控制台或 Vertex AI API。输入数据源可以是存储在 Cloud Storage 存储桶或 BigQuery 表中的 CSV 对象。批量预测任务可能需要一些时间才能完成，具体取决于您提交作为输入的数据量。

Google Cloud 控制台

使用 Google Cloud 控制台请求批量预测。

  1. 在 Google Cloud 控制台的 Vertex AI 部分中，前往批量预测页面。

    前往“批量预测”页面

  2. 点击创建以打开新建批量预测窗口。
  3. 在定义批量预测部分，完成以下步骤：
    1. 输入批量预测的名称。
    2. 在模型名称字段中，选择要用于此批量预测的模型的名称。
    3. 在版本字段中，选择要用于此批量预测的模型版本。
    4. 在选择来源字段中，选择源输入数据是 Cloud Storage 上的 CSV 文件还是 BigQuery 中的表。
      • 对于 CSV 文件，请指定 CSV 输入文件所在的 Cloud Storage 位置。
      • 对于 BigQuery 表，请指定表所在的项目 ID、BigQuery 数据集 ID 以及 BigQuery 表或视图 ID。
    5. 对于输出，选择 CSV 或 BigQuery。
      • 对于 CSV，请指定 Vertex AI 存储输出的 Cloud Storage 存储桶。
      • 对于 BigQuery，您可以指定项目 ID 或现有数据集：
        • 如需指定项目 ID，请在 Google Cloud 项目 ID 字段中输入项目 ID。Vertex AI 会为您创建新的输出数据集。
        • 如需指定现有数据集，请在 Google Cloud 项目 ID 字段中输入其 BigQuery 路径，例如 bq://projectid.datasetid。
  4. 可选：适用于批量预测的模型监控分析功能已推出预览版。请参阅将偏差检测配置添加到批量预测作业的前提条件。
    1. 点击以为此批量预测启用模型监控。
    2. 选择训练数据源。输入您选择的训练数据源的数据路径或位置。
    3. 可选：在提醒阈值下，指定触发提醒的阈值。
    4. 在通知电子邮件地址部分，输入一个或多个以英文逗号分隔的电子邮件地址，以便在模型超出提醒阈值时接收提醒。
    5. 可选：在通知渠道部分，添加 Cloud Monitoring 渠道，以便在模型超出提醒阈值时接收提醒。您可以选择现有的 Cloud Monitoring 渠道，也可以通过点击管理通知渠道来创建一个新的 Cloud Monitoring 渠道。控制台支持 PagerDuty、Slack 和 Pub/Sub 通知渠道。
  5. 点击创建。

API：BigQuery

REST

可以使用 batchPredictionJobs.create 方法请求批量预测。

在使用任何请求数据之前，请先进行以下替换：

  • LOCATION_ID：存储模型和执行批量预测作业的区域。例如 us-central1。
  • PROJECT_ID：您的项目 ID
  • BATCH_JOB_NAME：批量作业的显示名
  • MODEL_ID：用于执行预测的模型的 ID
  • INPUT_URI：对 BigQuery 数据源的引用。在此表单中执行以下操作： 
    bq://bqprojectId.bqDatasetId.bqTableId
  • OUTPUT_URI：对 BigQuery 目标位置（将写入预测结果的位置）的引用。指定项目 ID，并选择性地指定数据集 ID。如果您仅指定了项目 ID，Vertex AI 会为您创建一个新的输出数据集。请使用以下格式：
    bq://bqprojectId.bqDatasetId
  • MACHINE_TYPE：要用于此批量预测作业的机器资源。了解详情。
  • STARTING_REPLICA_COUNT：此批量预测作业的起始节点数。节点数可根据负载增加或减少，不得超过节点数上限，但始终不会低于此数量。
  • MAX_REPLICA_COUNT：此批量预测作业的节点数上限。节点数可根据负载增加或减少，但始终不会超出此上限。（可选）默认值为 10。

HTTP 方法和网址：

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/batchPredictionJobs

请求 JSON 正文： 

{
  "displayName": "BATCH_JOB_NAME",
  "model": "MODEL_ID",
  "inputConfig": {
    "instancesFormat": "bigquery",
    "bigquerySource": {
      "inputUri": "INPUT_URI"
    }
  },
  "outputConfig": {
    "predictionsFormat": "bigquery",
    "bigqueryDestination": {
      "outputUri": "OUTPUT_URI"
    }
  },
  "dedicatedResources": {
    "machineSpec": {
      "machineType": "MACHINE_TYPE",
      "acceleratorCount": "0"
    },
    "startingReplicaCount": STARTING_REPLICA_COUNT,
    "maxReplicaCount": MAX_REPLICA_COUNT
  },

}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/batchPredictionJobs"

PowerShell

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/batchPredictionJobs" | Select-Object -Expand Content

您应会收到如下所示的 JSON 响应：

{
  "name": "projects/PROJECT_ID/locations/LOCATION_ID/batchPredictionJobs/67890",
  "displayName": "batch_job_1 202005291958",
  "model": "projects/12345/locations/us-central1/models/5678",
  "state": "JOB_STATE_PENDING",
  "inputConfig": {
    "instancesFormat": "bigquery",
    "bigquerySource": {
      "inputUri": "INPUT_URI"
    }
  },
  "outputConfig": {
    "predictionsFormat": "bigquery",
    "bigqueryDestination": {
        "outputUri": bq://12345
    }
  },
  "dedicatedResources": {
    "machineSpec": {
      "machineType": "n1-standard-32",
      "acceleratorCount": "0"
    },
    "startingReplicaCount": 2,
    "maxReplicaCount": 6
  },
  "manualBatchTuningParameters": {
    "batchSize": 4
  },
  "generateExplanation": false,
  "outputInfo": {
    "bigqueryOutputDataset": "bq://12345.reg_model_2020_10_02_06_04
  }
  "state": "JOB_STATE_PENDING",
  "createTime": "2020-09-30T02:58:44.341643Z",
  "updateTime": "2020-09-30T02:58:44.341643Z",
}

Java

在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Java 设置说明执行操作。如需了解详情，请参阅 Vertex AI Java API 参考文档。

如需向 Vertex AI 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在以下示例中，将 INSTANCES_FORMAT 和 PREDICTIONS_FORMAT 替换为“bigquery”。如需了解如何替换其他占位符，请参阅本部分的“REST 和 CMD LINE”标签页。 
import com.google.cloud.aiplatform.v1.BatchPredictionJob;
import com.google.cloud.aiplatform.v1.BigQueryDestination;
import com.google.cloud.aiplatform.v1.BigQuerySource;
import com.google.cloud.aiplatform.v1.JobServiceClient;
import com.google.cloud.aiplatform.v1.JobServiceSettings;
import com.google.cloud.aiplatform.v1.LocationName;
import com.google.cloud.aiplatform.v1.ModelName;
import com.google.gson.JsonObject;
import com.google.protobuf.Value;
import com.google.protobuf.util.JsonFormat;
import java.io.IOException;

public class CreateBatchPredictionJobBigquerySample {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "PROJECT";
    String displayName = "DISPLAY_NAME";
    String modelName = "MODEL_NAME";
    String instancesFormat = "INSTANCES_FORMAT";
    String bigquerySourceInputUri = "BIGQUERY_SOURCE_INPUT_URI";
    String predictionsFormat = "PREDICTIONS_FORMAT";
    String bigqueryDestinationOutputUri = "BIGQUERY_DESTINATION_OUTPUT_URI";
    createBatchPredictionJobBigquerySample(
        project,
        displayName,
        modelName,
        instancesFormat,
        bigquerySourceInputUri,
        predictionsFormat,
        bigqueryDestinationOutputUri);
  }

  static void createBatchPredictionJobBigquerySample(
      String project,
      String displayName,
      String model,
      String instancesFormat,
      String bigquerySourceInputUri,
      String predictionsFormat,
      String bigqueryDestinationOutputUri)
      throws IOException {
    JobServiceSettings settings =
        JobServiceSettings.newBuilder()
            .setEndpoint("us-central1-aiplatform.googleapis.com:443")
            .build();
    String location = "us-central1";

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (JobServiceClient client = JobServiceClient.create(settings)) {
      JsonObject jsonModelParameters = new JsonObject();
      Value.Builder modelParametersBuilder = Value.newBuilder();
      JsonFormat.parser().merge(jsonModelParameters.toString(), modelParametersBuilder);
      Value modelParameters = modelParametersBuilder.build();
      BigQuerySource bigquerySource =
          BigQuerySource.newBuilder().setInputUri(bigquerySourceInputUri).build();
      BatchPredictionJob.InputConfig inputConfig =
          BatchPredictionJob.InputConfig.newBuilder()
              .setInstancesFormat(instancesFormat)
              .setBigquerySource(bigquerySource)
              .build();
      BigQueryDestination bigqueryDestination =
          BigQueryDestination.newBuilder().setOutputUri(bigqueryDestinationOutputUri).build();
      BatchPredictionJob.OutputConfig outputConfig =
          BatchPredictionJob.OutputConfig.newBuilder()
              .setPredictionsFormat(predictionsFormat)
              .setBigqueryDestination(bigqueryDestination)
              .build();
      String modelName = ModelName.of(project, location, model).toString();
      BatchPredictionJob batchPredictionJob =
          BatchPredictionJob.newBuilder()
              .setDisplayName(displayName)
              .setModel(modelName)
              .setModelParameters(modelParameters)
              .setInputConfig(inputConfig)
              .setOutputConfig(outputConfig)
              .build();
      LocationName parent = LocationName.of(project, location);
      BatchPredictionJob response = client.createBatchPredictionJob(parent, batchPredictionJob);
      System.out.format("response: %s\n", response);
      System.out.format("\tName: %s\n", response.getName());
    }
  }
}

Python

如需了解如何安装或更新 Python 版 Vertex AI SDK，请参阅安装 Python 版 Vertex AI SDK。如需了解详情，请参阅 Python API 参考文档。

在以下示例中，将“instances_format”和“predictions_format”参数设置为“bigquery”。如需了解如何设置其他参数，请参阅本部分的“REST 和 CMD LINE”标签页。
from google.cloud import aiplatform_v1beta1
from google.protobuf import json_format
from google.protobuf.struct_pb2 import Value

def create_batch_prediction_job_bigquery_sample(
    project: str,
    display_name: str,
    model_name: str,
    instances_format: str,
    bigquery_source_input_uri: str,
    predictions_format: str,
    bigquery_destination_output_uri: str,
    location: str = "us-central1",
    api_endpoint: str = "us-central1-aiplatform.googleapis.com",
):
    # The AI Platform services require regional API endpoints.
    client_options = {"api_endpoint": api_endpoint}
    # Initialize client that will be used to create and send requests.
    # This client only needs to be created once, and can be reused for multiple requests.
    client = aiplatform_v1beta1.JobServiceClient(client_options=client_options)
    model_parameters_dict = {}
    model_parameters = json_format.ParseDict(model_parameters_dict, Value())

    batch_prediction_job = {
        "display_name": display_name,
        # Format: 'projects/{project}/locations/{location}/models/{model_id}'
        "model": model_name,
        "model_parameters": model_parameters,
        "input_config": {
            "instances_format": instances_format,
            "bigquery_source": {"input_uri": bigquery_source_input_uri},
        },
        "output_config": {
            "predictions_format": predictions_format,
            "bigquery_destination": {"output_uri": bigquery_destination_output_uri},
        },
        # optional
        "generate_explanation": True,
    }
    parent = f"projects/{project}/locations/{location}"
    response = client.create_batch_prediction_job(
        parent=parent, batch_prediction_job=batch_prediction_job
    )
    print("response:", response)

API：Cloud Storage

REST

可以使用 batchPredictionJobs.create 方法请求批量预测。

在使用任何请求数据之前，请先进行以下替换：

  • LOCATION_ID：存储模型和执行批量预测作业的区域。例如 us-central1。
  • PROJECT_ID：您的项目 ID
  • BATCH_JOB_NAME：批量作业的显示名
  • MODEL_ID：用于执行预测的模型的 ID
  • URI：包含训练数据的 Cloud Storage 存储桶的路径 (URI)。可以有多个路径。每个 URI 的格式如下： 
    gs://bucketName/pathToFileName
  • OUTPUT_URI_PREFIX：将写入预测的 Cloud Storage 目标路径。Vertex AI 会将批量预测写入此路径上带时间戳的子目录中。将此值设置为采用以下格式的字符串：
    gs://bucketName/pathToOutputDirectory
  • MACHINE_TYPE：要用于此批量预测作业的机器资源。了解详情。
  • STARTING_REPLICA_COUNT：此批量预测作业的起始节点数。节点数可根据负载增加或减少，不得超过节点数上限，但始终不会低于此数量。
  • MAX_REPLICA_COUNT：此批量预测作业的节点数上限。节点数可根据负载增加或减少，但始终不会超出此上限。（可选）默认值为 10。

HTTP 方法和网址：

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/batchPredictionJobs

请求 JSON 正文： 

{
  "displayName": "BATCH_JOB_NAME",
  "model": "MODEL_ID",
  "inputConfig": {
    "instancesFormat": "csv",
    "gcsSource": {
      "uris": [
        URI1,...
      ]
    },
  },
  "outputConfig": {
    "predictionsFormat": "csv",
    "gcsDestination": {
      "outputUriPrefix": "OUTPUT_URI_PREFIX"
    }
  },
  "dedicatedResources": {
    "machineSpec": {
      "machineType": "MACHINE_TYPE",
      "acceleratorCount": "0"
    },
    "startingReplicaCount": STARTING_REPLICA_COUNT,
    "maxReplicaCount": MAX_REPLICA_COUNT
  },

}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/batchPredictionJobs"

PowerShell

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/batchPredictionJobs" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
  "name": "projects/PROJECT__ID/locations/LOCATION_ID/batchPredictionJobs/67890",
  "displayName": "batch_job_1 202005291958",
  "model": "projects/12345/locations/us-central1/models/5678",
  "state": "JOB_STATE_PENDING",
  "inputConfig": {
    "instancesFormat": "csv",
    "gcsSource": {
      "uris": [
        "gs://bp_bucket/reg_mode_test"
      ]
    }
  },
  "outputConfig": {
    "predictionsFormat": "csv",
    "gcsDestination": {
      "outputUriPrefix": "OUTPUT_URI_PREFIX"
    }
  },
  "dedicatedResources": {
    "machineSpec": {
      "machineType": "n1-standard-32",
      "acceleratorCount": "0"
    },
    "startingReplicaCount": 2,
    "maxReplicaCount": 6
  },
  "manualBatchTuningParameters": {
    "batchSize": 4
  }
  "outputInfo": {
    "gcsOutputDataset": "OUTPUT_URI_PREFIX/prediction-batch_job_1 202005291958-2020-09-30T02:58:44.341643Z"
  }
  "state": "JOB_STATE_PENDING",
  "createTime": "2020-09-30T02:58:44.341643Z",
  "updateTime": "2020-09-30T02:58:44.341643Z",
}

检索批量预测结果

Vertex AI 会将批量预测的输出发送到您指定的目标位置（可以是 BigQuery 或 Cloud Storage）。

BigQuery

输出数据集

如果您使用的是 BigQuery，则批量预测的输出会存储在输出数据集中。如果您为 Vertex AI 提供了数据集，则数据集 (BQ_DATASET_NAME) 的名称就是您之前提供的名称。如果您未提供输出数据集，则 Vertex AI 会为您创建一个输出数据集。您可以通过以下步骤找到其名称 (BQ_DATASET_NAME)：

  1. 在 Google Cloud 控制台中，进入 Vertex AI 批量预测页面。

    前往“批量预测”页面

  2. 选择您创建的预测。
  3. 输出数据集在导出位置中提供。数据集名称的格式如下：prediction_MODEL_NAME_TIMESTAMP
输出表

输出数据集包含以下三个输出表中的一个或多个：

  • 预测表

    此表包含输入数据中请求预测（即其中 TARGET_COLUMN_NAME = null）对应的每一行。

  • 错误表

    下表包含批量预测期间出现的每个非严重错误对应的行。每个非严重错误与输入数据中 Vertex AI 无法对其返回预测结果的行相对应。

预测表

表的名称 (BQ_PREDICTIONS_TABLE_NAME) 附加了 `predictions_` 并附加了批量预测作业开始的时间戳，格式为 predictions_TIMESTAMP

如需检索预测，请转到 BigQuery 页面。

转到 BigQuery

查询的格式取决于您的模型类型：

分类：

SELECT predicted_TARGET_COLUMN_NAME.classes AS classes,
predicted_TARGET_COLUMN_NAME.scores AS scores
FROM BQ_DATASET_NAME.BQ_PREDICTIONS_TABLE_NAME

classes 是潜在类别的列表，scores 是相应的置信度分数。

回归：

SELECT predicted_TARGET_COLUMN_NAME.value
FROM BQ_DATASET_NAME.BQ_PREDICTIONS_TABLE_NAME

如果模型使用概率推理，则 predicted_TARGET_COLUMN_NAME.value 包含优化目标的最小化器。例如，如果优化目标为 minimize-rmse，则 predicted_TARGET_COLUMN_NAME.value 包含平均值。如果优化目标为 minimize-mae，则 predicted_TARGET_COLUMN_NAME.value 包含中位数值。

如果模型将概率推理与分位数结合使用，则除了优化目标的最小化器之外，Vertex AI 还提供分位数值和预测。分位数值是在模型训练期间设置的。分位数预测是与分位数值关联的预测值。

错误表

表的名称 (BQ_ERRORS_TABLE_NAME) 附加了 errors_ 以及批量预测作业开始的时间戳，格式如下：errors_TIMESTAMP 如需检索错误验证表：

  1. 在控制台中，转到 BigQuery 页面。

    转到 BigQuery

  2. 请运行以下查询： 
    SELECT * FROM BQ_DATASET_NAME.BQ_ERRORS_TABLE_NAME
错误存储在以下列中：
  • errors_TARGET_COLUMN_NAME.code
  • errors_TARGET_COLUMN_NAME.message

Cloud Storage

如果您将 Cloud Storage 指定为输出的目标位置，则批量预测请求的结果会以 CSV 对象的形式返回到您指定的存储桶的新文件夹中。文件夹的名称是模型的名称，该名称附加了前缀“prediction-”，并附加了批量预测作业开始的时间戳。您可以在模型的批量预测标签页中找到 Cloud Storage 文件夹名称。

Cloud Storage 文件夹包含两种对象：
  • 预测对象

    预测对象名为 `predictions_1.csv`、`predictions_2.csv` 等。它们包含一个具有列名称的标题行和一个包含返回的各个预测的行。Vertex AI 会在预测对象中返回您的预测数据，并根据模型类型为预测结果创建一个或多个新列：

    • 分类：对于目标列的每个可能的值，结果中都会添加一个名为 TARGET_COLUMN_NAME_VALUE_score 的列。此列包含对应值的分数或置信度估计值。
    • 回归：对应行的预测值会返回到名为 predicted_TARGET_COLUMN_NAME 的列。系统不会为 CSV 输出返回预测区间。
  • 错误对象

    错误对象名为 `errors_1.csv`、`errors_2.csv` 等。 它们包含一个标题行，还包含输入数据中 Vertex AI 无法返回预测（例如，如果不可为 Null 的特征为 Null）的每一行。

注意：如果结果较大，则会拆分为多个对象。

解读预测结果

分类

分类模型会返回置信度分数。

置信度分数传达了模型将每个类列或标签与测试项相关联的强度。该数值越高，模型应用于该项的置信度就越高。您可以决定接受模型的置信度分数为多高。

回归

回归模型会返回预测值。

如果模型使用概率推理，则 value 字段包含优化目标的最小化器。例如，如果优化目标为 minimize-rmse，则 value 字段包含平均值。如果优化目标为 minimize-mae，则 value 字段包含中位数值。

如果模型将概率推理与分位数结合使用，则除了优化目标的最小化器之外，Vertex AI 还提供分位数值和预测。分位数值是在模型训练期间设置的。分位数预测是与分位数值关联的预测值。

后续步骤