google.cloud.retail.v2alpha.model.proto Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of proto-google-cloud-retail-v2alpha Show documentation
Show all versions of proto-google-cloud-retail-v2alpha Show documentation
Proto library for google-cloud-retail
// Copyright 2024 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 = "cloud.google.com/go/retail/apiv2alpha/retailpb;retailpb";
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
// configs 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. For example, 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.
repeated Candidate candidates = 2
[(google.api.field_behavior) = REQUIRED];
// Required. The default candidate. If the model fails at serving time,
// we 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`:
//
// * (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)
//
// `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`: pdp_ctr, pdp_cvr, home_page_ctr_no_diversity
//
//
// `Panel2 candidates`: home_page_ctr_no_diversity,
// home_page_ctr_diversity_low,
// pdp_cvr_no_diversity
//
// `Restriction` = `UNIQUE_SERVING_CONFIG_RESTRICTION`
//
// `Valid combinations`:
//
// * (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)
//
// `Invalid combinations`:
//
// * (home_page_ctr_no_diversity, home_page_ctr_no_diversity)
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`: pdp_ctr, pdp_cvr, home_page_ctr_no_diversity
//
//
// `Panel2 candidates`: home_page_ctr_no_diversity,
// home_page_ctr_diversity_low,
// pdp_cvr_no_diversity
//
// `Restriction` = `UNIQUE_MODEL_RESTRICTION`
//
// `Valid combinations`:
//
// * (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)
//
// `Invalid combinations`:
//
// * (home_page_ctr_no_diversity, home_page_ctr_no_diversity)
// * (pdp_cvr, pdp_cvr_no_diversity)
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`: pdp_ctr, pdp_cvr, home_page_ctr_no_diversity
//
//
// `Panel2 candidates`: home_page_ctr_no_diversity,
// home_page_ctr_diversity_low,
// pdp_cvr_no_diversity
//
// `Restriction` = `UNIQUE_MODEL_RESTRICTION`
//
// `Valid combinations`:
//
// * (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)
//
// `Invalid combinations`:
//
// * (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)
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
// can 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];
}
// Additional configs for the frequently-bought-together model type.
message FrequentlyBoughtTogetherFeaturesConfig {
// Optional. Specifies the context of the model when it is used in predict
// requests. Can only be set for the `frequently-bought-together` type. If
// it isn't specified, it defaults to
// [MULTIPLE_CONTEXT_PRODUCTS][google.cloud.retail.v2alpha.Model.ContextProductsType.MULTIPLE_CONTEXT_PRODUCTS].
ContextProductsType context_products_type = 2
[(google.api.field_behavior) = OPTIONAL];
}
// Additional model features config.
message ModelFeaturesConfig {
// Config that turns on usage of llm embeddings as features to the model.
// Embeddings leverage unstructured text fields like description and title.
message LlmEmbeddingConfig {
// Optional. The LLM embedding version to use.
// Currently only `v0` is supported. If not specified, feature will
// not be turned on.
string llm_embedding_version = 1 [(google.api.field_behavior) = OPTIONAL];
}
oneof type_dedicated_config {
// Additional configs for frequently-bought-together models.
FrequentlyBoughtTogetherFeaturesConfig frequently_bought_together_config =
1;
}
// Optional. LLM embedding config to use for this model.
LlmEmbeddingConfig llm_embedding_config = 2
[(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 `TuneModel`
// 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;
}
// Use single or multiple context products for recommendations.
enum ContextProductsType {
// Unspecified default value, should never be explicitly set.
// Defaults to
// [MULTIPLE_CONTEXT_PRODUCTS][google.cloud.retail.v2alpha.Model.ContextProductsType.MULTIPLE_CONTEXT_PRODUCTS].
CONTEXT_PRODUCTS_TYPE_UNSPECIFIED = 0;
// Use only a single product as context for the recommendation. Typically
// used on pages like add-to-cart or product details.
SINGLE_CONTEXT_PRODUCT = 1;
// Use one or multiple products as context for the recommendation. Typically
// used on shopping cart pages.
MULTIPLE_CONTEXT_PRODUCTS = 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 Console 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`, `on-sale-items`, and `recently-viewed`(readonly value).
//
//
// This field together with
// [optimization_objective][google.cloud.retail.v2alpha.Model.optimization_objective]
// describe model metadata to use to control model training and serving.
// See https://cloud.google.com/retail/docs/models
// for more details on what the model metadata control and which combination
// of parameters are valid. For invalid combinations of parameters (e.g. type
// = `frequently-bought-together` and optimization_objective = `ctr`), you
// receive an error 400 if you try to create/update a recommendation with
// this set of knobs.
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`
//
// This field together with
// [optimization_objective][google.cloud.retail.v2alpha.Model.type]
// describe model metadata to use to control model training and serving.
// See https://cloud.google.com/retail/docs/models
// for more details on what the model metadata control and which combination
// of parameters are valid. For invalid combinations of parameters (e.g. type
// = `frequently-bought-together` and optimization_objective = `ctr`), you
// receive an error 400 if you try to create/update a recommendation with
// this set of knobs.
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];
// Optional. Additional model features config.
ModelFeaturesConfig model_features_config = 22
[(google.api.field_behavior) = OPTIONAL];
}
© 2015 - 2024 Weber Informatics LLC | Privacy Policy