REST Resource: projects.locations.batchPredictionJobs

Resource: BatchPredictionJob

A job that uses a Model to produce predictions on multiple input instances. If predictions for significant portion of the instances fail, the job may finish without attempting predictions for all remaining instances.

JSON representation
{
  "name": string,
  "displayName": string,
  "model": string,
  "modelVersionId": string,
  "unmanagedContainerModel": {
    object (UnmanagedContainerModel)
  },
  "inputConfig": {
    object (InputConfig)
  },
  "instanceConfig": {
    object (InstanceConfig)
  },
  "modelParameters": value,
  "outputConfig": {
    object (OutputConfig)
  },
  "dedicatedResources": {
    object (BatchDedicatedResources)
  },
  "serviceAccount": string,
  "manualBatchTuningParameters": {
    object (ManualBatchTuningParameters)
  },
  "generateExplanation": boolean,
  "explanationSpec": {
    object (ExplanationSpec)
  },
  "outputInfo": {
    object (OutputInfo)
  },
  "state": enum (JobState),
  "error": {
    object (Status)
  },
  "partialFailures": [
    {
      object (Status)
    }
  ],
  "resourcesConsumed": {
    object (ResourcesConsumed)
  },
  "completionStats": {
    object (CompletionStats)
  },
  "createTime": string,
  "startTime": string,
  "endTime": string,
  "updateTime": string,
  "labels": {
    string: string,
    ...
  },
  "encryptionSpec": {
    object (EncryptionSpec)
  },
  "modelMonitoringConfig": {
    object (ModelMonitoringConfig)
  },
  "modelMonitoringStatsAnomalies": [
    {
      object (ModelMonitoringStatsAnomalies)
    }
  ],
  "modelMonitoringStatus": {
    object (Status)
  },
  "disableContainerLogging": boolean
}
Fields
name

string

Output only. Resource name of the BatchPredictionJob.

displayName

string

Required. The user-defined name of this BatchPredictionJob.

model

string

The name of the Model resource that produces the predictions via this job, must share the same ancestor Location. Starting this job has no impact on any existing deployments of the Model and their resources. Exactly one of model and unmanagedContainerModel must be set.

The model resource name may contain version id or version alias to specify the version. Example: projects/{project}/locations/{location}/models/{model}@2 or projects/{project}/locations/{location}/models/{model}@golden if no version is specified, the default version will be deployed.

The model resource could also be a publisher model. Example: publishers/{publisher}/models/{model} or projects/{project}/locations/{location}/publishers/{publisher}/models/{model}

modelVersionId

string

Output only. The version ID of the Model that produces the predictions via this job.

unmanagedContainerModel

object (UnmanagedContainerModel)

Contains model information necessary to perform batch prediction without requiring uploading to model registry. Exactly one of model and unmanagedContainerModel must be set.

inputConfig

object (InputConfig)

Required. Input configuration of the instances on which predictions are performed. The schema of any single instance may be specified via the Model's PredictSchemata's instanceSchemaUri.

instanceConfig

object (InstanceConfig)

Configuration for how to convert batch prediction input instances to the prediction instances that are sent to the Model.

modelParameters

value (Value format)

The parameters that govern the predictions. The schema of the parameters may be specified via the Model's PredictSchemata's parametersSchemaUri.

outputConfig

object (OutputConfig)

Required. The Configuration specifying where output predictions should be written. The schema of any single prediction may be specified as a concatenation of Model's PredictSchemata's instanceSchemaUri and predictionSchemaUri.

dedicatedResources

object (BatchDedicatedResources)

The config of resources used by the Model during the batch prediction. If the Model supports DEDICATED_RESOURCES this config may be provided (and the job will use these resources), if the Model doesn't support AUTOMATIC_RESOURCES, this config must be provided.

serviceAccount

string

The service account that the DeployedModel's container runs as. If not specified, a system generated one will be used, which has minimal permissions and the custom container, if used, may not have enough permission to access other Google Cloud resources.

Users deploying the Model must have the iam.serviceAccounts.actAs permission on this service account.

manualBatchTuningParameters

object (ManualBatchTuningParameters)

