1// Copyright 2021 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.cloud.retail.v2beta; 18 19import "google/api/field_behavior.proto"; 20import "google/api/resource.proto"; 21import "google/cloud/retail/v2beta/common.proto"; 22import "google/protobuf/timestamp.proto"; 23 24option csharp_namespace = "Google.Cloud.Retail.V2Beta"; 25option go_package = "cloud.google.com/go/retail/apiv2beta/retailpb;retailpb"; 26option java_multiple_files = true; 27option java_outer_classname = "ModelProto"; 28option java_package = "com.google.cloud.retail.v2beta"; 29option objc_class_prefix = "RETAIL"; 30option php_namespace = "Google\\Cloud\\Retail\\V2beta"; 31option ruby_package = "Google::Cloud::Retail::V2beta"; 32 33// Metadata that describes the training and serving parameters of a 34// [Model][google.cloud.retail.v2beta.Model]. A 35// [Model][google.cloud.retail.v2beta.Model] can be associated with a 36// [ServingConfig][google.cloud.retail.v2beta.ServingConfig] and then queried 37// through the Predict API. 38message Model { 39 option (google.api.resource) = { 40 type: "retail.googleapis.com/Model" 41 pattern: "projects/{project}/locations/{location}/catalogs/{catalog}/models/{model}" 42 }; 43 44 // Represents an ordered combination of valid serving configs, which 45 // can be used for `PAGE_OPTIMIZATION` recommendations. 46 message ServingConfigList { 47 // Optional. A set of valid serving configs that may be used for 48 // `PAGE_OPTIMIZATION`. 49 repeated string serving_config_ids = 1 50 [(google.api.field_behavior) = OPTIONAL]; 51 } 52 53 // The serving state of the model. 54 enum ServingState { 55 // Unspecified serving state. 56 SERVING_STATE_UNSPECIFIED = 0; 57 58 // The model is not serving. 59 INACTIVE = 1; 60 61 // The model is serving and can be queried. 62 ACTIVE = 2; 63 64 // The model is trained on tuned hyperparameters and can be 65 // queried. 66 TUNED = 3; 67 } 68 69 // The training state of the model. 70 enum TrainingState { 71 // Unspecified training state. 72 TRAINING_STATE_UNSPECIFIED = 0; 73 74 // The model training is paused. 75 PAUSED = 1; 76 77 // The model is training. 78 TRAINING = 2; 79 } 80 81 // Describes whether periodic tuning is enabled for this model 82 // or not. Periodic tuning is scheduled at most every three months. You can 83 // start a tuning process manually by using the `TuneModel` 84 // method, which starts a tuning process immediately and resets the quarterly 85 // schedule. Enabling or disabling periodic tuning does not affect any 86 // current tuning processes. 87 enum PeriodicTuningState { 88 // Unspecified default value, should never be explicitly set. 89 PERIODIC_TUNING_STATE_UNSPECIFIED = 0; 90 91 // The model has periodic tuning disabled. Tuning 92 // can be reenabled by calling the `EnableModelPeriodicTuning` 93 // method or by calling the `TuneModel` method. 94 PERIODIC_TUNING_DISABLED = 1; 95 96 // The model cannot be tuned with periodic tuning OR the 97 // `TuneModel` method. Hide the options in customer UI and 98 // reject any requests through the backend self serve API. 99 ALL_TUNING_DISABLED = 3; 100 101 // The model has periodic tuning enabled. Tuning 102 // can be disabled by calling the `DisableModelPeriodicTuning` 103 // method. 104 PERIODIC_TUNING_ENABLED = 2; 105 } 106 107 // Describes whether this model have sufficient training data 108 // to be continuously trained. 109 enum DataState { 110 // Unspecified default value, should never be explicitly set. 111 DATA_STATE_UNSPECIFIED = 0; 112 113 // The model has sufficient training data. 114 DATA_OK = 1; 115 116 // The model does not have sufficient training data. Error 117 // messages can be queried via Stackdriver. 118 DATA_ERROR = 2; 119 } 120 121 // Required. The fully qualified resource name of the model. 122 // 123 // Format: 124 // `projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/models/{model_id}` 125 // catalog_id has char limit of 50. 126 // recommendation_model_id has char limit of 40. 127 string name = 1 [(google.api.field_behavior) = REQUIRED]; 128 129 // Required. The display name of the model. 130 // 131 // Should be human readable, used to display Recommendation Models in the 132 // Retail Cloud Console Dashboard. UTF-8 encoded string with limit of 1024 133 // characters. 134 string display_name = 2 [(google.api.field_behavior) = REQUIRED]; 135 136 // Optional. The training state that the model is in (e.g. 137 // `TRAINING` or `PAUSED`). 138 // 139 // Since part of the cost of running the service 140 // is frequency of training - this can be used to determine when to train 141 // model in order to control cost. If not specified: the default value for 142 // `CreateModel` method is `TRAINING`. The default value for 143 // `UpdateModel` method is to keep the state the same as before. 144 TrainingState training_state = 3 [(google.api.field_behavior) = OPTIONAL]; 145 146 // Output only. The serving state of the model: `ACTIVE`, `NOT_ACTIVE`. 147 ServingState serving_state = 4 [(google.api.field_behavior) = OUTPUT_ONLY]; 148 149 // Output only. Timestamp the Recommendation Model was created at. 150 google.protobuf.Timestamp create_time = 5 151 [(google.api.field_behavior) = OUTPUT_ONLY]; 152 153 // Output only. Timestamp the Recommendation Model was last updated. E.g. 154 // if a Recommendation Model was paused - this would be the time the pause was 155 // initiated. 156 google.protobuf.Timestamp update_time = 6 157 [(google.api.field_behavior) = OUTPUT_ONLY]; 158 159 // Required. The type of model e.g. `home-page`. 160 // 161 // Currently supported values: `recommended-for-you`, `others-you-may-like`, 162 // `frequently-bought-together`, `page-optimization`, `similar-items`, 163 // `buy-it-again`, `on-sale-items`, and `recently-viewed`(readonly value). 164 // 165 // 166 // This field together with 167 // [optimization_objective][google.cloud.retail.v2beta.Model.optimization_objective] 168 // describe model metadata to use to control model training and serving. 169 // See https://cloud.google.com/retail/docs/models 170 // for more details on what the model metadata control and which combination 171 // of parameters are valid. For invalid combinations of parameters (e.g. type 172 // = `frequently-bought-together` and optimization_objective = `ctr`), you 173 // receive an error 400 if you try to create/update a recommendation with 174 // this set of knobs. 175 string type = 7 [(google.api.field_behavior) = REQUIRED]; 176 177 // Optional. The optimization objective e.g. `cvr`. 178 // 179 // Currently supported 180 // values: `ctr`, `cvr`, `revenue-per-order`. 181 // 182 // If not specified, we choose default based on model type. 183 // Default depends on type of recommendation: 184 // 185 // `recommended-for-you` => `ctr` 186 // 187 // `others-you-may-like` => `ctr` 188 // 189 // `frequently-bought-together` => `revenue_per_order` 190 // 191 // This field together with 192 // [optimization_objective][google.cloud.retail.v2beta.Model.type] 193 // describe model metadata to use to control model training and serving. 194 // See https://cloud.google.com/retail/docs/models 195 // for more details on what the model metadata control and which combination 196 // of parameters are valid. For invalid combinations of parameters (e.g. type 197 // = `frequently-bought-together` and optimization_objective = `ctr`), you 198 // receive an error 400 if you try to create/update a recommendation with 199 // this set of knobs. 200 string optimization_objective = 8 [(google.api.field_behavior) = OPTIONAL]; 201 202 // Optional. The state of periodic tuning. 203 // 204 // The period we use is 3 months - to do a 205 // one-off tune earlier use the `TuneModel` method. Default value 206 // is `PERIODIC_TUNING_ENABLED`. 207 PeriodicTuningState periodic_tuning_state = 11 208 [(google.api.field_behavior) = OPTIONAL]; 209 210 // Output only. The timestamp when the latest successful tune finished. 211 google.protobuf.Timestamp last_tune_time = 12 212 [(google.api.field_behavior) = OUTPUT_ONLY]; 213 214 // Output only. The tune operation associated with the model. 215 // 216 // Can be used to determine if there is an ongoing tune for this 217 // recommendation. Empty field implies no tune is goig on. 218 string tuning_operation = 15 [(google.api.field_behavior) = OUTPUT_ONLY]; 219 220 // Output only. The state of data requirements for this model: `DATA_OK` and 221 // `DATA_ERROR`. 222 // 223 // Recommendation model cannot be trained if the data is in 224 // `DATA_ERROR` state. Recommendation model can have `DATA_ERROR` state even 225 // if serving state is `ACTIVE`: models were trained successfully before, but 226 // cannot be refreshed because model no longer has sufficient 227 // data for training. 228 DataState data_state = 16 [(google.api.field_behavior) = OUTPUT_ONLY]; 229 230 // Optional. If `RECOMMENDATIONS_FILTERING_ENABLED`, recommendation filtering 231 // by attributes is enabled for the model. 232 RecommendationsFilteringOption filtering_option = 18 233 [(google.api.field_behavior) = OPTIONAL]; 234 235 // Output only. The list of valid serving configs associated with the 236 // PageOptimizationConfig. 237 repeated ServingConfigList serving_config_lists = 19 238 [(google.api.field_behavior) = OUTPUT_ONLY]; 239} 240