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.v2; 18 19import "google/api/field_behavior.proto"; 20import "google/api/resource.proto"; 21import "google/cloud/retail/v2/common.proto"; 22import "google/cloud/retail/v2/search_service.proto"; 23 24option csharp_namespace = "Google.Cloud.Retail.V2"; 25option go_package = "cloud.google.com/go/retail/apiv2/retailpb;retailpb"; 26option java_multiple_files = true; 27option java_outer_classname = "ServingConfigProto"; 28option java_package = "com.google.cloud.retail.v2"; 29option objc_class_prefix = "RETAIL"; 30option php_namespace = "Google\\Cloud\\Retail\\V2"; 31option ruby_package = "Google::Cloud::Retail::V2"; 32 33// Configures metadata that is used to generate serving time results (e.g. 34// search results or recommendation predictions). 35message ServingConfig { 36 option (google.api.resource) = { 37 type: "retail.googleapis.com/ServingConfig" 38 pattern: "projects/{project}/locations/{location}/catalogs/{catalog}/servingConfigs/{serving_config}" 39 }; 40 41 // What type of diversity - data or rule based. 42 enum DiversityType { 43 // Default value. 44 DIVERSITY_TYPE_UNSPECIFIED = 0; 45 46 // Rule based diversity. 47 RULE_BASED_DIVERSITY = 2; 48 49 // Data driven diversity. 50 DATA_DRIVEN_DIVERSITY = 3; 51 } 52 53 // Immutable. Fully qualified name 54 // `projects/*/locations/global/catalogs/*/servingConfig/*` 55 string name = 1 [(google.api.field_behavior) = IMMUTABLE]; 56 57 // Required. The human readable serving config display name. Used in Retail 58 // UI. 59 // 60 // This field must be a UTF-8 encoded string with a length limit of 128 61 // characters. Otherwise, an INVALID_ARGUMENT error is returned. 62 string display_name = 2 [(google.api.field_behavior) = REQUIRED]; 63 64 // The id of the model in the same [Catalog][google.cloud.retail.v2.Catalog] 65 // to use at serving time. Currently only RecommendationModels are supported: 66 // https://cloud.google.com/retail/recommendations-ai/docs/create-models 67 // Can be changed but only to a compatible model (e.g. 68 // others-you-may-like CTR to others-you-may-like CVR). 69 // 70 // Required when 71 // [solution_types][google.cloud.retail.v2.ServingConfig.solution_types] is 72 // [SOLUTION_TYPE_RECOMMENDATION][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_RECOMMENDATION]. 73 string model_id = 3; 74 75 // How much price ranking we want in serving results. 76 // Price reranking causes product items with a similar 77 // recommendation probability to be ordered by price, with the 78 // highest-priced items first. This setting could result in a decrease in 79 // click-through and conversion rates. 80 // Allowed values are: 81 // 82 // * `no-price-reranking` 83 // * `low-price-reranking` 84 // * `medium-price-reranking` 85 // * `high-price-reranking` 86 // 87 // If not specified, we choose default based on model type. Default value: 88 // `no-price-reranking`. 89 // 90 // Can only be set if 91 // [solution_types][google.cloud.retail.v2.ServingConfig.solution_types] is 92 // [SOLUTION_TYPE_RECOMMENDATION][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_RECOMMENDATION]. 93 string price_reranking_level = 4; 94 95 // Facet specifications for faceted search. If empty, no facets are returned. 96 // The ids refer to the ids of [Control][google.cloud.retail.v2.Control] 97 // resources with only the Facet control set. These controls are assumed to be 98 // in the same [Catalog][google.cloud.retail.v2.Catalog] as the 99 // [ServingConfig][google.cloud.retail.v2.ServingConfig]. 100 // A maximum of 100 values are allowed. Otherwise, an INVALID_ARGUMENT error 101 // is returned. 102 // 103 // Can only be set if 104 // [solution_types][google.cloud.retail.v2.ServingConfig.solution_types] is 105 // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH]. 106 repeated string facet_control_ids = 5; 107 108 // The specification for dynamically generated facets. Notice that only 109 // textual facets can be dynamically generated. 110 // 111 // Can only be set if 112 // [solution_types][google.cloud.retail.v2.ServingConfig.solution_types] is 113 // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH]. 114 SearchRequest.DynamicFacetSpec dynamic_facet_spec = 6; 115 116 // Condition boost specifications. If a product matches multiple conditions 117 // in the specifications, boost scores from these specifications are all 118 // applied and combined in a non-linear way. Maximum number of 119 // specifications is 100. 120 // 121 // Notice that if both 122 // [ServingConfig.boost_control_ids][google.cloud.retail.v2.ServingConfig.boost_control_ids] 123 // and 124 // [SearchRequest.boost_spec][google.cloud.retail.v2.SearchRequest.boost_spec] 125 // are set, the boost conditions from both places are evaluated. If a search 126 // request matches multiple boost conditions, the final boost score is equal 127 // to the sum of the boost scores from all matched boost conditions. 128 // 129 // Can only be set if 130 // [solution_types][google.cloud.retail.v2.ServingConfig.solution_types] is 131 // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH]. 132 repeated string boost_control_ids = 7; 133 134 // Condition filter specifications. If a product matches multiple conditions 135 // in the specifications, filters from these specifications are all 136 // applied and combined via the AND operator. Maximum number of 137 // specifications is 100. 138 // 139 // Can only be set if 140 // [solution_types][google.cloud.retail.v2.ServingConfig.solution_types] is 141 // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH]. 142 repeated string filter_control_ids = 9; 143 144 // Condition redirect specifications. Only the first triggered redirect action 145 // is applied, even if multiple apply. Maximum number of specifications is 146 // 1000. 147 // 148 // Can only be set if 149 // [solution_types][google.cloud.retail.v2.ServingConfig.solution_types] is 150 // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH]. 151 repeated string redirect_control_ids = 10; 152 153 // Condition synonyms specifications. If multiple syonyms conditions match, 154 // all matching synonyms control in the list will execute. Order of controls 155 // in the list will not matter. Maximum number of specifications is 156 // 100. 157 // 158 // Can only be set if 159 // [solution_types][google.cloud.retail.v2.ServingConfig.solution_types] is 160 // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH]. 161 repeated string twoway_synonyms_control_ids = 18; 162 163 // Condition oneway synonyms specifications. If multiple oneway synonyms 164 // conditions match, all matching oneway synonyms controls in the list will 165 // execute. Order of controls in the list will not matter. Maximum number of 166 // specifications is 100. 167 // 168 // Can only be set if 169 // [solution_types][google.cloud.retail.v2.ServingConfig.solution_types] is 170 // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH]. 171 repeated string oneway_synonyms_control_ids = 12; 172 173 // Condition do not associate specifications. If multiple do not associate 174 // conditions match, all matching do not associate controls in the list will 175 // execute. 176 // - Order does not matter. 177 // - Maximum number of specifications is 100. 178 // 179 // Can only be set if 180 // [solution_types][google.cloud.retail.v2.ServingConfig.solution_types] is 181 // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH]. 182 repeated string do_not_associate_control_ids = 13; 183 184 // Condition replacement specifications. 185 // - Applied according to the order in the list. 186 // - A previously replaced term can not be re-replaced. 187 // - Maximum number of specifications is 100. 188 // 189 // Can only be set if 190 // [solution_types][google.cloud.retail.v2.ServingConfig.solution_types] is 191 // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH]. 192 repeated string replacement_control_ids = 14; 193 194 // Condition ignore specifications. If multiple ignore 195 // conditions match, all matching ignore controls in the list will 196 // execute. 197 // - Order does not matter. 198 // - Maximum number of specifications is 100. 199 // 200 // Can only be set if 201 // [solution_types][google.cloud.retail.v2.ServingConfig.solution_types] is 202 // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH]. 203 repeated string ignore_control_ids = 15; 204 205 // How much diversity to use in recommendation model results e.g. 206 // `medium-diversity` or `high-diversity`. Currently supported values: 207 // 208 // * `no-diversity` 209 // * `low-diversity` 210 // * `medium-diversity` 211 // * `high-diversity` 212 // * `auto-diversity` 213 // 214 // If not specified, we choose default based on recommendation model 215 // type. Default value: `no-diversity`. 216 // 217 // Can only be set if 218 // [solution_types][google.cloud.retail.v2.ServingConfig.solution_types] is 219 // [SOLUTION_TYPE_RECOMMENDATION][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_RECOMMENDATION]. 220 string diversity_level = 8; 221 222 // What kind of diversity to use - data driven or rule based. If unset, the 223 // server behavior defaults to 224 // [RULE_BASED_DIVERSITY][google.cloud.retail.v2.ServingConfig.DiversityType.RULE_BASED_DIVERSITY]. 225 DiversityType diversity_type = 20; 226 227 // Whether to add additional category filters on the `similar-items` model. 228 // If not specified, we enable it by default. 229 // Allowed values are: 230 // 231 // * `no-category-match`: No additional filtering of original results from 232 // the model and the customer's filters. 233 // * `relaxed-category-match`: Only keep results with categories that match 234 // at least one item categories in the PredictRequests's context item. 235 // * If customer also sends filters in the PredictRequest, then the results 236 // will satisfy both conditions (user given and category match). 237 // 238 // Can only be set if 239 // [solution_types][google.cloud.retail.v2.ServingConfig.solution_types] is 240 // [SOLUTION_TYPE_RECOMMENDATION][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_RECOMMENDATION]. 241 string enable_category_filter_level = 16; 242 243 // The specification for personalization spec. 244 // 245 // Can only be set if 246 // [solution_types][google.cloud.retail.v2.ServingConfig.solution_types] is 247 // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH]. 248 // 249 // Notice that if both 250 // [ServingConfig.personalization_spec][google.cloud.retail.v2.ServingConfig.personalization_spec] 251 // and 252 // [SearchRequest.personalization_spec][google.cloud.retail.v2.SearchRequest.personalization_spec] 253 // are set. 254 // [SearchRequest.personalization_spec][google.cloud.retail.v2.SearchRequest.personalization_spec] 255 // will override 256 // [ServingConfig.personalization_spec][google.cloud.retail.v2.ServingConfig.personalization_spec]. 257 SearchRequest.PersonalizationSpec personalization_spec = 21; 258 259 // Required. Immutable. Specifies the solution types that a serving config can 260 // be associated with. Currently we support setting only one type of solution. 261 repeated SolutionType solution_types = 19 [ 262 (google.api.field_behavior) = REQUIRED, 263 (google.api.field_behavior) = IMMUTABLE 264 ]; 265} 266