Immutable. Parameters configuring the batch behavior. Currently only applicable when dedicatedResources are used (in other cases Vertex AI does the tuning itself).

generateExplanation

boolean

Generate explanation with the batch prediction results.

When set to true, the batch prediction output changes based on the predictionsFormat field of the BatchPredictionJob.output_config object:

  • bigquery: output includes a column named explanation. The value is a struct that conforms to the Explanation object.
  • jsonl: The JSON objects on each line include an additional entry keyed explanation. The value of the entry is a JSON object that conforms to the Explanation object.
  • csv: Generating explanations for CSV format is not supported.

If this field is set to true, either the Model.explanation_spec or explanationSpec must be populated.

explanationSpec

object (ExplanationSpec)

Explanation configuration for this BatchPredictionJob. Can be specified only if generateExplanation is set to true.

This value overrides the value of Model.explanation_spec. All fields of explanationSpec are optional in the request. If a field of the explanationSpec object is not populated, the corresponding field of the Model.explanation_spec object is inherited.

outputInfo

object (OutputInfo)

Output only. Information further describing the output of this job.

state

enum (JobState)

Output only. The detailed state of the job.

error

object (Status)

Output only. Only populated when the job's state is JOB_STATE_FAILED or JOB_STATE_CANCELLED.

partialFailures[]

object (Status)

Output only. Partial failures encountered. For example, single files that can't be read. This field never exceeds 20 entries. Status details fields contain standard Google Cloud error details.

resourcesConsumed

object (ResourcesConsumed)

Output only. Information about resources that had been consumed by this job. Provided in real time at best effort basis, as well as a final value once the job completes.

Note: This field currently may be not populated for batch predictions that use AutoML Models.

completionStats

object (CompletionStats)

Output only. Statistics on completed and failed prediction instances.

createTime

string (Timestamp format)

Output only. time when the BatchPredictionJob was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

startTime

string (Timestamp format)

Output only. time when the BatchPredictionJob for the first time entered the JOB_STATE_RUNNING state.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

endTime

string (Timestamp format)

Output only. time when the BatchPredictionJob entered any of the following states: JOB_STATE_SUCCEEDED, JOB_STATE_FAILED, JOB_STATE_CANCELLED.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

updateTime

string (Timestamp format)

Output only. time when the BatchPredictionJob was most recently updated.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

labels

map (key: string, value: string)

The labels with user-defined metadata to organize BatchPredictionJobs.

label keys and values can be no longer than 64 characters (Unicode codepoints), can only contain lowercase letters, numeric characters, underscores and dashes. International characters are allowed.

See https://goo.gl/xmQnxf for more information and examples of labels.

encryptionSpec

object (EncryptionSpec)

Customer-managed encryption key options for a BatchPredictionJob. If this is set, then all resources created by the BatchPredictionJob will be encrypted with the provided encryption key.

modelMonitoringConfig

object (ModelMonitoringConfig)

Model monitoring config will be used for analysis model behaviors, based on the input and output to the batch prediction job, as well as the provided training dataset.

modelMonitoringStatsAnomalies[]

object (ModelMonitoringStatsAnomalies)

Get batch prediction job monitoring statistics.

modelMonitoringStatus

object (Status)

Output only. The running status of the model monitoring pipeline.

disableContainerLogging

boolean

For custom-trained Models and AutoML Tabular Models, the container of the DeployedModel instances will send stderr and stdout streams to Cloud Logging by default. Please note that the logs incur cost, which are subject to Cloud Logging pricing.

user can disable container logging by setting this flag to true.

UnmanagedContainerModel

Contains model information necessary to perform batch prediction without requiring a full model import.

JSON representation
{
  "artifactUri": string,
  "predictSchemata": {
    object (PredictSchemata)
  },
  "containerSpec": {
    object (ModelContainerSpec)
  }
}
Fields
artifactUri

string

The path to the directory containing the Model artifact and any of its supporting files.

predictSchemata

object (PredictSchemata)

Contains the schemata used in Model's predictions and explanations

containerSpec

object (ModelContainerSpec)

Input only. The specification of the container that is to be used when deploying this Model.

InputConfig

