diff options
Diffstat (limited to 'third_party/googleapis/google/cloud/retail/v2alpha/model.proto')
| -rw-r--r-- | third_party/googleapis/google/cloud/retail/v2alpha/model.proto | 432 |
1 files changed, 432 insertions, 0 deletions
diff --git a/third_party/googleapis/google/cloud/retail/v2alpha/model.proto b/third_party/googleapis/google/cloud/retail/v2alpha/model.proto new file mode 100644 index 0000000..5f4ead9 --- /dev/null +++ b/third_party/googleapis/google/cloud/retail/v2alpha/model.proto @@ -0,0 +1,432 @@ +// Copyright 2021 Google LLC +// +// 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.retail.v2alpha; + +import "google/api/field_behavior.proto"; +import "google/api/resource.proto"; +import "google/cloud/retail/v2alpha/common.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.Retail.V2Alpha"; +option go_package = "google.golang.org/genproto/googleapis/cloud/retail/v2alpha;retail"; +option java_multiple_files = true; +option java_outer_classname = "ModelProto"; +option java_package = "com.google.cloud.retail.v2alpha"; +option objc_class_prefix = "RETAIL"; +option php_namespace = "Google\\Cloud\\Retail\\V2alpha"; +option ruby_package = "Google::Cloud::Retail::V2alpha"; + +// Metadata that describes the training and serving parameters of a +// [Model][google.cloud.retail.v2alpha.Model]. A +// [Model][google.cloud.retail.v2alpha.Model] can be associated with a +// [ServingConfig][google.cloud.retail.v2alpha.ServingConfig] and then queried +// through the Predict api. +message Model { + option (google.api.resource) = { + type: "retail.googleapis.com/Model" + pattern: "projects/{project}/locations/{location}/catalogs/{catalog}/models/{model}" + }; + + // The PageOptimizationConfig for model training. + // + // This determines how many panels to optimize for, and which serving + // configurations to consider for each panel. + // The purpose of this model is to optimize which + // [ServingConfig][google.cloud.retail.v2alpha.ServingConfig] to show on which + // panels in way that optimizes the visitors shopping journey. + message PageOptimizationConfig { + // A candidate to consider for a given panel. Currently only + // [ServingConfig][google.cloud.retail.v2alpha.ServingConfig] are valid + // candidates. + message Candidate { + oneof candidate { + // This has to be a valid + // [ServingConfig][google.cloud.retail.v2alpha.ServingConfig] + // identifier. e.g. for a ServingConfig with full name: + // `projects/*/locations/global/catalogs/default_catalog/servingConfigs/my_candidate_config` + // this would be 'my_candidate_config' + string serving_config_id = 1; + } + } + + // An individual panel with a list of + // [ServingConfigs][google.cloud.retail.v2alpha.ServingConfig] to consider + // for it. + message Panel { + // Optional. The name to display for the panel. + string display_name = 1 [(google.api.field_behavior) = OPTIONAL]; + + // Required. The candidates to consider on the panel. + // + // Limit = 10. + repeated Candidate candidates = 2 + [(google.api.field_behavior) = REQUIRED]; + + // Required. The default candidate (in case the model fails at serving + // time, we can fall back to the default). + Candidate default_candidate = 3 [(google.api.field_behavior) = REQUIRED]; + } + + // Restrictions of expected returned results. + enum Restriction { + // Unspecified value for restriction. + RESTRICTION_UNSPECIFIED = 0; + + // Allow any [ServingConfig][google.cloud.retail.v2alpha.ServingConfig] to + // be show on any number of panels. + // + // Example: + // + // `Panel1 candidates`: pdp_ctr, pdp_cvr, home_page_ctr_no_diversity + // + // `Panel2 candidates`: home_page_ctr_no_diversity, + // home_page_ctr_diversity, + // pdp_cvr_no_diversity + // + // `Restriction` = NO_RESTRICTION + // + // `Valid combinations`: + // + // * <i> (pdp_ctr, home_page_ctr_no_diversity) + // * (pdp_ctr, home_page_ctr_diversity) + // * (pdp_ctr, pdp_cvr_no_diversity) + // * (pdp_cvr, home_page_ctr_no_diversity) + // * (pdp_cvr, home_page_ctr_diversity) + // * (pdp_cvr, pdp_cvr_no_diversity) + // * (home_page_ctr_no_diversity, home_page_ctr_no_diversity) + // * (home_page_ctr_no_diversity, home_page_ctr_diversity) + // * (home_page_ctr_no_diversity, pdp_cvr_no_diversity) </i> + // + // `Invalid combinations`: [] + NO_RESTRICTION = 1; + + // Do not allow the same + // [ServingConfig.name][google.cloud.retail.v2alpha.ServingConfig.name] to + // be shown on multiple panels. + // + // Example: + // + // `Panel1 candidates`: <i> pdp_ctr, pdp_cvr, home_page_ctr_no_diversity + // </i> + // + // `Panel2 candidates`: <i> home_page_ctr_no_diversity, + // home_page_ctr_diversity_low, + // pdp_cvr_no_diversity </i> + // + // `Restriction` = UNIQUE_SERVING_CONFIG_RESTRICTION + // + // `Valid combinations`: + // + // * <i> (pdp_ctr, home_page_ctr_no_diversity) + // * (pdp_ctr, home_page_ctr_diversity_low) + // * (pdp_ctr, pdp_cvr_no_diversity) + // * (pdp_ctr, pdp_cvr_no_diversity) + // * (pdp_cvr, home_page_ctr_no_diversity) + // * (pdp_cvr, home_page_ctr_diversity_low) + // * (pdp_cvr, pdp_cvr_no_diversity) + // * (home_page_ctr_no_diversity, home_page_ctr_diversity_low) + // * (home_page_ctr_no_diversity, pdp_cvr_no_diversity) </i> + // + // `Invalid combinations`: + // + // * <i> (home_page_ctr_no_diversity, home_page_ctr_no_diversity) </i> + UNIQUE_SERVING_CONFIG_RESTRICTION = 2; + + // Do not allow multiple + // [ServingConfigs][google.cloud.retail.v2alpha.ServingConfig] with same + // [Model.name][google.cloud.retail.v2alpha.Model.name] to be show on on + // different panels. + // + // Example: + // + // `Panel1 candidates`: <i> pdp_ctr, pdp_cvr, home_page_ctr_no_diversity + // </i> + // + // `Panel2 candidates`: <i> home_page_ctr_no_diversity, + // home_page_ctr_diversity_low, + // pdp_cvr_no_diversity </i> + // + // `Restriction` = UNIQUE_MODEL_RESTRICTION + // + // `Valid combinations`: + // + // * <i> (pdp_ctr, home_page_ctr_no_diversity) + // * (pdp_ctr, home_page_ctr_diversity) + // * (pdp_ctr, pdp_cvr_no_diversity) + // * (pdp_ctr, pdp_cvr_no_diversity) + // * (pdp_cvr, home_page_ctr_no_diversity) + // * (pdp_cvr, home_page_ctr_diversity_low) + // * (home_page_ctr_no_diversity, pdp_cvr_no_diversity) </i> + // + // `Invalid combinations`: + // + // * <i> (home_page_ctr_no_diversity, home_page_ctr_no_diversity) + // * (pdp_cvr, pdp_cvr_no_diversity) </i> + UNIQUE_MODEL_RESTRICTION = 3; + + // Do not allow multiple + // [ServingConfigs][google.cloud.retail.v2alpha.ServingConfig] with same + // [Model.type][google.cloud.retail.v2alpha.Model.type] to be shown on + // different panels. + // + // Example: + // + // `Panel1 candidates`: <i> pdp_ctr, pdp_cvr, home_page_ctr_no_diversity + // </i> + // + // `Panel2 candidates`: <i> home_page_ctr_no_diversity, + // home_page_ctr_diversity_low, + // pdp_cvr_no_diversity </i> + // + // `Restriction` = UNIQUE_MODEL_RESTRICTION + // + // `Valid combinations`: + // + // * <i> (pdp_ctr, home_page_ctr_no_diversity) + // * (pdp_ctr, home_page_ctr_diversity) + // * (pdp_cvr, home_page_ctr_no_diversity) + // * (pdp_cvr, home_page_ctr_diversity_low) + // * (home_page_ctr_no_diversity, pdp_cvr_no_diversity) </i> + // + // `Invalid combinations`: + // + // * <i> (pdp_ctr, pdp_cvr_no_diversity) + // * (pdp_ctr, pdp_cvr_no_diversity) + // * (pdp_cvr, pdp_cvr_no_diversity) + // * (home_page_ctr_no_diversity, home_page_ctr_no_diversity) + // * (home_page_ctr_no_diversity, home_page_ctr_diversity) </i> + UNIQUE_MODEL_TYPE_RESTRICTION = 4; + } + + // Required. The type of [UserEvent][google.cloud.retail.v2alpha.UserEvent] + // this page optimization is shown for. + // + // Each page has an associated event type - this will be the + // corresponding event type for the page that the page optimization + // model is used on. + // + // Supported types: + // + // * `add-to-cart`: Products being added to cart. + // * `detail-page-view`: Products detail page viewed. + // * `home-page-view`: Homepage viewed + // * `category-page-view`: Homepage viewed + // * `shopping-cart-page-view`: User viewing a shopping cart. + // + // `home-page-view` only allows models with type `recommended-for-you`. + // All other page_optimization_event_type allow all + // [Model.types][google.cloud.retail.v2alpha.Model.type]. + string page_optimization_event_type = 1 + [(google.api.field_behavior) = REQUIRED]; + + // Required. A list of panel configurations. + // + // Limit = 5. + repeated Panel panels = 2 [(google.api.field_behavior) = REQUIRED]; + + // Optional. How to restrict results across panels e.g. can the same + // [ServingConfig][google.cloud.retail.v2alpha.ServingConfig] be shown on + // multiple panels at once. + // + // If unspecified, default to `UNIQUE_MODEL_RESTRICTION`. + Restriction restriction = 3 [(google.api.field_behavior) = OPTIONAL]; + } + + // Represents an ordered combination of valid serving configs, which + // / may be used for PAGE_OPTIMIZATION recommendations. + message ServingConfigList { + // Optional. A set of valid serving configs that may be used for + // PAGE_OPTIMIZATION. + repeated string serving_config_ids = 1 + [(google.api.field_behavior) = OPTIONAL]; + } + + // The serving state of the model. + enum ServingState { + // Unspecified serving state. + SERVING_STATE_UNSPECIFIED = 0; + + // The model is not serving. + INACTIVE = 1; + + // The model is serving and can be queried. + ACTIVE = 2; + + // The model is trained on tuned hyperparameters, and can be + // queried. + TUNED = 3; + } + + // The training state of the model. + enum TrainingState { + // Unspecified training state. + TRAINING_STATE_UNSPECIFIED = 0; + + // The model training is paused. + PAUSED = 1; + + // The model is training. + TRAINING = 2; + } + + // Describes whether periodic tuning is enabled for this model + // or not. Periodic tuning is scheduled at most every three months. You can + // start a tuning process manually by using the ModelTune + // method, which starts a tuning process immediately and resets the quarterly + // schedule. Enabling or disabling periodic tuning does not affect any + // current tuning processes. + enum PeriodicTuningState { + // Unspecified default value - should never be explicitly set. + PERIODIC_TUNING_STATE_UNSPECIFIED = 0; + + // The model has periodic tuning disabled. Tuning + // can be reenabled by calling the EnableModelPeriodicTuning + // method or by calling the TuneModel method. + PERIODIC_TUNING_DISABLED = 1; + + // The model cannot be tuned with periodic tuning OR the + // TuneModel method. Hide the options in customer UI and + // reject any requests through the backend self serve API. + ALL_TUNING_DISABLED = 3; + + // The model has periodic tuning enabled. Tuning + // can be disabled by calling the DisableModelPeriodicTuning + // method. + PERIODIC_TUNING_ENABLED = 2; + } + + // Describes whether this model have sufficient training data + // to be continuously trained. + enum DataState { + // Unspecified default value - should never be explicitly set. + DATA_STATE_UNSPECIFIED = 0; + + // The model has sufficient training data. + DATA_OK = 1; + + // The model does not have sufficient training data. Error + // messages can be queried via Stackdriver. + DATA_ERROR = 2; + } + + // Training configuration specific to a + // [Model.type][google.cloud.retail.v2alpha.Model.type] - currently, only for + // page optimization. + oneof training_config { + // Optional. The page optimization config. + PageOptimizationConfig page_optimization_config = 17 + [(google.api.field_behavior) = OPTIONAL]; + } + + // Required. The fully qualified resource name of the model. + // + // Format: + // projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/models/{model_id} + // catalog_id has char limit of 50. + // recommendation_model_id has char limit of 40. + string name = 1 [(google.api.field_behavior) = REQUIRED]; + + // Required. The display name of the model. + // + // Should be human readable, used to display Recommendation Models in the + // Retail Cloud Cosole Dashboard. UTF-8 encoded string with limit of 1024 + // characters. + string display_name = 2 [(google.api.field_behavior) = REQUIRED]; + + // Optional. The training state that the model is in (e.g. + // TRAINING or PAUSED). + // + // Since part of the cost of running the service + // is frequency of training - this can be used to determine when to train + // model in order to control cost. If not specified: the default value for + // CreateModel method is TRAINING. the default value for + // UpdateModel method is to keep the state the same as before. + TrainingState training_state = 3 [(google.api.field_behavior) = OPTIONAL]; + + // Output only. The serving state of the model: ACTIVE, NOT_ACTIVE. + ServingState serving_state = 4 [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. Timestamp the Recommendation Model was created at. + google.protobuf.Timestamp create_time = 5 + [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. Timestamp the Recommendation Model was last updated. E.g. + // if a Recommendation Model was paused - this would be the time the pause was + // initiated. + google.protobuf.Timestamp update_time = 6 + [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Required. The type of model e.g. `home-page`. + // + // Currently supported values: `recommended-for-you`, `others-you-may-like`, + // `frequently-bought-together`, `page-optimization`, 'similar-items', + // 'buy-it-again', `recently-viewed`(readonly value). + string type = 7 [(google.api.field_behavior) = REQUIRED]; + + // Optional. The optimization objective e.g. `cvr`. + // + // Currently supported + // values: `ctr`, `cvr`, `revenue-per-order`. + // + // If not specified, we choose default based on model type. + // Default depends on type of recommendation: + // + // `recommended-for-you` => `ctr` + // + // `others-you-may-like` => `ctr` + // + // `frequently-bought-together` => `revenue_per_order` + string optimization_objective = 8 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. The state of periodic tuning. + // + // The period we use is 3 months - to do a + // one-off tune earlier use the TuneModel method. Default value + // is PERIODIC_TUNING_ENABLED. + PeriodicTuningState periodic_tuning_state = 11 + [(google.api.field_behavior) = OPTIONAL]; + + // Output only. The timestamp when the latest successful tune finished. + google.protobuf.Timestamp last_tune_time = 12 + [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. The tune operation associated with the model. + // + // Can be used to determine if there is an ongoing tune for this + // recommendation. Empty field implies no tune is goig on. + string tuning_operation = 15 [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. The state of data requirements for this model: DATA_OK and + // DATA_ERROR. + // + // Recommendation model cannot be trained if the data is in + // DATA_ERROR state. Recommendation model can have DATA_ERROR state even if + // serving state is ACTIVE: models were trained successfully before, but + // cannot be refreshed because model no longer has sufficient + // data for training. + DataState data_state = 16 [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Optional. If RECOMMENDATIONS_FILTERING_ENABLED, recommendation filtering by + // attributes is enabled for the model. + RecommendationsFilteringOption filtering_option = 18 + [(google.api.field_behavior) = OPTIONAL]; + + // Output only. The list of valid serving configs associated with the + // PageOptimizationConfig. + repeated ServingConfigList serving_config_lists = 19 + [(google.api.field_behavior) = OUTPUT_ONLY]; +} |