1 // Copyright 2017 Google Inc.
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
7 // http://www.apache.org/licenses/LICENSE-2.0
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.
17 package google.cloud.ml.v1;
19 import "google/api/annotations.proto";
20 import "google/api/auth.proto";
21 import "google/longrunning/operations.proto";
22 import "google/protobuf/timestamp.proto";
24 option go_package = "google.golang.org/genproto/googleapis/cloud/ml/v1;ml";
25 option java_multiple_files = true;
26 option java_outer_classname = "ModelServiceProto";
27 option java_package = "com.google.cloud.ml.api.v1";
29 // Copyright 2017 Google Inc. All Rights Reserved.
31 // Proto file for the Google Cloud Machine Learning Engine.
32 // Describes the 'models service' to work with the 'model' and 'version'
35 // Provides methods that create and manage machine learning models and their
38 // A model in this context is a container for versions. The model can't provide
39 // predictions without first having a version created for it.
41 // Each version is a trained machine learning model, and each is assumed to be
42 // an iteration of the same machine learning problem as the other versions of
45 // Your project can define multiple models, each with multiple versions.
47 // The basic life cycle of a model is:
49 // * Create and train the machine learning model and save it to a
50 // Google Cloud Storage location.
52 // [projects.models.create](/ml/reference/rest/v1/projects.models/create)
53 // to make a new model in your project.
55 // [projects.models.versions.create](/ml/reference/rest/v1/projects.models.versions/create)
56 // to deploy your saved model.
57 // * Use [projects.predict](/ml/reference/rest/v1/projects/predict to
58 // request predictions of a version of your model, or use
59 // [projects.jobs.create](/ml/reference/rest/v1/projects.jobs/create)
60 // to start a batch prediction job.
61 service ModelService {
62 // Creates a model which will later contain one or more versions.
64 // You must add at least one version before you can request predictions from
65 // the model. Add versions by calling
66 // [projects.models.versions.create](/ml/reference/rest/v1/projects.models.versions/create).
67 rpc CreateModel(CreateModelRequest) returns (Model) {
68 option (google.api.http) = {
69 post: "/v1/{parent=projects/*}/models"
74 // Lists the models in a project.
76 // Each project can contain multiple models, and each model can have multiple
78 rpc ListModels(ListModelsRequest) returns (ListModelsResponse) {
79 option (google.api.http) = {
80 get: "/v1/{parent=projects/*}/models"
84 // Gets information about a model, including its name, the description (if
85 // set), and the default version (if at least one version of the model has
87 rpc GetModel(GetModelRequest) returns (Model) {
88 option (google.api.http) = {
89 get: "/v1/{name=projects/*/models/*}"
95 // You can only delete a model if there are no versions in it. You can delete
96 // versions by calling
97 // [projects.models.versions.delete](/ml/reference/rest/v1/projects.models.versions/delete).
98 rpc DeleteModel(DeleteModelRequest) returns (google.longrunning.Operation) {
99 option (google.api.http) = {
100 delete: "/v1/{name=projects/*/models/*}"
104 // Creates a new version of a model from a trained TensorFlow model.
106 // If the version created in the cloud by this call is the first deployed
107 // version of the specified model, it will be made the default version of the
108 // model. When you add a version to a model that already has one or more
109 // versions, the default version does not automatically change. If you want a
110 // new version to be the default, you must call
111 // [projects.models.versions.setDefault](/ml/reference/rest/v1/projects.models.versions/setDefault).
112 rpc CreateVersion(CreateVersionRequest)
113 returns (google.longrunning.Operation) {
114 option (google.api.http) = {
115 post: "/v1/{parent=projects/*/models/*}/versions"
120 // Gets basic information about all the versions of a model.
122 // If you expect that a model has a lot of versions, or if you need to handle
123 // only a limited number of results at a time, you can request that the list
124 // be retrieved in batches (called pages):
125 rpc ListVersions(ListVersionsRequest) returns (ListVersionsResponse) {
126 option (google.api.http) = {
127 get: "/v1/{parent=projects/*/models/*}/versions"
131 // Gets information about a model version.
133 // Models can have multiple versions. You can call
134 // [projects.models.versions.list](/ml/reference/rest/v1/projects.models.versions/list)
135 // to get the same information that this method returns for all of the
136 // versions of a model.
137 rpc GetVersion(GetVersionRequest) returns (Version) {
138 option (google.api.http) = {
139 get: "/v1/{name=projects/*/models/*/versions/*}"
143 // Deletes a model version.
145 // Each model can have multiple versions deployed and in use at any given
146 // time. Use this method to remove a single version.
148 // Note: You cannot delete the version that is set as the default version
149 // of the model unless it is the only remaining version.
150 rpc DeleteVersion(DeleteVersionRequest)
151 returns (google.longrunning.Operation) {
152 option (google.api.http) = {
153 delete: "/v1/{name=projects/*/models/*/versions/*}"
157 // Designates a version to be the default for the model.
159 // The default version is used for prediction requests made against the model
160 // that don't specify a version.
162 // The first version to be created for a model is automatically set as the
163 // default. You must make any subsequent changes to the default version
164 // setting manually using this method.
165 rpc SetDefaultVersion(SetDefaultVersionRequest) returns (Version) {
166 option (google.api.http) = {
167 post: "/v1/{name=projects/*/models/*/versions/*}:setDefault"
173 // Represents a machine learning solution.
175 // A model can have multiple versions, each of which is a deployed, trained
176 // model ready to receive prediction requests. The model itself is just a
179 // Required. The name specified for the model when it was created.
181 // The model name must be unique within the project it is created in.
184 // Optional. The description specified for the model when it was created.
185 string description = 2;
187 // Output only. The default version of the model. This version will be used to
188 // handle prediction requests that do not specify a version.
190 // You can change the default version by calling
191 // [projects.methods.versions.setDefault](/ml/reference/rest/v1/projects.models.versions/setDefault).
192 Version default_version = 3;
194 // Optional. The list of regions where the model is going to be deployed.
195 // Currently only one region per model is supported.
196 // Defaults to 'us-central1' if nothing is set.
197 repeated string regions = 4;
199 // Optional. If true, enables StackDriver Logging for online prediction.
201 bool online_prediction_logging = 5;
204 // Represents a version of the model.
206 // Each version is a trained model deployed in the cloud, ready to handle
207 // prediction requests. A model can have multiple versions. You can get
208 // information about all of the versions of a given model by calling
209 // [projects.models.versions.list](/ml/reference/rest/v1/projects.models.versions/list).
211 // Required.The name specified for the version when it was created.
213 // The version name must be unique within the model it is created in.
216 // Optional. The description specified for the version when it was created.
217 string description = 2;
219 // Output only. If true, this version will be used to handle prediction
220 // requests that do not specify a version.
222 // You can change the default version by calling
223 // [projects.methods.versions.setDefault](/ml/reference/rest/v1/projects.models.versions/setDefault).
226 // Required. The Google Cloud Storage location of the trained model used to
227 // create the version. See the
228 // [overview of model deployment](/ml/docs/concepts/deployment-overview) for
231 // When passing Version to
232 // [projects.models.versions.create](/ml/reference/rest/v1/projects.models.versions/create)
233 // the model service uses the specified location as the source of the model.
234 // Once deployed, the model version is hosted by the prediction service, so
235 // this location is useful only as a historical record.
236 string deployment_uri = 4;
238 // Output only. The time the version was created.
239 google.protobuf.Timestamp create_time = 5;
241 // Output only. The time the version was last used for prediction.
242 google.protobuf.Timestamp last_use_time = 6;
244 // Optional. The Google Cloud ML runtime version to use for this deployment.
245 // If not set, Google Cloud ML will choose a version.
246 string runtime_version = 8;
248 // Optional. Manually select the number of nodes to use for serving the
249 // model. If unset (i.e., by default), the number of nodes used to serve
250 // the model automatically scales with traffic. However, care should be
251 // taken to ramp up traffic according to the model's ability to scale. If
252 // your model needs to handle bursts of traffic beyond it's ability to
253 // scale, it is recommended you set this field appropriately.
254 ManualScaling manual_scaling = 9;
257 // Options for manually scaling a model.
258 message ManualScaling {
259 // The number of nodes to allocate for this model. These nodes are always up,
260 // starting from the time the model is deployed, so the cost of operating
261 // this model will be proportional to nodes * number of hours since
266 // Request message for the CreateModel method.
267 message CreateModelRequest {
268 // Required. The project name.
270 // Authorization: requires `Editor` role on the specified project.
273 // Required. The model to create.
277 // Request message for the ListModels method.
278 message ListModelsRequest {
279 // Required. The name of the project whose models are to be listed.
281 // Authorization: requires `Viewer` role on the specified project.
284 // Optional. A page token to request the next page of results.
286 // You get the token from the `next_page_token` field of the response from
287 // the previous call.
288 string page_token = 4;
290 // Optional. The number of models to retrieve per "page" of results. If there
291 // are more remaining results than this number, the response message will
292 // contain a valid value in the `next_page_token` field.
294 // The default value is 20, and the maximum page size is 100.
298 // Response message for the ListModels method.
299 message ListModelsResponse {
300 // The list of models.
301 repeated Model models = 1;
303 // Optional. Pass this token as the `page_token` field of the request for a
305 string next_page_token = 2;
308 // Request message for the GetModel method.
309 message GetModelRequest {
310 // Required. The name of the model.
312 // Authorization: requires `Viewer` role on the parent project.
316 // Request message for the DeleteModel method.
317 message DeleteModelRequest {
318 // Required. The name of the model.
320 // Authorization: requires `Editor` role on the parent project.
324 // Uploads the provided trained model version to Cloud Machine Learning.
325 message CreateVersionRequest {
326 // Required. The name of the model.
328 // Authorization: requires `Editor` role on the parent project.
331 // Required. The version details.
335 // Request message for the ListVersions method.
336 message ListVersionsRequest {
337 // Required. The name of the model for which to list the version.
339 // Authorization: requires `Viewer` role on the parent project.
342 // Optional. A page token to request the next page of results.
344 // You get the token from the `next_page_token` field of the response from
345 // the previous call.
346 string page_token = 4;
348 // Optional. The number of versions to retrieve per "page" of results. If
349 // there are more remaining results than this number, the response message
350 // will contain a valid value in the `next_page_token` field.
352 // The default value is 20, and the maximum page size is 100.
356 // Response message for the ListVersions method.
357 message ListVersionsResponse {
358 // The list of versions.
359 repeated Version versions = 1;
361 // Optional. Pass this token as the `page_token` field of the request for a
363 string next_page_token = 2;
366 // Request message for the GetVersion method.
367 message GetVersionRequest {
368 // Required. The name of the version.
370 // Authorization: requires `Viewer` role on the parent project.
374 // Request message for the DeleteVerionRequest method.
375 message DeleteVersionRequest {
376 // Required. The name of the version. You can get the names of all the
377 // versions of a model by calling
378 // [projects.models.versions.list](/ml/reference/rest/v1/projects.models.versions/list).
380 // Authorization: requires `Editor` role on the parent project.
384 // Request message for the SetDefaultVersion request.
385 message SetDefaultVersionRequest {
386 // Required. The name of the version to make the default for the model. You
387 // can get the names of all the versions of a model by calling
388 // [projects.models.versions.list](/ml/reference/rest/v1/projects.models.versions/list).
390 // Authorization: requires `Editor` role on the parent project.