Configures the input to BatchPredictionJob. See Model.supported_input_storage_formats for Model's supported input formats, and how instances should be expressed via any of them.

JSON representation
{
  "instancesFormat": string,

  // Union field source can be only one of the following:
  "gcsSource": {
    object (GcsSource)
  },
  "bigquerySource": {
    object (BigQuerySource)
  }
  // End of list of possible types for union field source.
}
Fields
instancesFormat

string

Required. The format in which instances are given, must be one of the Model's supportedInputStorageFormats.

Union field source. Required. The source of the input. source can be only one of the following:
gcsSource

object (GcsSource)

The Cloud Storage location for the input instances.

bigquerySource

object (BigQuerySource)

The BigQuery location of the input table. The schema of the table should be in the format described by the given context OpenAPI Schema, if one is provided. The table may contain additional columns that are not described by the schema, and they will be ignored.

InstanceConfig

Configuration defining how to transform batch prediction input instances to the instances that the Model accepts.

JSON representation
{
  "instanceType": string,
  "keyField": string,
  "includedFields": [
    string
  ],
  "excludedFields": [
    string
  ]
}
Fields
instanceType

string

The format of the instance that the Model accepts. Vertex AI will convert compatible batch prediction input instance formats to the specified format.

Supported values are:

  • object: Each input is converted to JSON object format.

    • For bigquery, each row is converted to an object.
    • For jsonl, each line of the JSONL input must be an object.
    • Does not apply to csv, file-list, tf-record, or tf-record-gzip.
  • array: Each input is converted to JSON array format.

    • For bigquery, each row is converted to an array. The order of columns is determined by the BigQuery column order, unless includedFields is populated. includedFields must be populated for specifying field orders.
    • For jsonl, if each line of the JSONL input is an object, includedFields must be populated for specifying field orders.
    • Does not apply to csv, file-list, tf-record, or tf-record-gzip.

If not specified, Vertex AI converts the batch prediction input as follows:

  • For bigquery and csv, the behavior is the same as array. The order of columns is the same as defined in the file or table, unless includedFields is populated.
  • For jsonl, the prediction instance format is determined by each line of the input.
  • For tf-record/tf-record-gzip, each record will be converted to an object in the format of {"b64": <value>}, where <value> is the Base64-encoded string of the content of the record.
  • For file-list, each file in the list will be converted to an object in the format of {"b64": <value>}, where <value> is the Base64-encoded string of the content of the file.
keyField

string

The name of the field that is considered as a key.

The values identified by the key field is not included in the transformed instances that is sent to the Model. This is similar to specifying this name of the field in excludedFields. In addition, the batch prediction output will not include the instances. Instead the output will only include the value of the key field, in a field named key in the output:

  • For jsonl output format, the output will have a key field instead of the instance field.
  • For csv/bigquery output format, the output will have have a key column instead of the instance feature columns.

The input must be JSONL with objects at each line, CSV, BigQuery or TfRecord.

includedFields[]

string

Fields that will be included in the prediction instance that is sent to the Model.

If instanceType is array, the order of field names in includedFields also determines the order of the values in the array.

When includedFields is populated, excludedFields must be empty.

The input must be JSONL with objects at each line, BigQuery or TfRecord.

excludedFields[]

string

Fields that will be excluded in the prediction instance that is sent to the Model.

Excluded will be attached to the batch prediction output if keyField is not specified.

When excludedFields is populated, includedFields must be empty.

The input must be JSONL with objects at each line, BigQuery or TfRecord.

OutputConfig

Configures the output of BatchPredictionJob. See Model.supported_output_storage_formats for supported output formats, and how predictions are expressed via any of them.

JSON representation
{
  "predictionsFormat": string,

  // Union field destination can be only one of the following:
  "gcsDestination": {
    object (GcsDestination)
  },
  "bigqueryDestination": {
    object (BigQueryDestination)
  }
  // End of list of possible types for union field destination.
}
Fields
predictionsFormat

string

Required. The format in which Vertex AI gives the predictions, must be one of the Model's supportedOutputStorageFormats.

Union field destination. Required. The destination of the output. destination can be only one of the following:
gcsDestination

object (GcsDestination)

