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: + // + //
+ //
standard
+ //
+ // A basic machine configuration suitable for training simple models with + // small to moderate datasets. + //
+ //
large_model
+ //
+ // A machine with a lot of memory, specially suited for parameter servers + // when your model is large (having many hidden layers or layers with very + // large numbers of nodes). + //
+ //
complex_model_s
+ //
+ // A machine suitable for the master and workers of the cluster when your + // model requires more computation than the standard machine can handle + // satisfactorily. + //
+ //
complex_model_m
+ //
+ // A machine with roughly twice the number of cores and roughly double the + // memory of complex_model_s. + //
+ //
complex_model_l
+ //
+ // A machine with roughly twice the number of cores and roughly double the + // memory of complex_model_m. + //
+ //
standard_gpu
+ //
+ // A machine equivalent to standard that + // also includes a + // + // GPU that you can use in your trainer. + //
+ //
complex_model_m_gpu
+ //
+ // A machine equivalent to + // coplex_model_m that also includes + // four GPUs. + //
+ //
+ // + // You must set this value when `scaleTier` is set to `CUSTOM`. + string master_type = 2; + + // Optional. Specifies the type of virtual machine to use for your training + // job's worker nodes. + // + // The supported values are the same as those described in the entry for + // `masterType`. + // + // This value must be present when `scaleTier` is set to `CUSTOM` and + // `workerCount` is greater than zero. + string worker_type = 3; + + // Optional. Specifies the type of virtual machine to use for your training + // job's parameter server. + // + // The supported values are the same as those described in the entry for + // `master_type`. + // + // This value must be present when `scaleTier` is set to `CUSTOM` and + // `parameter_server_count` is greater than zero. + string parameter_server_type = 4; + + // Optional. The number of worker replicas to use for the training job. Each + // replica in the cluster will be of the type specified in `worker_type`. + // + // This value can only be used when `scale_tier` is set to `CUSTOM`. If you + // set this value, you must also set `worker_type`. + int64 worker_count = 5; + + // Optional. The number of parameter server replicas to use for the training + // job. Each replica in the cluster will be of the type specified in + // `parameter_server_type`. + // + // This value can only be used when `scale_tier` is set to `CUSTOM`.If you + // set this value, you must also set `parameter_server_type`. + int64 parameter_server_count = 6; + + // Required. The Google Cloud Storage location of the packages with + // the training program and any additional dependencies. + repeated string package_uris = 7; + + // Required. The Python module name to run after installing the packages. + string python_module = 8; + + // Optional. Command line arguments to pass to the program. + repeated string args = 10; + + // Optional. The set of Hyperparameters to tune. + HyperparameterSpec hyperparameters = 12; + + // Required. The Google Compute Engine region to run the training job in. + string region = 14; + + // Optional. A Google Cloud Storage path in which to store training outputs + // and other data needed for training. This path is passed to your TensorFlow + // program as the 'job_dir' command-line argument. The benefit of specifying + // this field is that Cloud ML validates the path for use in training. + string job_dir = 16; + + // Optional. The Google Cloud ML runtime version to use for training. If not + // set, Google Cloud ML will choose the latest stable version. + string runtime_version = 15; +} + +// Represents a set of hyperparameters to optimize. +message HyperparameterSpec { + // The available types of optimization goals. + enum GoalType { + // Goal Type will default to maximize. + GOAL_TYPE_UNSPECIFIED = 0; + + // Maximize the goal metric. + MAXIMIZE = 1; + + // Minimize the goal metric. + MINIMIZE = 2; + } + + // Required. The type of goal to use for tuning. Available types are + // `MAXIMIZE` and `MINIMIZE`. + // + // Defaults to `MAXIMIZE`. + GoalType goal = 1; + + // Required. The set of parameters to tune. + repeated ParameterSpec params = 2; + + // Optional. How many training trials should be attempted to optimize + // the specified hyperparameters. + // + // Defaults to one. + int32 max_trials = 3; + + // Optional. The number of training trials to run concurrently. + // You can reduce the time it takes to perform hyperparameter tuning by adding + // trials in parallel. However, each trail only benefits from the information + // gained in completed trials. That means that a trial does not get access to + // the results of trials running at the same time, which could reduce the + // quality of the overall optimization. + // + // Each trial will use the same scale tier and machine types. + // + // Defaults to one. + int32 max_parallel_trials = 4; + + // Optional. The Tensorflow summary tag name to use for optimizing trials. For + // current versions of Tensorflow, this tag name should exactly match what is + // shown in Tensorboard, including all scopes. For versions of Tensorflow + // prior to 0.12, this should be only the tag passed to tf.Summary. + // By default, "training/hptuning/metric" will be used. + string hyperparameter_metric_tag = 5; +} + +// Represents a single hyperparameter to optimize. +message ParameterSpec { + // The type of the parameter. + enum ParameterType { + // You must specify a valid type. Using this unspecified type will result in + // an error. + PARAMETER_TYPE_UNSPECIFIED = 0; + + // Type for real-valued parameters. + DOUBLE = 1; + + // Type for integral parameters. + INTEGER = 2; + + // The parameter is categorical, with a value chosen from the categories + // field. + CATEGORICAL = 3; + + // The parameter is real valued, with a fixed set of feasible points. If + // `type==DISCRETE`, feasible_points must be provided, and + // {`min_value`, `max_value`} will be ignored. + DISCRETE = 4; + } + + // The type of scaling that should be applied to this parameter. + enum ScaleType { + // By default, no scaling is applied. + NONE = 0; + + // Scales the feasible space to (0, 1) linearly. + UNIT_LINEAR_SCALE = 1; + + // Scales the feasible space logarithmically to (0, 1). The entire feasible + // space must be strictly positive. + UNIT_LOG_SCALE = 2; + + // Scales the feasible space "reverse" logarithmically to (0, 1). The result + // is that values close to the top of the feasible space are spread out more + // than points near the bottom. The entire feasible space must be strictly + // positive. + UNIT_REVERSE_LOG_SCALE = 3; + } + + // Required. The parameter name must be unique amongst all ParameterConfigs in + // a HyperparameterSpec message. E.g., "learning_rate". + string parameter_name = 1; + + // Required. The type of the parameter. + ParameterType type = 4; + + // Required if type is `DOUBLE` or `INTEGER`. This field + // should be unset if type is `CATEGORICAL`. This value should be integers if + // type is INTEGER. + double min_value = 2; + + // Required if typeis `DOUBLE` or `INTEGER`. This field + // should be unset if type is `CATEGORICAL`. This value should be integers if + // type is `INTEGER`. + double max_value = 3; + + // Required if type is `CATEGORICAL`. The list of possible categories. + repeated string categorical_values = 5; + + // Required if type is `DISCRETE`. + // A list of feasible points. + // The list should be in strictly increasing order. For instance, this + // parameter might have possible settings of 1.5, 2.5, and 4.0. This list + // should not contain more than 1,000 values. + repeated double discrete_values = 6; + + // Optional. How the parameter should be scaled to the hypercube. + // Leave unset for categorical parameters. + // Some kind of scaling is strongly recommended for real or integral + // parameters (e.g., `UNIT_LINEAR_SCALE`). + ScaleType scale_type = 7; +} + +// Represents the result of a single hyperparameter tuning trial from a +// training job. The TrainingOutput object that is returned on successful +// completion of a training job with hyperparameter tuning includes a list +// of HyperparameterOutput objects, one for each successful trial. +message HyperparameterOutput { + // An observed value of a metric. + message HyperparameterMetric { + // The global training step for this metric. + int64 training_step = 1; + + // The objective value at this training step. + double objective_value = 2; + } + + // The trial id for these results. + string trial_id = 1; + + // The hyperparameters given to this trial. + map hyperparameters = 2; + + // The final objective metric seen for this trial. + HyperparameterMetric final_metric = 3; + + // All recorded object metrics for this trial. + repeated HyperparameterMetric all_metrics = 4; +} + +// Represents results of a training job. Output only. +message TrainingOutput { + // The number of hyperparameter tuning trials that completed successfully. + // Only set for hyperparameter tuning jobs. + int64 completed_trial_count = 1; + + // Results for individual Hyperparameter trials. + // Only set for hyperparameter tuning jobs. + repeated HyperparameterOutput trials = 2; + + // The amount of ML units consumed by the job. + double consumed_ml_units = 3; + + // Whether this job is a hyperparameter tuning job. + bool is_hyperparameter_tuning_job = 4; +} + +// Represents input parameters for a prediction job. +message PredictionInput { + // The format used to separate data instances in the source files. + enum DataFormat { + // Unspecified format. + DATA_FORMAT_UNSPECIFIED = 0; + + // The source file is a text file with instances separated by the + // new-line character. + TEXT = 1; + + // The source file is a TFRecord file. + TF_RECORD = 2; + + // The source file is a GZIP-compressed TFRecord file. + TF_RECORD_GZIP = 3; + } + + // Required. The model or the version to use for prediction. + oneof model_version { + // Use this field if you want to use the default version for the specified + // model. The string must use the following format: + // + // `"projects/[YOUR_PROJECT]/models/[YOUR_MODEL]"` + string model_name = 1; + + // Use this field if you want to specify a version of the model to use. The + // string is formatted the same way as `model_version`, with the addition + // of the version information: + // + // `"projects/[YOUR_PROJECT]/models/YOUR_MODEL/versions/[YOUR_VERSION]"` + string version_name = 2; + + // Use this field if you want to specify a Google Cloud Storage path for + // the model to use. + string uri = 9; + } + + // Required. The format of the input data files. + DataFormat data_format = 3; + + // Required. The Google Cloud Storage location of the input data files. + // May contain wildcards. + repeated string input_paths = 4; + + // Required. The output Google Cloud Storage location. + string output_path = 5; + + // Optional. The maximum number of workers to be used for parallel processing. + // Defaults to 10 if not specified. + int64 max_worker_count = 6; + + // Required. The Google Compute Engine region to run the prediction job in. + string region = 7; + + // Optional. The Google Cloud ML runtime version to use for this batch + // prediction. If not set, Google Cloud ML will pick the runtime version used + // during the CreateVersion request for this model version, or choose the + // latest stable version when model version information is not available + // such as when the model is specified by uri. + string runtime_version = 8; +} + +// Represents results of a prediction job. +message PredictionOutput { + // The output Google Cloud Storage location provided at the job creation time. + string output_path = 1; + + // The number of generated predictions. + int64 prediction_count = 2; + + // The number of data instances which resulted in errors. + int64 error_count = 3; + + // Node hours used by the batch prediction job. + double node_hours = 4; +} + +// Represents a training or prediction job. +message Job { + // Describes the job state. + enum State { + // The job state is unspecified. + STATE_UNSPECIFIED = 0; + + // The job has been just created and processing has not yet begun. + QUEUED = 1; + + // The service is preparing to run the job. + PREPARING = 2; + + // The job is in progress. + RUNNING = 3; + + // The job completed successfully. + SUCCEEDED = 4; + + // The job failed. + // `error_message` should contain the details of the failure. + FAILED = 5; + + // The job is being cancelled. + // `error_message` should describe the reason for the cancellation. + CANCELLING = 6; + + // The job has been cancelled. + // `error_message` should describe the reason for the cancellation. + CANCELLED = 7; + } + + // Required. The user-specified id of the job. + string job_id = 1; + + // Required. Parameters to create a job. + oneof input { + // Input parameters to create a training job. + TrainingInput training_input = 2; + + // Input parameters to create a prediction job. + PredictionInput prediction_input = 3; + } + + // Output only. When the job was created. + google.protobuf.Timestamp create_time = 4; + + // Output only. When the job processing was started. + google.protobuf.Timestamp start_time = 5; + + // Output only. When the job processing was completed. + google.protobuf.Timestamp end_time = 6; + + // Output only. The detailed state of a job. + State state = 7; + + // Output only. The details of a failure or a cancellation. + string error_message = 8; + + // Output only. The current result of the job. + oneof output { + // The current training job result. + TrainingOutput training_output = 9; + + // The current prediction job result. + PredictionOutput prediction_output = 10; + } +} + +// Request message for the CreateJob method. +message CreateJobRequest { + // Required. The project name. + // + // Authorization: requires `Editor` role on the specified project. + string parent = 1; + + // Required. The job to create. + Job job = 2; +} + +// Request message for the ListJobs method. +message ListJobsRequest { + // Required. The name of the project for which to list jobs. + // + // Authorization: requires `Viewer` role on the specified project. + string parent = 1; + + // Optional. Specifies the subset of jobs to retrieve. + string filter = 2; + + // Optional. A page token to request the next page of results. + // + // You get the token from the `next_page_token` field of the response from + // the previous call. + string page_token = 4; + + // Optional. The number of jobs to retrieve per "page" of results. If there + // are more remaining results than this number, the response message will + // contain a valid value in the `next_page_token` field. + // + // The default value is 20, and the maximum page size is 100. + int32 page_size = 5; +} + +// Response message for the ListJobs method. +message ListJobsResponse { + // The list of jobs. + repeated Job jobs = 1; + + // Optional. Pass this token as the `page_token` field of the request for a + // subsequent call. + string next_page_token = 2; +} + +// Request message for the GetJob method. +message GetJobRequest { + // Required. The name of the job to get the description of. + // + // Authorization: requires `Viewer` role on the parent project. + string name = 1; +} + +// Request message for the CancelJob method. +message CancelJobRequest { + // Required. The name of the job to cancel. + // + // Authorization: requires `Editor` role on the parent project. + string name = 1; +} diff --git a/google/cloud/ml/v1/model_service.proto b/google/cloud/ml/v1/model_service.proto new file mode 100644 index 00000000..783ba871 --- /dev/null +++ b/google/cloud/ml/v1/model_service.proto @@ -0,0 +1,371 @@ +// 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/longrunning/operations.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 = "ModelServiceProto"; +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 'models service' to work with the 'model' and 'version' +// resources. + + + +// Provides methods that create and manage machine learning models and their +// versions. +// +// A model in this context is a container for versions. The model can't provide +// predictions without first having a version created for it. +// +// Each version is a trained machine learning model, and each is assumed to be +// an iteration of the same machine learning problem as the other versions of +// the same model. +// +// Your project can define multiple models, each with multiple versions. +// +// The basic life cycle of a model is: +// +// * Create and train the machine learning model and save it to a +// Google Cloud Storage location. +// * Use +// [projects.models.create](/ml/reference/rest/v1/projects.models/create) +// to make a new model in your project. +// * Use +// [projects.models.versions.create](/ml/reference/rest/v1/projects.models.versions/create) +// to deploy your saved model. +// * Use [projects.predict](/ml/reference/rest/v1/projects/predict to +// request predictions of a version of your model, or use +// [projects.jobs.create](/ml/reference/rest/v1/projects.jobs/create) +// to start a batch prediction job. +service ModelService { + // Creates a model which will later contain one or more versions. + // + // You must add at least one version before you can request predictions from + // the model. Add versions by calling + // [projects.models.versions.create](/ml/reference/rest/v1/projects.models.versions/create). + rpc CreateModel(CreateModelRequest) returns (Model) { + option (google.api.http) = { post: "/v1/{parent=projects/*}/models" body: "model" }; + } + + // Lists the models in a project. + // + // Each project can contain multiple models, and each model can have multiple + // versions. + rpc ListModels(ListModelsRequest) returns (ListModelsResponse) { + option (google.api.http) = { get: "/v1/{parent=projects/*}/models" }; + } + + // Gets information about a model, including its name, the description (if + // set), and the default version (if at least one version of the model has + // been deployed). + rpc GetModel(GetModelRequest) returns (Model) { + option (google.api.http) = { get: "/v1/{name=projects/*/models/*}" }; + } + + // Deletes a model. + // + // You can only delete a model if there are no versions in it. You can delete + // versions by calling + // [projects.models.versions.delete](/ml/reference/rest/v1/projects.models.versions/delete). + rpc DeleteModel(DeleteModelRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { delete: "/v1/{name=projects/*/models/*}" }; + } + + // Creates a new version of a model from a trained TensorFlow model. + // + // If the version created in the cloud by this call is the first deployed + // version of the specified model, it will be made the default version of the + // model. When you add a version to a model that already has one or more + // versions, the default version does not automatically change. If you want a + // new version to be the default, you must call + // [projects.models.versions.setDefault](/ml/reference/rest/v1/projects.models.versions/setDefault). + rpc CreateVersion(CreateVersionRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { post: "/v1/{parent=projects/*/models/*}/versions" body: "version" }; + } + + // Gets basic information about all the versions of a model. + // + // If you expect that a model has a lot of versions, or if you need to handle + // only a limited number of results at a time, you can request that the list + // be retrieved in batches (called pages): + rpc ListVersions(ListVersionsRequest) returns (ListVersionsResponse) { + option (google.api.http) = { get: "/v1/{parent=projects/*/models/*}/versions" }; + } + + // Gets information about a model version. + // + // Models can have multiple versions. You can call + // [projects.models.versions.list](/ml/reference/rest/v1/projects.models.versions/list) + // to get the same information that this method returns for all of the + // versions of a model. + rpc GetVersion(GetVersionRequest) returns (Version) { + option (google.api.http) = { get: "/v1/{name=projects/*/models/*/versions/*}" }; + } + + // Deletes a model version. + // + // Each model can have multiple versions deployed and in use at any given + // time. Use this method to remove a single version. + // + // Note: You cannot delete the version that is set as the default version + // of the model unless it is the only remaining version. + rpc DeleteVersion(DeleteVersionRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { delete: "/v1/{name=projects/*/models/*/versions/*}" }; + } + + // Designates a version to be the default for the model. + // + // The default version is used for prediction requests made against the model + // that don't specify a version. + // + // The first version to be created for a model is automatically set as the + // default. You must make any subsequent changes to the default version + // setting manually using this method. + rpc SetDefaultVersion(SetDefaultVersionRequest) returns (Version) { + option (google.api.http) = { post: "/v1/{name=projects/*/models/*/versions/*}:setDefault" body: "*" }; + } +} + +// Represents a machine learning solution. +// +// A model can have multiple versions, each of which is a deployed, trained +// model ready to receive prediction requests. The model itself is just a +// container. +message Model { + // Required. The name specified for the model when it was created. + // + // The model name must be unique within the project it is created in. + string name = 1; + + // Optional. The description specified for the model when it was created. + string description = 2; + + // Output only. The default version of the model. This version will be used to + // handle prediction requests that do not specify a version. + // + // You can change the default version by calling + // [projects.methods.versions.setDefault](/ml/reference/rest/v1/projects.models.versions/setDefault). + Version default_version = 3; + + // Optional. The list of regions where the model is going to be deployed. + // Currently only one region per model is supported. + // Defaults to 'us-central1' if nothing is set. + repeated string regions = 4; + + // Optional. If true, enables StackDriver Logging for online prediction. + // Default is false. + bool online_prediction_logging = 5; +} + +// Represents a version of the model. +// +// Each version is a trained model deployed in the cloud, ready to handle +// prediction requests. A model can have multiple versions. You can get +// information about all of the versions of a given model by calling +// [projects.models.versions.list](/ml/reference/rest/v1/projects.models.versions/list). +message Version { + // Required.The name specified for the version when it was created. + // + // The version name must be unique within the model it is created in. + string name = 1; + + // Optional. The description specified for the version when it was created. + string description = 2; + + // Output only. If true, this version will be used to handle prediction + // requests that do not specify a version. + // + // You can change the default version by calling + // [projects.methods.versions.setDefault](/ml/reference/rest/v1/projects.models.versions/setDefault). + bool is_default = 3; + + // Required. The Google Cloud Storage location of the trained model used to + // create the version. See the + // [overview of model deployment](/ml/docs/concepts/deployment-overview) for + // more informaiton. + // + // When passing Version to + // [projects.models.versions.create](/ml/reference/rest/v1/projects.models.versions/create) + // the model service uses the specified location as the source of the model. + // Once deployed, the model version is hosted by the prediction service, so + // this location is useful only as a historical record. + string deployment_uri = 4; + + // Output only. The time the version was created. + google.protobuf.Timestamp create_time = 5; + + // Output only. The time the version was last used for prediction. + google.protobuf.Timestamp last_use_time = 6; + + // Optional. The Google Cloud ML runtime version to use for this deployment. + // If not set, Google Cloud ML will choose a version. + string runtime_version = 8; + + // Optional. Manually select the number of nodes to use for serving the + // model. If unset (i.e., by default), the number of nodes used to serve + // the model automatically scales with traffic. However, care should be + // taken to ramp up traffic according to the model's ability to scale. If + // your model needs to handle bursts of traffic beyond it's ability to + // scale, it is recommended you set this field appropriately. + ManualScaling manual_scaling = 9; +} + +// Options for manually scaling a model. +message ManualScaling { + // The number of nodes to allocate for this model. These nodes are always up, + // starting from the time the model is deployed, so the cost of operating + // this model will be proportional to nodes * number of hours since + // deployment. + int32 nodes = 1; +} + +// Request message for the CreateModel method. +message CreateModelRequest { + // Required. The project name. + // + // Authorization: requires `Editor` role on the specified project. + string parent = 1; + + // Required. The model to create. + Model model = 2; +} + +// Request message for the ListModels method. +message ListModelsRequest { + // Required. The name of the project whose models are to be listed. + // + // Authorization: requires `Viewer` role on the specified project. + string parent = 1; + + // Optional. A page token to request the next page of results. + // + // You get the token from the `next_page_token` field of the response from + // the previous call. + string page_token = 4; + + // Optional. The number of models to retrieve per "page" of results. If there + // are more remaining results than this number, the response message will + // contain a valid value in the `next_page_token` field. + // + // The default value is 20, and the maximum page size is 100. + int32 page_size = 5; +} + +// Response message for the ListModels method. +message ListModelsResponse { + // The list of models. + repeated Model models = 1; + + // Optional. Pass this token as the `page_token` field of the request for a + // subsequent call. + string next_page_token = 2; +} + +// Request message for the GetModel method. +message GetModelRequest { + // Required. The name of the model. + // + // Authorization: requires `Viewer` role on the parent project. + string name = 1; +} + +// Request message for the DeleteModel method. +message DeleteModelRequest { + // Required. The name of the model. + // + // Authorization: requires `Editor` role on the parent project. + string name = 1; +} + +// Uploads the provided trained model version to Cloud Machine Learning. +message CreateVersionRequest { + // Required. The name of the model. + // + // Authorization: requires `Editor` role on the parent project. + string parent = 1; + + // Required. The version details. + Version version = 2; +} + +// Request message for the ListVersions method. +message ListVersionsRequest { + // Required. The name of the model for which to list the version. + // + // Authorization: requires `Viewer` role on the parent project. + string parent = 1; + + // Optional. A page token to request the next page of results. + // + // You get the token from the `next_page_token` field of the response from + // the previous call. + string page_token = 4; + + // Optional. The number of versions to retrieve per "page" of results. If + // there are more remaining results than this number, the response message + // will contain a valid value in the `next_page_token` field. + // + // The default value is 20, and the maximum page size is 100. + int32 page_size = 5; +} + +// Response message for the ListVersions method. +message ListVersionsResponse { + // The list of versions. + repeated Version versions = 1; + + // Optional. Pass this token as the `page_token` field of the request for a + // subsequent call. + string next_page_token = 2; +} + +// Request message for the GetVersion method. +message GetVersionRequest { + // Required. The name of the version. + // + // Authorization: requires `Viewer` role on the parent project. + string name = 1; +} + +// Request message for the DeleteVerionRequest method. +message DeleteVersionRequest { + // Required. The name of the version. You can get the names of all the + // versions of a model by calling + // [projects.models.versions.list](/ml/reference/rest/v1/projects.models.versions/list). + // + // Authorization: requires `Editor` role on the parent project. + string name = 1; +} + +// Request message for the SetDefaultVersion request. +message SetDefaultVersionRequest { + // Required. The name of the version to make the default for the model. You + // can get the names of all the versions of a model by calling + // [projects.models.versions.list](/ml/reference/rest/v1/projects.models.versions/list). + // + // Authorization: requires `Editor` role on the parent project. + string name = 1; +} diff --git a/google/cloud/ml/v1/operation_metadata.proto b/google/cloud/ml/v1/operation_metadata.proto new file mode 100644 index 00000000..c29a7892 --- /dev/null +++ b/google/cloud/ml/v1/operation_metadata.proto @@ -0,0 +1,72 @@ +// 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/cloud/ml/v1/model_service.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 = "OperationMetadataProto"; +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 metadata for longrunning operations. + + + +// Represents the metadata of the long-running operation. +message OperationMetadata { + // The operation type. + enum OperationType { + // Unspecified operation type. + OPERATION_TYPE_UNSPECIFIED = 0; + + // An operation to create a new version. + CREATE_VERSION = 1; + + // An operation to delete an existing version. + DELETE_VERSION = 2; + + // An operation to delete an existing model. + DELETE_MODEL = 3; + } + + // The time the operation was submitted. + google.protobuf.Timestamp create_time = 1; + + // The time operation processing started. + google.protobuf.Timestamp start_time = 2; + + // The time operation processing completed. + google.protobuf.Timestamp end_time = 3; + + // Indicates whether a request to cancel this operation has been made. + bool is_cancellation_requested = 4; + + // The operation type. + OperationType operation_type = 5; + + // Contains the name of the model associated with the operation. + string model_name = 6; + + // Contains the version associated with the operation. + Version version = 7; +} diff --git a/google/cloud/ml/v1/prediction_service.proto b/google/cloud/ml/v1/prediction_service.proto new file mode 100644 index 00000000..c5e25dcd --- /dev/null +++ b/google/cloud/ml/v1/prediction_service.proto @@ -0,0 +1,240 @@ +// 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/httpbody.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/ml/v1;ml"; +option java_multiple_files = true; +option java_outer_classname = "PredictionServiceProto"; +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 online prediction service. + + + +// The Prediction API, which serves predictions for models managed by +// ModelService. +service OnlinePredictionService { + // Performs prediction on the data in the request. + // + // **** REMOVE FROM GENERATED DOCUMENTATION + rpc Predict(PredictRequest) returns (google.api.HttpBody) { + option (google.api.http) = { post: "/v1/{name=projects/**}:predict" body: "*" }; + } +} + +// Request for predictions to be issued against a trained model. +// +// The body of the request is a single JSON object with a single top-level +// field: +// +//
+//
instances
+//
A JSON array containing values representing the instances to use for +// prediction.
+//
+// +// The structure of each element of the instances list is determined by your +// model's input definition. Instances can include named inputs or can contain +// only unlabeled values. +// +// 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: +// +// CSV data with each row encoded as a string value: +//
+// {"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_m
//
// A machine with roughly twice the number of cores and roughly double the - // memory of `complex_model_s`. + // memory of complex_model_s. //
//
complex_model_l
//
// A machine with roughly twice the number of cores and roughly double the - // memory of `complex_model_m`. + // memory of complex_model_m. + //
+ //
standard_gpu
+ //
+ // A machine equivalent to standard that + // also includes a + // + // GPU that you can use in your trainer. + //
+ //
complex_model_m_gpu
+ //
+ // A machine equivalent to + // coplex_model_m that also includes + // four GPUs. //
// // - // This value can only be used when `ScaleTier` is set to `CUSTOM`. + // You must set this value when `scaleTier` is set to `CUSTOM`. string master_type = 2; // Optional. Specifies the type of virtual machine to use for your training // job's worker nodes. // // The supported values are the same as those described in the entry for - // `master_type`. + // `masterType`. // - // This value must be present when `scale_tier` is set to `CUSTOM` and - // `worker_count` is greater than zero. + // This value must be present when `scaleTier` is set to `CUSTOM` and + // `workerCount` is greater than zero. string worker_type = 3; // Optional. Specifies the type of virtual machine to use for your training @@ -144,7 +180,7 @@ message TrainingInput { // The supported values are the same as those described in the entry for // `master_type`. // - // This value must be present when `scale_tier` is set to `CUSTOM` and + // This value must be present when `scaleTier` is set to `CUSTOM` and // `parameter_server_count` is greater than zero. string parameter_server_type = 4; @@ -178,6 +214,16 @@ message TrainingInput { // Required. The Google Compute Engine region to run the training job in. string region = 14; + + // Optional. A Google Cloud Storage path in which to store training outputs + // and other data needed for training. This path is passed to your TensorFlow + // program as the 'job_dir' command-line argument. The benefit of specifying + // this field is that Cloud ML validates the path for use in training. + string job_dir = 16; + + // Optional. The Google Cloud ML runtime version to use for training. If not + // set, Google Cloud ML will choose the latest stable version. + string runtime_version = 15; } // Represents a set of hyperparameters to optimize. @@ -220,6 +266,13 @@ message HyperparameterSpec { // // Defaults to one. int32 max_parallel_trials = 4; + + // Optional. The Tensorflow summary tag name to use for optimizing trials. For + // current versions of Tensorflow, this tag name should exactly match what is + // shown in Tensorboard, including all scopes. For versions of Tensorflow + // prior to 0.12, this should be only the tag passed to tf.Summary. + // By default, "training/hptuning/metric" will be used. + string hyperparameter_metric_tag = 5; } // Represents a single hyperparameter to optimize. @@ -326,13 +379,21 @@ message HyperparameterOutput { repeated HyperparameterMetric all_metrics = 4; } -// Represents results of a training job. +// Represents results of a training job. Output only. message TrainingOutput { // The number of hyperparameter tuning trials that completed successfully. + // Only set for hyperparameter tuning jobs. int64 completed_trial_count = 1; // Results for individual Hyperparameter trials. + // Only set for hyperparameter tuning jobs. repeated HyperparameterOutput trials = 2; + + // The amount of ML units consumed by the job. + double consumed_ml_units = 3; + + // Whether this job is a hyperparameter tuning job. + bool is_hyperparameter_tuning_job = 4; } // Represents input parameters for a prediction job. @@ -358,15 +419,19 @@ message PredictionInput { // Use this field if you want to use the default version for the specified // model. The string must use the following format: // - // `"project/[YOUR_PROJECT]/models/[YOUR_MODEL]"` + // `"projects/[YOUR_PROJECT]/models/[YOUR_MODEL]"` string model_name = 1; // Use this field if you want to specify a version of the model to use. The // string is formatted the same way as `model_version`, with the addition // of the version information: // - // `"project/[YOUR_PROJECT]/models/YOUR_MODEL/versions/[YOUR_VERSION]"` + // `"projects/[YOUR_PROJECT]/models/YOUR_MODEL/versions/[YOUR_VERSION]"` string version_name = 2; + + // Use this field if you want to specify a Google Cloud Storage path for + // the model to use. + string uri = 9; } // Required. The format of the input data files. @@ -379,12 +444,19 @@ message PredictionInput { // Required. The output Google Cloud Storage location. string output_path = 5; - // Optional. The maximum amount of workers to be used for parallel processing. - // Defaults to 10. + // Optional. The maximum number of workers to be used for parallel processing. + // Defaults to 10 if not specified. int64 max_worker_count = 6; // Required. The Google Compute Engine region to run the prediction job in. string region = 7; + + // Optional. The Google Cloud ML runtime version to use for this batch + // prediction. If not set, Google Cloud ML will pick the runtime version used + // during the CreateVersion request for this model version, or choose the + // latest stable version when model version information is not available + // such as when the model is specified by uri. + string runtime_version = 8; } // Represents results of a prediction job. @@ -397,6 +469,9 @@ message PredictionOutput { // The number of data instances which resulted in errors. int64 error_count = 3; + + // Node hours used by the batch prediction job. + double node_hours = 4; } // Represents a training or prediction job. diff --git a/google/cloud/ml/v1beta1/model_service.proto b/google/cloud/ml/v1beta1/model_service.proto index 67eacb95..08b0d37a 100644 --- a/google/cloud/ml/v1beta1/model_service.proto +++ b/google/cloud/ml/v1beta1/model_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,8 +17,8 @@ syntax = "proto3"; package google.cloud.ml.v1beta1; import "google/api/annotations.proto"; +import "google/api/auth.proto"; import "google/longrunning/operations.proto"; -import "google/protobuf/empty.proto"; import "google/protobuf/timestamp.proto"; option go_package = "google.golang.org/genproto/googleapis/cloud/ml/v1beta1;ml"; @@ -28,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 'models service' to work with the 'model' and 'version' // resources. @@ -169,6 +169,15 @@ message Model { // You can change the default version by calling // [projects.methods.versions.setDefault](/ml/reference/rest/v1beta1/projects.models.versions/setDefault). Version default_version = 3; + + // Optional. The list of regions where the model is going to be deployed. + // Currently only one region per model is supported. + // Defaults to 'us-central1' if nothing is set. + repeated string regions = 4; + + // Optional. If true, enables StackDriver Logging for online prediction. + // Default is false. + bool online_prediction_logging = 5; } // Represents a version of the model. @@ -210,6 +219,27 @@ message Version { // Output only. The time the version was last used for prediction. google.protobuf.Timestamp last_use_time = 6; + + // Optional. The Google Cloud ML runtime version to use for this deployment. + // If not set, Google Cloud ML will choose a version. + string runtime_version = 8; + + // Optional. Manually select the number of nodes to use for serving the + // model. If unset (i.e., by default), the number of nodes used to serve + // the model automatically scales with traffic. However, care should be + // taken to ramp up traffic according to the model's ability to scale. If + // your model needs to handle bursts of traffic beyond it's ability to + // scale, it is recommended you set this field appropriately. + ManualScaling manual_scaling = 9; +} + +// Options for manually scaling a model. +message ManualScaling { + // The number of nodes to allocate for this model. These nodes are always up, + // starting from the time the model is deployed, so the cost of operating + // this model will be proportional to nodes * number of hours since + // deployment. + int32 nodes = 1; } // Request message for the CreateModel method. diff --git a/google/cloud/ml/v1beta1/operation_metadata.proto b/google/cloud/ml/v1beta1/operation_metadata.proto index 65f9da5c..a7264719 100644 --- a/google/cloud/ml/v1beta1/operation_metadata.proto +++ b/google/cloud/ml/v1beta1/operation_metadata.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. @@ -27,7 +27,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 metadata for longrunning operations. diff --git a/google/cloud/ml/v1beta1/prediction_service.proto b/google/cloud/ml/v1beta1/prediction_service.proto index 622008c2..6374ca22 100644 --- a/google/cloud/ml/v1beta1/prediction_service.proto +++ b/google/cloud/ml/v1beta1/prediction_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. @@ -26,7 +26,8 @@ option java_package = "com.google.cloud.ml.api.v1beta1"; // Copyright 2016 Google Inc. All Rights Reserved. // -// Proto file for the Prediction service, both online and batch prediction. +// Proto file for the Google Cloud Machine Learning Engine. +// Describes the online prediction service. @@ -35,51 +36,7 @@ option java_package = "com.google.cloud.ml.api.v1beta1"; service OnlinePredictionService { // Performs prediction on the data in the request. // - // Responses are very similar to requests. There are two top-level fields, - // each of which are JSON lists: - // - //
- //
predictions
- //
The list of predictions, one per instance in the request.
- //
error
- //
An error message returned instead of a prediction list if any - // instance produced an error.
- //
- // - // 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. - // - // Even though there is one prediction per instance, the format of a - // prediction is not directly related to the format of an instance. - // Predictions take whatever format is specified in the outputs collection - // defined in the model. The collection of predictions is returned in a JSON - // list. Each member of the list can be a simple value, a list, or a JSON - // object of any complexity. If your model has more than one output tensor, - // each prediction will be a JSON object containing a name/value pair for each - // output. The names identify the output aliases in the graph. - // - // The following examples show some possible responses: - // - // A simple set of predictions for three input instances, where each - // prediction is an integer value: - //
-  // {"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 {