diff --git a/google/cloud/ml/v1/job_service.proto b/google/cloud/ml/v1/job_service.proto new file mode 100644 index 00000000..93beed1c --- /dev/null +++ b/google/cloud/ml/v1/job_service.proto @@ -0,0 +1,605 @@ +// Copyright 2017 Google Inc. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +package google.cloud.ml.v1; + +import "google/api/annotations.proto"; +import "google/api/auth.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/ml/v1;ml"; +option java_multiple_files = true; +option java_outer_classname = "JobServiceProto"; +option java_package = "com.google.cloud.ml.api.v1"; + +// Copyright 2017 Google Inc. All Rights Reserved. +// +// Proto file for the Google Cloud Machine Learning Engine. +// Describes the 'job service' to manage training and prediction jobs. + + + +// Service to create and manage training and batch prediction jobs. +service JobService { + // Creates a training or a batch prediction job. + rpc CreateJob(CreateJobRequest) returns (Job) { + option (google.api.http) = { post: "/v1/{parent=projects/*}/jobs" body: "job" }; + } + + // Lists the jobs in the project. + rpc ListJobs(ListJobsRequest) returns (ListJobsResponse) { + option (google.api.http) = { get: "/v1/{parent=projects/*}/jobs" }; + } + + // Describes a job. + rpc GetJob(GetJobRequest) returns (Job) { + option (google.api.http) = { get: "/v1/{name=projects/*/jobs/*}" }; + } + + // Cancels a running job. + rpc CancelJob(CancelJobRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { post: "/v1/{name=projects/*/jobs/*}:cancel" body: "*" }; + } +} + +// Represents input parameters for a training job. +message TrainingInput { + // A scale tier is an abstract representation of the resources Cloud ML + // will allocate to a training job. When selecting a scale tier for your + // training job, you should consider the size of your training dataset and + // the complexity of your model. As the tiers increase, virtual machines are + // added to handle your job, and the individual machines in the cluster + // generally have more memory and greater processing power than they do at + // lower tiers. The number of training units charged per hour of processing + // increases as tiers get more advanced. Refer to the + // [pricing guide](/ml/pricing) for more details. Note that in addition to + // incurring costs, your use of training resources is constrained by the + // [quota policy](/ml/quota). + enum ScaleTier { + // A single worker instance. This tier is suitable for learning how to use + // Cloud ML, and for experimenting with new models using small datasets. + BASIC = 0; + + // Many workers and a few parameter servers. + STANDARD_1 = 1; + + // A large number of workers with many parameter servers. + PREMIUM_1 = 3; + + // A single worker instance [with a GPU](ml/docs/how-tos/using-gpus). + BASIC_GPU = 6; + + // The CUSTOM tier is not a set tier, but rather enables you to use your + // own cluster specification. When you use this tier, set values to + // configure your processing cluster according to these guidelines: + // + // * You _must_ set `TrainingInput.masterType` to specify the type + // of machine to use for your master node. This is the only required + // setting. + // + // * You _may_ set `TrainingInput.workerCount` to specify the number of + // workers to use. If you specify one or more workers, you _must_ also + // set `TrainingInput.workerType` to specify the type of machine to use + // for your worker nodes. + // + // * You _may_ set `TrainingInput.parameterServerCount` to specify the + // number of parameter servers to use. If you specify one or more + // parameter servers, you _must_ also set + // `TrainingInput.parameterServerType` to specify the type of machine to + // use for your parameter servers. + // + // Note that all of your workers must use the same machine type, which can + // be different from your parameter server type and master type. Your + // parameter servers must likewise use the same machine type, which can be + // different from your worker type and master type. + CUSTOM = 5; + } + + // Required. Specifies the machine types, the number of replicas for workers + // and parameter servers. + ScaleTier scale_tier = 1; + + // Optional. Specifies the type of virtual machine to use for your training + // job's master worker. + // + // The following types are supported: + // + //
complex_model_s.
+ // complex_model_m.
+ // standard that
+ // also includes a
+ //
+ // GPU that you can use in your trainer.
+ // coplex_model_m that also includes
+ // four GPUs.
+ //
+// {"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}
+//
+// Plain text:
+//
+// {"instances": ["the quick brown fox", "la bruja le dio"]}
+//
+// Sentences encoded as lists of words (vectors of strings):
+//
+// {
+// "instances": [
+// ["the","quick","brown"],
+// ["la","bruja","le"],
+// ...
+// ]
+// }
+//
+// Floating point scalar values:
+//
+// {"instances": [0.0, 1.1, 2.2]}
+//
+// Vectors of integers:
+//
+// {
+// "instances": [
+// [0, 1, 2],
+// [3, 4, 5],
+// ...
+// ]
+// }
+//
+// Tensors (in this case, two-dimensional tensors):
+//
+// {
+// "instances": [
+// [
+// [0, 1, 2],
+// [3, 4, 5]
+// ],
+// ...
+// ]
+// }
+//
+// Images can be represented different ways. In this encoding scheme the first
+// two dimensions represent the rows and columns of the image, and the third
+// contains lists (vectors) of the R, G, and B values for each pixel.
+//
+// {
+// "instances": [
+// [
+// [
+// [138, 30, 66],
+// [130, 20, 56],
+// ...
+// ],
+// [
+// [126, 38, 61],
+// [122, 24, 57],
+// ...
+// ],
+// ...
+// ],
+// ...
+// ]
+// }
+//
+// JSON strings must be encoded as UTF-8. To send binary data, you must
+// base64-encode the data and mark it as binary. To mark a JSON string
+// as binary, replace it with a JSON object with a single attribute named `b64`:
+// {"b64": "..."}
+// For example:
+//
+// Two Serialized tf.Examples (fake data, for illustrative purposes only):
+//
+// {"instances": [{"b64": "X5ad6u"}, {"b64": "IA9j4nx"}]}
+//
+// Two JPEG image byte strings (fake data, for illustrative purposes only):
+//
+// {"instances": [{"b64": "ASa8asdf"}, {"b64": "JLK7ljk3"}]}
+//
+// If your data includes named references, format each instance as a JSON object
+// with the named references as the keys:
+//
+// JSON input data to be preprocessed:
+//
+// {
+// "instances": [
+// {
+// "a": 1.0,
+// "b": true,
+// "c": "x"
+// },
+// {
+// "a": -2.0,
+// "b": false,
+// "c": "y"
+// }
+// ]
+// }
+//
+// Some models have an underlying TensorFlow graph that accepts multiple input
+// tensors. In this case, you should use the names of JSON name/value pairs to
+// identify the input tensors, as shown in the following exmaples:
+//
+// For a graph with input tensor aliases "tag" (string) and "image"
+// (base64-encoded string):
+//
+// {
+// "instances": [
+// {
+// "tag": "beach",
+// "image": {"b64": "ASa8asdf"}
+// },
+// {
+// "tag": "car",
+// "image": {"b64": "JLK7ljk3"}
+// }
+// ]
+// }
+//
+// For a graph with input tensor aliases "tag" (string) and "image"
+// (3-dimensional array of 8-bit ints):
+//
+// {
+// "instances": [
+// {
+// "tag": "beach",
+// "image": [
+// [
+// [138, 30, 66],
+// [130, 20, 56],
+// ...
+// ],
+// [
+// [126, 38, 61],
+// [122, 24, 57],
+// ...
+// ],
+// ...
+// ]
+// },
+// {
+// "tag": "car",
+// "image": [
+// [
+// [255, 0, 102],
+// [255, 0, 97],
+// ...
+// ],
+// [
+// [254, 1, 101],
+// [254, 2, 93],
+// ...
+// ],
+// ...
+// ]
+// },
+// ...
+// ]
+// }
+//
+// If the call is successful, the response body will contain one prediction
+// entry per instance in the request body. If prediction fails for any
+// instance, the response body will contain no predictions and will contian
+// a single error entry instead.
+message PredictRequest {
+ // Required. The resource name of a model or a version.
+ //
+ // Authorization: requires `Viewer` role on the parent project.
+ string name = 1;
+
+ //
+ // Required. The prediction request body.
+ google.api.HttpBody http_body = 2;
+}
diff --git a/google/cloud/ml/v1/project_service.proto b/google/cloud/ml/v1/project_service.proto
new file mode 100644
index 00000000..f54eadf6
--- /dev/null
+++ b/google/cloud/ml/v1/project_service.proto
@@ -0,0 +1,59 @@
+// Copyright 2017 Google Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.cloud.ml.v1;
+
+import "google/api/annotations.proto";
+
+option go_package = "google.golang.org/genproto/googleapis/cloud/ml/v1;ml";
+option java_multiple_files = true;
+option java_outer_classname = "ProjectServiceProto";
+option java_package = "com.google.cloud.ml.api.v1";
+
+// Copyright 2017 Google Inc. All Rights Reserved.
+//
+// Proto file for the Google Cloud Machine Learning Engine.
+// Describes the project management service.
+
+
+
+// Allows retrieving project related information.
+service ProjectManagementService {
+ // Get the service account information associated with your project. You need
+ // this information in order to grant the service account persmissions for
+ // the Google Cloud Storage location where you put your model training code
+ // for training the model with Google Cloud Machine Learning.
+ rpc GetConfig(GetConfigRequest) returns (GetConfigResponse) {
+ option (google.api.http) = { get: "/v1/{name=projects/*}:getConfig" };
+ }
+}
+
+// Requests service account information associated with a project.
+message GetConfigRequest {
+ // Required. The project name.
+ //
+ // Authorization: requires `Viewer` role on the specified project.
+ string name = 1;
+}
+
+// Returns service account information associated with a project.
+message GetConfigResponse {
+ // The service account Cloud ML uses to access resources in the project.
+ string service_account = 1;
+
+ // The project number for `service_account`.
+ int64 service_account_project = 2;
+}
diff --git a/google/cloud/ml/v1beta1/job_service.proto b/google/cloud/ml/v1beta1/job_service.proto
index e6717fcf..1ac71e17 100644
--- a/google/cloud/ml/v1beta1/job_service.proto
+++ b/google/cloud/ml/v1beta1/job_service.proto
@@ -1,4 +1,4 @@
-// Copyright 2016 Google Inc.
+// Copyright 2017 Google Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
@@ -17,6 +17,7 @@ syntax = "proto3";
package google.cloud.ml.v1beta1;
import "google/api/annotations.proto";
+import "google/api/auth.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";
@@ -27,7 +28,7 @@ option java_package = "com.google.cloud.ml.api.v1beta1";
// Copyright 2016 Google Inc. All Rights Reserved.
//
-// Proto file for the Machine Learning Service
+// Proto file for the Google Cloud Machine Learning Engine.
// Describes the 'job service' to manage training and prediction jobs.
@@ -65,7 +66,9 @@ message TrainingInput {
// generally have more memory and greater processing power than they do at
// lower tiers. The number of training units charged per hour of processing
// increases as tiers get more advanced. Refer to the
- // [pricing guide](/ml/pricing) for more details.
+ // [pricing guide](/ml/pricing) for more details. Note that in addition to
+ // incurring costs, your use of training resources is constrained by the
+ // [quota policy](/ml/quota).
enum ScaleTier {
// A single worker instance. This tier is suitable for learning how to use
// Cloud ML, and for experimenting with new models using small datasets.
@@ -77,12 +80,32 @@ message TrainingInput {
// A large number of workers with many parameter servers.
PREMIUM_1 = 3;
+ // A single worker instance [with a GPU](ml/docs/how-tos/using-gpus).
+ BASIC_GPU = 6;
+
// The CUSTOM tier is not a set tier, but rather enables you to use your
- // own cluster specification. When you use this tier, you must also set
- // valid values for `worker_count` and `parameter_server_count`, and you can
- // specify the type of virtual machines to use for the different types of
- // workers by setting `master_type`, `worker_type`, and
- // `parameter_server_type`.
+ // own cluster specification. When you use this tier, set values to
+ // configure your processing cluster according to these guidelines:
+ //
+ // * You _must_ set `TrainingInput.masterType` to specify the type
+ // of machine to use for your master node. This is the only required
+ // setting.
+ //
+ // * You _may_ set `TrainingInput.workerCount` to specify the number of
+ // workers to use. If you specify one or more workers, you _must_ also
+ // set `TrainingInput.workerType` to specify the type of machine to use
+ // for your worker nodes.
+ //
+ // * You _may_ set `TrainingInput.parameterServerCount` to specify the
+ // number of parameter servers to use. If you specify one or more
+ // parameter servers, you _must_ also set
+ // `TrainingInput.parameterServerType` to specify the type of machine to
+ // use for your parameter servers.
+ //
+ // Note that all of your workers must use the same machine type, which can
+ // be different from your parameter server type and master type. Your
+ // parameter servers must likewise use the same machine type, which can be
+ // different from your worker type and master type.
CUSTOM = 5;
}
@@ -116,26 +139,39 @@ message TrainingInput {
// complex_model_s.
// complex_model_m.
+ // standard that
+ // also includes a
+ //
+ // GPU that you can use in your trainer.
+ // coplex_model_m that also includes
+ // four GPUs.
//
- // {"predictions": [5, 4, 3]}
- //
- // A more complex set of predictions, each containing two named values that
- // correspond to output tensors, named **label** and **scores** respectively.
- // The value of **label** is the predicted category ("car" or "beach") and
- // **scores** contains a list of probabilities for that instance across the
- // possible categories.
- //
- // {"predictions": [{"label": "beach", "scores": [0.1, 0.9]},
- // {"label": "car", "scores": [0.75, 0.25]}]}
- //
- // A response when there is an error processing an input instance:
- //
- // {"error": "Divide by zero"}
- //
+ // **** REMOVE FROM GENERATED DOCUMENTATION
rpc Predict(PredictRequest) returns (google.api.HttpBody) {
option (google.api.http) = { post: "/v1beta1/{name=projects/**}:predict" body: "*" };
}
@@ -100,7 +57,7 @@ service OnlinePredictionService {
// model's input definition. Instances can include named inputs or can contain
// only unlabeled values.
//
-// Most data does not include named inputs. Some instances will be simple
+// Not all data includes named inputs. Some instances will be simple
// JSON values (boolean, number, or string). However, instances are often lists
// of simple values, or complex nested lists. Here are some examples of request
// bodies:
@@ -115,7 +72,13 @@ service OnlinePredictionService {
//
// Sentences encoded as lists of words (vectors of strings):
//
-// {"instances": [["the","quick","brown"], ["la","bruja","le"]]}
+// {
+// "instances": [
+// ["the","quick","brown"],
+// ["la","bruja","le"],
+// ...
+// ]
+// }
//
// Floating point scalar values:
//
@@ -123,22 +86,53 @@ service OnlinePredictionService {
//
// Vectors of integers:
//
-// {"instances": [[0, 1, 2], [3, 4, 5],...]}
+// {
+// "instances": [
+// [0, 1, 2],
+// [3, 4, 5],
+// ...
+// ]
+// }
//
// Tensors (in this case, two-dimensional tensors):
//
-// {"instances": [[[0, 1, 2], [3, 4, 5]], ...]}
+// {
+// "instances": [
+// [
+// [0, 1, 2],
+// [3, 4, 5]
+// ],
+// ...
+// ]
+// }
//
-// Images represented as a three-dimensional list. In this encoding scheme the
-// first two dimensions represent the rows and columns of the image, and the
-// third contains the R, G, and B values for each pixel.
+// Images can be represented different ways. In this encoding scheme the first
+// two dimensions represent the rows and columns of the image, and the third
+// contains lists (vectors) of the R, G, and B values for each pixel.
//
-// {"instances": [[[[138, 30, 66], [130, 20, 56], ...]]]]}
+// {
+// "instances": [
+// [
+// [
+// [138, 30, 66],
+// [130, 20, 56],
+// ...
+// ],
+// [
+// [126, 38, 61],
+// [122, 24, 57],
+// ...
+// ],
+// ...
+// ],
+// ...
+// ]
+// }
//
-// Data must be encoded as UTF-8. If your data uses another character encoding,
-// you must base64 encode the data and mark it as binary. To mark a JSON string
-// as binary, replace it with an object with a single attribute named `b`:
-// {"b": "..."}
+// JSON strings must be encoded as UTF-8. To send binary data, you must
+// base64-encode the data and mark it as binary. To mark a JSON string
+// as binary, replace it with a JSON object with a single attribute named `b64`:
+// {"b64": "..."}
// For example:
//
// Two Serialized tf.Examples (fake data, for illustrative purposes only):
@@ -154,8 +148,20 @@ service OnlinePredictionService {
//
// JSON input data to be preprocessed:
//
-// {"instances": [{"a": 1.0, "b": true, "c": "x"},
-// {"a": -2.0, "b": false, "c": "y"}]}
+// {
+// "instances": [
+// {
+// "a": 1.0,
+// "b": true,
+// "c": "x"
+// },
+// {
+// "a": -2.0,
+// "b": false,
+// "c": "y"
+// }
+// ]
+// }
//
// Some models have an underlying TensorFlow graph that accepts multiple input
// tensors. In this case, you should use the names of JSON name/value pairs to
@@ -164,14 +170,59 @@ service OnlinePredictionService {
// For a graph with input tensor aliases "tag" (string) and "image"
// (base64-encoded string):
//
-// {"instances": [{"tag": "beach", "image": {"b64": "ASa8asdf"}},
-// {"tag": "car", "image": {"b64": "JLK7ljk3"}}]}
+// {
+// "instances": [
+// {
+// "tag": "beach",
+// "image": {"b64": "ASa8asdf"}
+// },
+// {
+// "tag": "car",
+// "image": {"b64": "JLK7ljk3"}
+// }
+// ]
+// }
//
// For a graph with input tensor aliases "tag" (string) and "image"
// (3-dimensional array of 8-bit ints):
//
-// {"instances": [{"tag": "beach", "image": [[[263, 1, 10], [262, 2, 11], ...]]},
-// {"tag": "car", "image": [[[10, 11, 24], [23, 10, 15], ...]]}]}
+// {
+// "instances": [
+// {
+// "tag": "beach",
+// "image": [
+// [
+// [138, 30, 66],
+// [130, 20, 56],
+// ...
+// ],
+// [
+// [126, 38, 61],
+// [122, 24, 57],
+// ...
+// ],
+// ...
+// ]
+// },
+// {
+// "tag": "car",
+// "image": [
+// [
+// [255, 0, 102],
+// [255, 0, 97],
+// ...
+// ],
+// [
+// [254, 1, 101],
+// [254, 2, 93],
+// ...
+// ],
+// ...
+// ]
+// },
+// ...
+// ]
+// }
//
// If the call is successful, the response body will contain one prediction
// entry per instance in the request body. If prediction fails for any
diff --git a/google/cloud/ml/v1beta1/project_service.proto b/google/cloud/ml/v1beta1/project_service.proto
index fcf5d938..1f8b2d5e 100644
--- a/google/cloud/ml/v1beta1/project_service.proto
+++ b/google/cloud/ml/v1beta1/project_service.proto
@@ -1,4 +1,4 @@
-// Copyright 2016 Google Inc.
+// Copyright 2017 Google Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
@@ -23,6 +23,12 @@ option java_multiple_files = true;
option java_outer_classname = "ProjectServiceProto";
option java_package = "com.google.cloud.ml.api.v1beta1";
+// Copyright 2016 Google Inc. All Rights Reserved.
+//
+// Proto file for the Google Cloud Machine Learning Engine.
+// Describes the project management service.
+
+
// Allows retrieving project related information.
service ProjectManagementService {