The Cloud Storage location of the directory where the output is to be written to. In the given directory a new directory is created. Its name is prediction-<model-display-name>-<job-create-time>, where timestamp is in YYYY-MM-DDThh:mm:ss.sssZ ISO-8601 format. Inside of it files predictions_0001.<extension>, predictions_0002.<extension>, ..., predictions_N.<extension> are created where <extension> depends on chosen predictionsFormat, and N may equal 0001 and depends on the total number of successfully predicted instances. If the Model has both instance and prediction schemata defined then each such file contains predictions as per the predictionsFormat. If prediction for any instance failed (partially or completely), then an additional errors_0001.<extension>, errors_0002.<extension>,..., errors_N.<extension> files are created (N depends on total number of failed predictions). These files contain the failed instances, as per their schema, followed by an additional error field which as value has google.rpc.Status containing only code and message fields.

bigqueryDestination

object (BigQueryDestination)

The BigQuery project or dataset location where the output is to be written to. If project is provided, a new dataset is created with name prediction_<model-display-name>_<job-create-time> where is made BigQuery-dataset-name compatible (for example, most special characters become underscores), and timestamp is in YYYY_MM_DDThh_mm_ss_sssZ "based on ISO-8601" format. In the dataset two tables will be created, predictions, and errors. If the Model has both instance and prediction schemata defined then the tables have columns as follows: The predictions table contains instances for which the prediction succeeded, it has columns as per a concatenation of the Model's instance and prediction schemata. The errors table contains rows for which the prediction has failed, it has instance columns, as per the instance schema, followed by a single "errors" column, which as values has google.rpc.Status represented as a STRUCT, and containing only code and message.

BatchDedicatedResources

A description of resources that are used for performing batch operations, are dedicated to a Model, and need manual configuration.

JSON representation
{
  "machineSpec": {
    object (MachineSpec)
  },
  "startingReplicaCount": integer,
  "maxReplicaCount": integer
}
Fields
machineSpec

object (MachineSpec)

Required. Immutable. The specification of a single machine.

startingReplicaCount

integer

Immutable. The number of machine replicas used at the start of the batch operation. If not set, Vertex AI decides starting number, not greater than maxReplicaCount

maxReplicaCount

integer

Immutable. The maximum number of machine replicas the batch operation may be scaled to. The default value is 10.

ManualBatchTuningParameters

Manual batch tuning parameters.

JSON representation
{
  "batchSize": integer
}
Fields
batchSize

integer

Immutable. The number of the records (e.g. instances) of the operation given in each batch to a machine replica. Machine type, and size of a single record should be considered when setting this parameter, higher value speeds up the batch operation's execution, but too high value will result in a whole batch not fitting in a machine's memory, and the whole operation will fail. The default value is 64.

OutputInfo

Further describes this job's output. Supplements outputConfig.

JSON representation
{
  "bigqueryOutputTable": string,

  // Union field output_location can be only one of the following:
  "gcsOutputDirectory": string,
  "bigqueryOutputDataset": string
  // End of list of possible types for union field output_location.
}
Fields
bigqueryOutputTable

string

Output only. The name of the BigQuery table created, in predictions_<timestamp> format, into which the prediction output is written. Can be used by UI to generate the BigQuery output path, for example.

Union field output_location. The output location into which prediction output is written. output_location can be only one of the following:
gcsOutputDirectory

string

Output only. The full path of the Cloud Storage directory created, into which the prediction output is written.

bigqueryOutputDataset

string

Output only. The path of the BigQuery dataset created, in bq://projectId.bqDatasetId format, into which the prediction output is written.

ResourcesConsumed

Statistics information about resource consumption.

JSON representation
{
  "replicaHours": number
}
Fields
replicaHours

number

Output only. The number of replica hours used. Note that many replicas may run in parallel, and additionally any given work may be queued for some time. Therefore this value is not strictly related to wall time.

CompletionStats

Success and error statistics of processing multiple entities (for example, DataItems or structured data rows) in batch.

JSON representation
{
  "successfulCount": string,
  "failedCount": string,
  "incompleteCount": string,
  "successfulForecastPointCount": string
}
Fields
successfulCount

string (int64 format)

