1// Copyright 2023 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.cloud.aiplatform.v1; 18 19import "google/api/annotations.proto"; 20import "google/api/client.proto"; 21import "google/api/field_behavior.proto"; 22import "google/api/httpbody.proto"; 23import "google/api/resource.proto"; 24import "google/cloud/aiplatform/v1/explanation.proto"; 25import "google/protobuf/struct.proto"; 26 27option csharp_namespace = "Google.Cloud.AIPlatform.V1"; 28option go_package = "cloud.google.com/go/aiplatform/apiv1/aiplatformpb;aiplatformpb"; 29option java_multiple_files = true; 30option java_outer_classname = "PredictionServiceProto"; 31option java_package = "com.google.cloud.aiplatform.v1"; 32option php_namespace = "Google\\Cloud\\AIPlatform\\V1"; 33option ruby_package = "Google::Cloud::AIPlatform::V1"; 34 35// A service for online predictions and explanations. 36service PredictionService { 37 option (google.api.default_host) = "aiplatform.googleapis.com"; 38 option (google.api.oauth_scopes) = 39 "https://www.googleapis.com/auth/cloud-platform"; 40 41 // Perform an online prediction. 42 rpc Predict(PredictRequest) returns (PredictResponse) { 43 option (google.api.http) = { 44 post: "/v1/{endpoint=projects/*/locations/*/endpoints/*}:predict" 45 body: "*" 46 additional_bindings { 47 post: "/v1/{endpoint=projects/*/locations/*/publishers/*/models/*}:predict" 48 body: "*" 49 } 50 }; 51 option (google.api.method_signature) = "endpoint,instances,parameters"; 52 } 53 54 // Perform an online prediction with an arbitrary HTTP payload. 55 // 56 // The response includes the following HTTP headers: 57 // 58 // * `X-Vertex-AI-Endpoint-Id`: ID of the 59 // [Endpoint][google.cloud.aiplatform.v1.Endpoint] that served this 60 // prediction. 61 // 62 // * `X-Vertex-AI-Deployed-Model-Id`: ID of the Endpoint's 63 // [DeployedModel][google.cloud.aiplatform.v1.DeployedModel] that served this 64 // prediction. 65 rpc RawPredict(RawPredictRequest) returns (google.api.HttpBody) { 66 option (google.api.http) = { 67 post: "/v1/{endpoint=projects/*/locations/*/endpoints/*}:rawPredict" 68 body: "*" 69 additional_bindings { 70 post: "/v1/{endpoint=projects/*/locations/*/publishers/*/models/*}:rawPredict" 71 body: "*" 72 } 73 }; 74 option (google.api.method_signature) = "endpoint,http_body"; 75 } 76 77 // Perform an online explanation. 78 // 79 // If 80 // [deployed_model_id][google.cloud.aiplatform.v1.ExplainRequest.deployed_model_id] 81 // is specified, the corresponding DeployModel must have 82 // [explanation_spec][google.cloud.aiplatform.v1.DeployedModel.explanation_spec] 83 // populated. If 84 // [deployed_model_id][google.cloud.aiplatform.v1.ExplainRequest.deployed_model_id] 85 // is not specified, all DeployedModels must have 86 // [explanation_spec][google.cloud.aiplatform.v1.DeployedModel.explanation_spec] 87 // populated. Only deployed AutoML tabular Models have 88 // explanation_spec. 89 rpc Explain(ExplainRequest) returns (ExplainResponse) { 90 option (google.api.http) = { 91 post: "/v1/{endpoint=projects/*/locations/*/endpoints/*}:explain" 92 body: "*" 93 }; 94 option (google.api.method_signature) = 95 "endpoint,instances,parameters,deployed_model_id"; 96 } 97} 98 99// Request message for 100// [PredictionService.Predict][google.cloud.aiplatform.v1.PredictionService.Predict]. 101message PredictRequest { 102 // Required. The name of the Endpoint requested to serve the prediction. 103 // Format: 104 // `projects/{project}/locations/{location}/endpoints/{endpoint}` 105 string endpoint = 1 [ 106 (google.api.field_behavior) = REQUIRED, 107 (google.api.resource_reference) = { 108 type: "aiplatform.googleapis.com/Endpoint" 109 } 110 ]; 111 112 // Required. The instances that are the input to the prediction call. 113 // A DeployedModel may have an upper limit on the number of instances it 114 // supports per request, and when it is exceeded the prediction call errors 115 // in case of AutoML Models, or, in case of customer created Models, the 116 // behaviour is as documented by that Model. 117 // The schema of any single instance may be specified via Endpoint's 118 // DeployedModels' [Model's][google.cloud.aiplatform.v1.DeployedModel.model] 119 // [PredictSchemata's][google.cloud.aiplatform.v1.Model.predict_schemata] 120 // [instance_schema_uri][google.cloud.aiplatform.v1.PredictSchemata.instance_schema_uri]. 121 repeated google.protobuf.Value instances = 2 122 [(google.api.field_behavior) = REQUIRED]; 123 124 // The parameters that govern the prediction. The schema of the parameters may 125 // be specified via Endpoint's DeployedModels' [Model's 126 // ][google.cloud.aiplatform.v1.DeployedModel.model] 127 // [PredictSchemata's][google.cloud.aiplatform.v1.Model.predict_schemata] 128 // [parameters_schema_uri][google.cloud.aiplatform.v1.PredictSchemata.parameters_schema_uri]. 129 google.protobuf.Value parameters = 3; 130} 131 132// Response message for 133// [PredictionService.Predict][google.cloud.aiplatform.v1.PredictionService.Predict]. 134message PredictResponse { 135 // The predictions that are the output of the predictions call. 136 // The schema of any single prediction may be specified via Endpoint's 137 // DeployedModels' [Model's ][google.cloud.aiplatform.v1.DeployedModel.model] 138 // [PredictSchemata's][google.cloud.aiplatform.v1.Model.predict_schemata] 139 // [prediction_schema_uri][google.cloud.aiplatform.v1.PredictSchemata.prediction_schema_uri]. 140 repeated google.protobuf.Value predictions = 1; 141 142 // ID of the Endpoint's DeployedModel that served this prediction. 143 string deployed_model_id = 2; 144 145 // Output only. The resource name of the Model which is deployed as the 146 // DeployedModel that this prediction hits. 147 string model = 3 [ 148 (google.api.field_behavior) = OUTPUT_ONLY, 149 (google.api.resource_reference) = { 150 type: "aiplatform.googleapis.com/Model" 151 } 152 ]; 153 154 // Output only. The version ID of the Model which is deployed as the 155 // DeployedModel that this prediction hits. 156 string model_version_id = 5 [(google.api.field_behavior) = OUTPUT_ONLY]; 157 158 // Output only. The [display 159 // name][google.cloud.aiplatform.v1.Model.display_name] of the Model which is 160 // deployed as the DeployedModel that this prediction hits. 161 string model_display_name = 4 [(google.api.field_behavior) = OUTPUT_ONLY]; 162} 163 164// Request message for 165// [PredictionService.RawPredict][google.cloud.aiplatform.v1.PredictionService.RawPredict]. 166message RawPredictRequest { 167 // Required. The name of the Endpoint requested to serve the prediction. 168 // Format: 169 // `projects/{project}/locations/{location}/endpoints/{endpoint}` 170 string endpoint = 1 [ 171 (google.api.field_behavior) = REQUIRED, 172 (google.api.resource_reference) = { 173 type: "aiplatform.googleapis.com/Endpoint" 174 } 175 ]; 176 177 // The prediction input. Supports HTTP headers and arbitrary data payload. 178 // 179 // A [DeployedModel][google.cloud.aiplatform.v1.DeployedModel] may have an 180 // upper limit on the number of instances it supports per request. When this 181 // limit it is exceeded for an AutoML model, the 182 // [RawPredict][google.cloud.aiplatform.v1.PredictionService.RawPredict] 183 // method returns an error. When this limit is exceeded for a custom-trained 184 // model, the behavior varies depending on the model. 185 // 186 // You can specify the schema for each instance in the 187 // [predict_schemata.instance_schema_uri][google.cloud.aiplatform.v1.PredictSchemata.instance_schema_uri] 188 // field when you create a [Model][google.cloud.aiplatform.v1.Model]. This 189 // schema applies when you deploy the `Model` as a `DeployedModel` to an 190 // [Endpoint][google.cloud.aiplatform.v1.Endpoint] and use the `RawPredict` 191 // method. 192 google.api.HttpBody http_body = 2; 193} 194 195// Request message for 196// [PredictionService.Explain][google.cloud.aiplatform.v1.PredictionService.Explain]. 197message ExplainRequest { 198 // Required. The name of the Endpoint requested to serve the explanation. 199 // Format: 200 // `projects/{project}/locations/{location}/endpoints/{endpoint}` 201 string endpoint = 1 [ 202 (google.api.field_behavior) = REQUIRED, 203 (google.api.resource_reference) = { 204 type: "aiplatform.googleapis.com/Endpoint" 205 } 206 ]; 207 208 // Required. The instances that are the input to the explanation call. 209 // A DeployedModel may have an upper limit on the number of instances it 210 // supports per request, and when it is exceeded the explanation call errors 211 // in case of AutoML Models, or, in case of customer created Models, the 212 // behaviour is as documented by that Model. 213 // The schema of any single instance may be specified via Endpoint's 214 // DeployedModels' [Model's][google.cloud.aiplatform.v1.DeployedModel.model] 215 // [PredictSchemata's][google.cloud.aiplatform.v1.Model.predict_schemata] 216 // [instance_schema_uri][google.cloud.aiplatform.v1.PredictSchemata.instance_schema_uri]. 217 repeated google.protobuf.Value instances = 2 218 [(google.api.field_behavior) = REQUIRED]; 219 220 // The parameters that govern the prediction. The schema of the parameters may 221 // be specified via Endpoint's DeployedModels' [Model's 222 // ][google.cloud.aiplatform.v1.DeployedModel.model] 223 // [PredictSchemata's][google.cloud.aiplatform.v1.Model.predict_schemata] 224 // [parameters_schema_uri][google.cloud.aiplatform.v1.PredictSchemata.parameters_schema_uri]. 225 google.protobuf.Value parameters = 4; 226 227 // If specified, overrides the 228 // [explanation_spec][google.cloud.aiplatform.v1.DeployedModel.explanation_spec] 229 // of the DeployedModel. Can be used for explaining prediction results with 230 // different configurations, such as: 231 // - Explaining top-5 predictions results as opposed to top-1; 232 // - Increasing path count or step count of the attribution methods to reduce 233 // approximate errors; 234 // - Using different baselines for explaining the prediction results. 235 ExplanationSpecOverride explanation_spec_override = 5; 236 237 // If specified, this ExplainRequest will be served by the chosen 238 // DeployedModel, overriding 239 // [Endpoint.traffic_split][google.cloud.aiplatform.v1.Endpoint.traffic_split]. 240 string deployed_model_id = 3; 241} 242 243// Response message for 244// [PredictionService.Explain][google.cloud.aiplatform.v1.PredictionService.Explain]. 245message ExplainResponse { 246 // The explanations of the Model's 247 // [PredictResponse.predictions][google.cloud.aiplatform.v1.PredictResponse.predictions]. 248 // 249 // It has the same number of elements as 250 // [instances][google.cloud.aiplatform.v1.ExplainRequest.instances] to be 251 // explained. 252 repeated Explanation explanations = 1; 253 254 // ID of the Endpoint's DeployedModel that served this explanation. 255 string deployed_model_id = 2; 256 257 // The predictions that are the output of the predictions call. 258 // Same as 259 // [PredictResponse.predictions][google.cloud.aiplatform.v1.PredictResponse.predictions]. 260 repeated google.protobuf.Value predictions = 3; 261} 262