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