Output only. The number of entities that had been processed successfully.

failedCount

string (int64 format)

Output only. The number of entities for which any error was encountered.

incompleteCount

string (int64 format)

Output only. In cases when enough errors are encountered a job, pipeline, or operation may be failed as a whole. Below is the number of entities for which the processing had not been finished (either in successful or failed state). Set to -1 if the number is unknown (for example, the operation failed before the total entity number could be collected).

successfulForecastPointCount

string (int64 format)

Output only. The number of the successful forecast points that are generated by the forecasting model. This is ONLY used by the forecasting batch prediction.

ModelMonitoringConfig

The model monitoring configuration used for Batch Prediction Job.

JSON representation
{
  "objectiveConfigs": [
    {
      object (ModelMonitoringObjectiveConfig)
    }
  ],
  "alertConfig": {
    object (ModelMonitoringAlertConfig)
  },
  "analysisInstanceSchemaUri": string,
  "statsAnomaliesBaseDirectory": {
    object (GcsDestination)
  }
}
Fields
objectiveConfigs[]

object (ModelMonitoringObjectiveConfig)

Model monitoring objective config.

alertConfig

object (ModelMonitoringAlertConfig)

Model monitoring alert config.

analysisInstanceSchemaUri

string

YAML schema file uri in Cloud Storage describing the format of a single instance that you want Tensorflow Data Validation (TFDV) to analyze.

If there are any data type differences between predict instance and TFDV instance, this field can be used to override the schema. For models trained with Vertex AI, this field must be set as all the fields in predict instance formatted as string.

statsAnomaliesBaseDirectory

object (GcsDestination)

A Google Cloud Storage location for batch prediction model monitoring to dump statistics and anomalies. If not provided, a folder will be created in customer project to hold statistics and anomalies.

ModelMonitoringStatsAnomalies

Statistics and anomalies generated by Model Monitoring.

JSON representation
{
  "objective": enum (ModelDeploymentMonitoringObjectiveType),
  "deployedModelId": string,
  "anomalyCount": integer,
  "featureStats": [
    {
      object (FeatureHistoricStatsAnomalies)
    }
  ]
}
Fields
objective

enum (ModelDeploymentMonitoringObjectiveType)

Model Monitoring Objective those stats and anomalies belonging to.

deployedModelId

string

Deployed Model ID.

anomalyCount

integer

Number of anomalies within all stats.

featureStats[]

object (FeatureHistoricStatsAnomalies)

A list of historical Stats and Anomalies generated for all Features.

ModelDeploymentMonitoringObjectiveType

The Model Monitoring Objective types.

Enums
MODEL_DEPLOYMENT_MONITORING_OBJECTIVE_TYPE_UNSPECIFIED Default value, should not be set.
RAW_FEATURE_SKEW Raw feature values' stats to detect skew between Training-Prediction datasets.
RAW_FEATURE_DRIFT Raw feature values' stats to detect drift between Serving-Prediction datasets.
FEATURE_ATTRIBUTION_SKEW feature attribution scores to detect skew between Training-Prediction datasets.
FEATURE_ATTRIBUTION_DRIFT feature attribution scores to detect skew between Prediction datasets collected within different time windows.

FeatureHistoricStatsAnomalies

Historical Stats (and Anomalies) for a specific feature.

JSON representation
{
  "featureDisplayName": string,
  "threshold": {
    object (ThresholdConfig)
  },
  "trainingStats": {
    object (FeatureStatsAnomaly)
  },
  "predictionStats": [
    {
      object (FeatureStatsAnomaly)
    }
  ]
}
Fields
featureDisplayName

string

Display name of the feature.

threshold

object (ThresholdConfig)

Threshold for anomaly detection.

trainingStats

object (FeatureStatsAnomaly)

Stats calculated for the Training Dataset.

predictionStats[]

object (FeatureStatsAnomaly)

A list of historical stats generated by different time window's Prediction Dataset.

Methods

cancel

Cancels a BatchPredictionJob.

create

Creates a BatchPredictionJob.

delete

Deletes a BatchPredictionJob.

get

Gets a BatchPredictionJob

list

Lists BatchPredictionJobs in a Location.