xref: /aosp_15_r20/external/googleapis/google/cloud/retail/v2beta/serving_config.proto (revision d5c09012810ac0c9f33fe448fb6da8260d444cc9)
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/cloud/retail/v2beta/search_service.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 = "ServingConfigProto";
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// 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
65  // [Catalog][google.cloud.retail.v2beta.Catalog] to use at serving time.
66  // Currently only RecommendationModels are supported:
67  // https://cloud.google.com/retail/recommendations-ai/docs/create-models
68  // Can be changed but only to a compatible model (e.g.
69  // others-you-may-like CTR to others-you-may-like CVR).
70  //
71  // Required when
72  // [solution_types][google.cloud.retail.v2beta.ServingConfig.solution_types]
73  // is
74  // [SOLUTION_TYPE_RECOMMENDATION][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_RECOMMENDATION].
75  string model_id = 3;
76
77  // How much price ranking we want in serving results.
78  // Price reranking causes product items with a similar
79  // recommendation probability to be ordered by price, with the
80  // highest-priced items first. This setting could result in a decrease in
81  // click-through and conversion rates.
82  //  Allowed values are:
83  //
84  // * `no-price-reranking`
85  // * `low-price-reranking`
86  // * `medium-price-reranking`
87  // * `high-price-reranking`
88  //
89  // If not specified, we choose default based on model type. Default value:
90  // `no-price-reranking`.
91  //
92  // Can only be set if
93  // [solution_types][google.cloud.retail.v2beta.ServingConfig.solution_types]
94  // is
95  // [SOLUTION_TYPE_RECOMMENDATION][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_RECOMMENDATION].
96  string price_reranking_level = 4;
97
98  // Facet specifications for faceted search. If empty, no facets are returned.
99  // The ids refer to the ids of [Control][google.cloud.retail.v2beta.Control]
100  // resources with only the Facet control set. These controls are assumed to be
101  // in the same [Catalog][google.cloud.retail.v2beta.Catalog] as the
102  // [ServingConfig][google.cloud.retail.v2beta.ServingConfig].
103  // A maximum of 100 values are allowed. Otherwise, an INVALID_ARGUMENT error
104  // is returned.
105  //
106  // Can only be set if
107  // [solution_types][google.cloud.retail.v2beta.ServingConfig.solution_types]
108  // is
109  // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH].
110  repeated string facet_control_ids = 5;
111
112  // The specification for dynamically generated facets. Notice that only
113  // textual facets can be dynamically generated.
114  //
115  // Can only be set if
116  // [solution_types][google.cloud.retail.v2beta.ServingConfig.solution_types]
117  // is
118  // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH].
119  SearchRequest.DynamicFacetSpec dynamic_facet_spec = 6;
120
121  // Condition boost specifications. If a product matches multiple conditions
122  // in the specifications, boost scores from these specifications are all
123  // applied and combined in a non-linear way. Maximum number of
124  // specifications is 100.
125  //
126  // Notice that if both
127  // [ServingConfig.boost_control_ids][google.cloud.retail.v2beta.ServingConfig.boost_control_ids]
128  // and
129  // [SearchRequest.boost_spec][google.cloud.retail.v2beta.SearchRequest.boost_spec]
130  // are set, the boost conditions from both places are evaluated. If a search
131  // request matches multiple boost conditions, the final boost score is equal
132  // to the sum of the boost scores from all matched boost conditions.
133  //
134  // Can only be set if
135  // [solution_types][google.cloud.retail.v2beta.ServingConfig.solution_types]
136  // is
137  // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH].
138  repeated string boost_control_ids = 7;
139
140  // Condition filter specifications. If a product matches multiple conditions
141  // in the specifications, filters from these specifications are all
142  // applied and combined via the AND operator. Maximum number of
143  // specifications is 100.
144  //
145  // Can only be set if
146  // [solution_types][google.cloud.retail.v2beta.ServingConfig.solution_types]
147  // is
148  // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH].
149  repeated string filter_control_ids = 9;
150
151  // Condition redirect specifications. Only the first triggered redirect action
152  // is applied, even if multiple apply. Maximum number of specifications is
153  // 1000.
154  //
155  // Can only be set if
156  // [solution_types][google.cloud.retail.v2beta.ServingConfig.solution_types]
157  // is
158  // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH].
159  repeated string redirect_control_ids = 10;
160
161  // Condition synonyms specifications. If multiple syonyms conditions match,
162  // all matching synonyms control in the list will execute. Order of controls
163  // in the list will not matter. Maximum number of specifications is
164  // 100.
165  //
166  // Can only be set if
167  // [solution_types][google.cloud.retail.v2beta.ServingConfig.solution_types]
168  // is
169  // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH].
170  repeated string twoway_synonyms_control_ids = 18;
171
172  // Condition oneway synonyms specifications. If multiple oneway synonyms
173  // conditions match, all matching oneway synonyms controls in the list will
174  // execute. Order of controls in the list will not matter. Maximum number of
175  // specifications is 100.
176  //
177  // Can only be set if
178  // [solution_types][google.cloud.retail.v2beta.ServingConfig.solution_types]
179  // is
180  // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH].
181  repeated string oneway_synonyms_control_ids = 12;
182
183  // Condition do not associate specifications. If multiple do not associate
184  // conditions match, all matching do not associate controls in the list will
185  // execute.
186  // - Order does not matter.
187  // - Maximum number of specifications is 100.
188  //
189  // Can only be set if
190  // [solution_types][google.cloud.retail.v2beta.ServingConfig.solution_types]
191  // is
192  // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH].
193  repeated string do_not_associate_control_ids = 13;
194
195  // Condition replacement specifications.
196  // - Applied according to the order in the list.
197  // - A previously replaced term can not be re-replaced.
198  // - Maximum number of specifications is 100.
199  //
200  // Can only be set if
201  // [solution_types][google.cloud.retail.v2beta.ServingConfig.solution_types]
202  // is
203  // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH].
204  repeated string replacement_control_ids = 14;
205
206  // Condition ignore specifications. If multiple ignore
207  // conditions match, all matching ignore controls in the list will
208  // execute.
209  // - Order does not matter.
210  // - Maximum number of specifications is 100.
211  //
212  // Can only be set if
213  // [solution_types][google.cloud.retail.v2beta.ServingConfig.solution_types]
214  // is
215  // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH].
216  repeated string ignore_control_ids = 15;
217
218  // How much diversity to use in recommendation model results e.g.
219  // `medium-diversity` or `high-diversity`. Currently supported values:
220  //
221  // * `no-diversity`
222  // * `low-diversity`
223  // * `medium-diversity`
224  // * `high-diversity`
225  // * `auto-diversity`
226  //
227  // If not specified, we choose default based on recommendation model
228  // type. Default value: `no-diversity`.
229  //
230  // Can only be set if
231  // [solution_types][google.cloud.retail.v2beta.ServingConfig.solution_types]
232  // is
233  // [SOLUTION_TYPE_RECOMMENDATION][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_RECOMMENDATION].
234  string diversity_level = 8;
235
236  // What kind of diversity to use - data driven or rule based. If unset, the
237  // server behavior defaults to
238  // [RULE_BASED_DIVERSITY][google.cloud.retail.v2beta.ServingConfig.DiversityType.RULE_BASED_DIVERSITY].
239  DiversityType diversity_type = 20;
240
241  // Whether to add additional category filters on the `similar-items` model.
242  // If not specified, we enable it by default.
243  //  Allowed values are:
244  //
245  // * `no-category-match`: No additional filtering of original results from
246  //   the model and the customer's filters.
247  // * `relaxed-category-match`: Only keep results with categories that match
248  //   at least one item categories in the PredictRequests's context item.
249  //   * If customer also sends filters in the PredictRequest, then the results
250  //   will satisfy both conditions (user given and category match).
251  //
252  // Can only be set if
253  // [solution_types][google.cloud.retail.v2beta.ServingConfig.solution_types]
254  // is
255  // [SOLUTION_TYPE_RECOMMENDATION][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_RECOMMENDATION].
256  string enable_category_filter_level = 16;
257
258  // The specification for personalization spec.
259  //
260  // Can only be set if
261  // [solution_types][google.cloud.retail.v2beta.ServingConfig.solution_types]
262  // is
263  // [SOLUTION_TYPE_SEARCH][google.cloud.retail.v2main.SolutionType.SOLUTION_TYPE_SEARCH].
264  //
265  // Notice that if both
266  // [ServingConfig.personalization_spec][google.cloud.retail.v2beta.ServingConfig.personalization_spec]
267  // and
268  // [SearchRequest.personalization_spec][google.cloud.retail.v2beta.SearchRequest.personalization_spec]
269  // are set.
270  // [SearchRequest.personalization_spec][google.cloud.retail.v2beta.SearchRequest.personalization_spec]
271  // will override
272  // [ServingConfig.personalization_spec][google.cloud.retail.v2beta.ServingConfig.personalization_spec].
273  SearchRequest.PersonalizationSpec personalization_spec = 21;
274
275  // Required. Immutable. Specifies the solution types that a serving config can
276  // be associated with. Currently we support setting only one type of solution.
277  repeated SolutionType solution_types = 19 [
278    (google.api.field_behavior) = REQUIRED,
279    (google.api.field_behavior) = IMMUTABLE
280  ];
281}
282