model_service.proto 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392
  1. // Copyright 2017 Google Inc.
  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. syntax = "proto3";
  15. package google.cloud.ml.v1;
  16. import "google/api/annotations.proto";
  17. import "google/api/auth.proto";
  18. import "google/longrunning/operations.proto";
  19. import "google/protobuf/timestamp.proto";
  20. option go_package = "google.golang.org/genproto/googleapis/cloud/ml/v1;ml";
  21. option java_multiple_files = true;
  22. option java_outer_classname = "ModelServiceProto";
  23. option java_package = "com.google.cloud.ml.api.v1";
  24. // Copyright 2017 Google Inc. All Rights Reserved.
  25. //
  26. // Proto file for the Google Cloud Machine Learning Engine.
  27. // Describes the 'models service' to work with the 'model' and 'version'
  28. // resources.
  29. // Provides methods that create and manage machine learning models and their
  30. // versions.
  31. //
  32. // A model in this context is a container for versions. The model can't provide
  33. // predictions without first having a version created for it.
  34. //
  35. // Each version is a trained machine learning model, and each is assumed to be
  36. // an iteration of the same machine learning problem as the other versions of
  37. // the same model.
  38. //
  39. // Your project can define multiple models, each with multiple versions.
  40. //
  41. // The basic life cycle of a model is:
  42. //
  43. // * Create and train the machine learning model and save it to a
  44. // Google Cloud Storage location.
  45. // * Use
  46. // [projects.models.create](/ml/reference/rest/v1/projects.models/create)
  47. // to make a new model in your project.
  48. // * Use
  49. // [projects.models.versions.create](/ml/reference/rest/v1/projects.models.versions/create)
  50. // to deploy your saved model.
  51. // * Use [projects.predict](/ml/reference/rest/v1/projects/predict to
  52. // request predictions of a version of your model, or use
  53. // [projects.jobs.create](/ml/reference/rest/v1/projects.jobs/create)
  54. // to start a batch prediction job.
  55. service ModelService {
  56. // Creates a model which will later contain one or more versions.
  57. //
  58. // You must add at least one version before you can request predictions from
  59. // the model. Add versions by calling
  60. // [projects.models.versions.create](/ml/reference/rest/v1/projects.models.versions/create).
  61. rpc CreateModel(CreateModelRequest) returns (Model) {
  62. option (google.api.http) = {
  63. post: "/v1/{parent=projects/*}/models"
  64. body: "model"
  65. };
  66. }
  67. // Lists the models in a project.
  68. //
  69. // Each project can contain multiple models, and each model can have multiple
  70. // versions.
  71. rpc ListModels(ListModelsRequest) returns (ListModelsResponse) {
  72. option (google.api.http) = {
  73. get: "/v1/{parent=projects/*}/models"
  74. };
  75. }
  76. // Gets information about a model, including its name, the description (if
  77. // set), and the default version (if at least one version of the model has
  78. // been deployed).
  79. rpc GetModel(GetModelRequest) returns (Model) {
  80. option (google.api.http) = {
  81. get: "/v1/{name=projects/*/models/*}"
  82. };
  83. }
  84. // Deletes a model.
  85. //
  86. // You can only delete a model if there are no versions in it. You can delete
  87. // versions by calling
  88. // [projects.models.versions.delete](/ml/reference/rest/v1/projects.models.versions/delete).
  89. rpc DeleteModel(DeleteModelRequest) returns (google.longrunning.Operation) {
  90. option (google.api.http) = {
  91. delete: "/v1/{name=projects/*/models/*}"
  92. };
  93. }
  94. // Creates a new version of a model from a trained TensorFlow model.
  95. //
  96. // If the version created in the cloud by this call is the first deployed
  97. // version of the specified model, it will be made the default version of the
  98. // model. When you add a version to a model that already has one or more
  99. // versions, the default version does not automatically change. If you want a
  100. // new version to be the default, you must call
  101. // [projects.models.versions.setDefault](/ml/reference/rest/v1/projects.models.versions/setDefault).
  102. rpc CreateVersion(CreateVersionRequest)
  103. returns (google.longrunning.Operation) {
  104. option (google.api.http) = {
  105. post: "/v1/{parent=projects/*/models/*}/versions"
  106. body: "version"
  107. };
  108. }
  109. // Gets basic information about all the versions of a model.
  110. //
  111. // If you expect that a model has a lot of versions, or if you need to handle
  112. // only a limited number of results at a time, you can request that the list
  113. // be retrieved in batches (called pages):
  114. rpc ListVersions(ListVersionsRequest) returns (ListVersionsResponse) {
  115. option (google.api.http) = {
  116. get: "/v1/{parent=projects/*/models/*}/versions"
  117. };
  118. }
  119. // Gets information about a model version.
  120. //
  121. // Models can have multiple versions. You can call
  122. // [projects.models.versions.list](/ml/reference/rest/v1/projects.models.versions/list)
  123. // to get the same information that this method returns for all of the
  124. // versions of a model.
  125. rpc GetVersion(GetVersionRequest) returns (Version) {
  126. option (google.api.http) = {
  127. get: "/v1/{name=projects/*/models/*/versions/*}"
  128. };
  129. }
  130. // Deletes a model version.
  131. //
  132. // Each model can have multiple versions deployed and in use at any given
  133. // time. Use this method to remove a single version.
  134. //
  135. // Note: You cannot delete the version that is set as the default version
  136. // of the model unless it is the only remaining version.
  137. rpc DeleteVersion(DeleteVersionRequest)
  138. returns (google.longrunning.Operation) {
  139. option (google.api.http) = {
  140. delete: "/v1/{name=projects/*/models/*/versions/*}"
  141. };
  142. }
  143. // Designates a version to be the default for the model.
  144. //
  145. // The default version is used for prediction requests made against the model
  146. // that don't specify a version.
  147. //
  148. // The first version to be created for a model is automatically set as the
  149. // default. You must make any subsequent changes to the default version
  150. // setting manually using this method.
  151. rpc SetDefaultVersion(SetDefaultVersionRequest) returns (Version) {
  152. option (google.api.http) = {
  153. post: "/v1/{name=projects/*/models/*/versions/*}:setDefault"
  154. body: "*"
  155. };
  156. }
  157. }
  158. // Represents a machine learning solution.
  159. //
  160. // A model can have multiple versions, each of which is a deployed, trained
  161. // model ready to receive prediction requests. The model itself is just a
  162. // container.
  163. message Model {
  164. // Required. The name specified for the model when it was created.
  165. //
  166. // The model name must be unique within the project it is created in.
  167. string name = 1;
  168. // Optional. The description specified for the model when it was created.
  169. string description = 2;
  170. // Output only. The default version of the model. This version will be used to
  171. // handle prediction requests that do not specify a version.
  172. //
  173. // You can change the default version by calling
  174. // [projects.methods.versions.setDefault](/ml/reference/rest/v1/projects.models.versions/setDefault).
  175. Version default_version = 3;
  176. // Optional. The list of regions where the model is going to be deployed.
  177. // Currently only one region per model is supported.
  178. // Defaults to 'us-central1' if nothing is set.
  179. repeated string regions = 4;
  180. // Optional. If true, enables StackDriver Logging for online prediction.
  181. // Default is false.
  182. bool online_prediction_logging = 5;
  183. }
  184. // Represents a version of the model.
  185. //
  186. // Each version is a trained model deployed in the cloud, ready to handle
  187. // prediction requests. A model can have multiple versions. You can get
  188. // information about all of the versions of a given model by calling
  189. // [projects.models.versions.list](/ml/reference/rest/v1/projects.models.versions/list).
  190. message Version {
  191. // Required.The name specified for the version when it was created.
  192. //
  193. // The version name must be unique within the model it is created in.
  194. string name = 1;
  195. // Optional. The description specified for the version when it was created.
  196. string description = 2;
  197. // Output only. If true, this version will be used to handle prediction
  198. // requests that do not specify a version.
  199. //
  200. // You can change the default version by calling
  201. // [projects.methods.versions.setDefault](/ml/reference/rest/v1/projects.models.versions/setDefault).
  202. bool is_default = 3;
  203. // Required. The Google Cloud Storage location of the trained model used to
  204. // create the version. See the
  205. // [overview of model deployment](/ml/docs/concepts/deployment-overview) for
  206. // more informaiton.
  207. //
  208. // When passing Version to
  209. // [projects.models.versions.create](/ml/reference/rest/v1/projects.models.versions/create)
  210. // the model service uses the specified location as the source of the model.
  211. // Once deployed, the model version is hosted by the prediction service, so
  212. // this location is useful only as a historical record.
  213. string deployment_uri = 4;
  214. // Output only. The time the version was created.
  215. google.protobuf.Timestamp create_time = 5;
  216. // Output only. The time the version was last used for prediction.
  217. google.protobuf.Timestamp last_use_time = 6;
  218. // Optional. The Google Cloud ML runtime version to use for this deployment.
  219. // If not set, Google Cloud ML will choose a version.
  220. string runtime_version = 8;
  221. // Optional. Manually select the number of nodes to use for serving the
  222. // model. If unset (i.e., by default), the number of nodes used to serve
  223. // the model automatically scales with traffic. However, care should be
  224. // taken to ramp up traffic according to the model's ability to scale. If
  225. // your model needs to handle bursts of traffic beyond it's ability to
  226. // scale, it is recommended you set this field appropriately.
  227. ManualScaling manual_scaling = 9;
  228. }
  229. // Options for manually scaling a model.
  230. message ManualScaling {
  231. // The number of nodes to allocate for this model. These nodes are always up,
  232. // starting from the time the model is deployed, so the cost of operating
  233. // this model will be proportional to nodes * number of hours since
  234. // deployment.
  235. int32 nodes = 1;
  236. }
  237. // Request message for the CreateModel method.
  238. message CreateModelRequest {
  239. // Required. The project name.
  240. //
  241. // Authorization: requires `Editor` role on the specified project.
  242. string parent = 1;
  243. // Required. The model to create.
  244. Model model = 2;
  245. }
  246. // Request message for the ListModels method.
  247. message ListModelsRequest {
  248. // Required. The name of the project whose models are to be listed.
  249. //
  250. // Authorization: requires `Viewer` role on the specified project.
  251. string parent = 1;
  252. // Optional. A page token to request the next page of results.
  253. //
  254. // You get the token from the `next_page_token` field of the response from
  255. // the previous call.
  256. string page_token = 4;
  257. // Optional. The number of models to retrieve per "page" of results. If there
  258. // are more remaining results than this number, the response message will
  259. // contain a valid value in the `next_page_token` field.
  260. //
  261. // The default value is 20, and the maximum page size is 100.
  262. int32 page_size = 5;
  263. }
  264. // Response message for the ListModels method.
  265. message ListModelsResponse {
  266. // The list of models.
  267. repeated Model models = 1;
  268. // Optional. Pass this token as the `page_token` field of the request for a
  269. // subsequent call.
  270. string next_page_token = 2;
  271. }
  272. // Request message for the GetModel method.
  273. message GetModelRequest {
  274. // Required. The name of the model.
  275. //
  276. // Authorization: requires `Viewer` role on the parent project.
  277. string name = 1;
  278. }
  279. // Request message for the DeleteModel method.
  280. message DeleteModelRequest {
  281. // Required. The name of the model.
  282. //
  283. // Authorization: requires `Editor` role on the parent project.
  284. string name = 1;
  285. }
  286. // Uploads the provided trained model version to Cloud Machine Learning.
  287. message CreateVersionRequest {
  288. // Required. The name of the model.
  289. //
  290. // Authorization: requires `Editor` role on the parent project.
  291. string parent = 1;
  292. // Required. The version details.
  293. Version version = 2;
  294. }
  295. // Request message for the ListVersions method.
  296. message ListVersionsRequest {
  297. // Required. The name of the model for which to list the version.
  298. //
  299. // Authorization: requires `Viewer` role on the parent project.
  300. string parent = 1;
  301. // Optional. A page token to request the next page of results.
  302. //
  303. // You get the token from the `next_page_token` field of the response from
  304. // the previous call.
  305. string page_token = 4;
  306. // Optional. The number of versions to retrieve per "page" of results. If
  307. // there are more remaining results than this number, the response message
  308. // will contain a valid value in the `next_page_token` field.
  309. //
  310. // The default value is 20, and the maximum page size is 100.
  311. int32 page_size = 5;
  312. }
  313. // Response message for the ListVersions method.
  314. message ListVersionsResponse {
  315. // The list of versions.
  316. repeated Version versions = 1;
  317. // Optional. Pass this token as the `page_token` field of the request for a
  318. // subsequent call.
  319. string next_page_token = 2;
  320. }
  321. // Request message for the GetVersion method.
  322. message GetVersionRequest {
  323. // Required. The name of the version.
  324. //
  325. // Authorization: requires `Viewer` role on the parent project.
  326. string name = 1;
  327. }
  328. // Request message for the DeleteVerionRequest method.
  329. message DeleteVersionRequest {
  330. // Required. The name of the version. You can get the names of all the
  331. // versions of a model by calling
  332. // [projects.models.versions.list](/ml/reference/rest/v1/projects.models.versions/list).
  333. //
  334. // Authorization: requires `Editor` role on the parent project.
  335. string name = 1;
  336. }
  337. // Request message for the SetDefaultVersion request.
  338. message SetDefaultVersionRequest {
  339. // Required. The name of the version to make the default for the model. You
  340. // can get the names of all the versions of a model by calling
  341. // [projects.models.versions.list](/ml/reference/rest/v1/projects.models.versions/list).
  342. //
  343. // Authorization: requires `Editor` role on the parent project.
  344. string name = 1;
  345. }