1// Copyright 2022 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.discoveryengine.v1beta; 18 19import "google/api/field_behavior.proto"; 20import "google/api/resource.proto"; 21import "google/cloud/discoveryengine/v1beta/common.proto"; 22import "google/cloud/discoveryengine/v1beta/search_service.proto"; 23import "google/protobuf/timestamp.proto"; 24 25option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1Beta"; 26option go_package = "cloud.google.com/go/discoveryengine/apiv1beta/discoveryenginepb;discoveryenginepb"; 27option java_multiple_files = true; 28option java_outer_classname = "ServingConfigProto"; 29option java_package = "com.google.cloud.discoveryengine.v1beta"; 30option objc_class_prefix = "DISCOVERYENGINE"; 31option php_namespace = "Google\\Cloud\\DiscoveryEngine\\V1beta"; 32option ruby_package = "Google::Cloud::DiscoveryEngine::V1beta"; 33 34// Configures metadata that is used to generate serving time results (e.g. 35// search results or recommendation predictions). 36// The ServingConfig is passed in the search and predict request and generates 37// results. 38message ServingConfig { 39 option (google.api.resource) = { 40 type: "discoveryengine.googleapis.com/ServingConfig" 41 pattern: "projects/{project}/locations/{location}/dataStores/{data_store}/servingConfigs/{serving_config}" 42 pattern: "projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}/servingConfigs/{serving_config}" 43 pattern: "projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{serving_config}" 44 }; 45 46 // Specifies the configurations needed for Media Discovery. Currently we 47 // support: 48 // 49 // * `demote_content_watched`: Threshold for watched content demotion. 50 // Customers can specify if using watched content demotion or use viewed 51 // detail page. Using the content watched demotion, customers need to specify 52 // the watched minutes or percentage exceeds the threshold, the content will 53 // be demoted in the recommendation result. 54 // * `promote_fresh_content`: cutoff days for fresh content promotion. 55 // Customers can specify if using content freshness promotion. If the content 56 // was published within the cutoff days, the content will be promoted in the 57 // recommendation result. 58 // Can only be set if 59 // [SolutionType][google.cloud.discoveryengine.v1beta.SolutionType] is 60 // [SOLUTION_TYPE_RECOMMENDATION][google.cloud.discoveryengine.v1beta.SolutionType.SOLUTION_TYPE_RECOMMENDATION]. 61 message MediaConfig { 62 // Specify the threshold for demoting watched content, the threshold can be 63 // either percentage or minutes value. 64 // This must be set for `media-complete` event type. 65 oneof demote_content_watched { 66 // Specifies the content watched percentage threshold for demotion. 67 // Threshold value must be between [0, 1.0] inclusive. 68 float content_watched_percentage_threshold = 2; 69 70 // Specifies the content watched minutes threshold for demotion. 71 float content_watched_seconds_threshold = 5; 72 } 73 74 // Specifies the event type used for demoting recommendation result. 75 // Currently supported values: 76 // 77 // * `view-item`: Item viewed. 78 // * `media-play`: Start/resume watching a video, playing a song, etc. 79 // * `media-complete`: Finished or stopped midway through a video, song, 80 // etc. 81 // 82 // If unset, watch history demotion will not be applied. Content freshness 83 // demotion will still be applied. 84 string demotion_event_type = 1; 85 86 // Specifies the content freshness used for recommendation result. 87 // Contents will be demoted if contents were published for more than content 88 // freshness cutoff days. 89 int32 content_freshness_cutoff_days = 4; 90 } 91 92 // Specifies the configurations needed for Generic Discovery.Currently we 93 // support: 94 // 95 // * `content_search_spec`: configuration for generic content search. 96 message GenericConfig { 97 // Specifies the expected behavior of content search. 98 // Only valid for content-search enabled data store. 99 SearchRequest.ContentSearchSpec content_search_spec = 1; 100 } 101 102 // Industry vertical specific config. 103 oneof vertical_config { 104 // The MediaConfig of the serving configuration. 105 MediaConfig media_config = 7; 106 107 // The GenericConfig of the serving configuration. 108 GenericConfig generic_config = 10; 109 } 110 111 // Immutable. Fully qualified name 112 // `projects/{project}/locations/{location}/collections/{collection_id}/engines/{engine_id}/servingConfigs/{serving_config_id}` 113 string name = 1 [(google.api.field_behavior) = IMMUTABLE]; 114 115 // Required. The human readable serving config display name. Used in Discovery 116 // UI. 117 // 118 // This field must be a UTF-8 encoded string with a length limit of 128 119 // characters. Otherwise, an INVALID_ARGUMENT error is returned. 120 string display_name = 2 [(google.api.field_behavior) = REQUIRED]; 121 122 // Required. Immutable. Specifies the solution type that a serving config can 123 // be associated with. 124 SolutionType solution_type = 3 [ 125 (google.api.field_behavior) = REQUIRED, 126 (google.api.field_behavior) = IMMUTABLE 127 ]; 128 129 // The id of the model to use at serving time. 130 // Currently only RecommendationModels are supported. 131 // Can be changed but only to a compatible model (e.g. 132 // others-you-may-like CTR to others-you-may-like CVR). 133 // 134 // Required when 135 // [SolutionType][google.cloud.discoveryengine.v1beta.SolutionType] is 136 // [SOLUTION_TYPE_RECOMMENDATION][google.cloud.discoveryengine.v1beta.SolutionType.SOLUTION_TYPE_RECOMMENDATION]. 137 string model_id = 4; 138 139 // How much diversity to use in recommendation model results e.g. 140 // `medium-diversity` or `high-diversity`. Currently supported values: 141 // 142 // * `no-diversity` 143 // * `low-diversity` 144 // * `medium-diversity` 145 // * `high-diversity` 146 // * `auto-diversity` 147 // 148 // If not specified, we choose default based on recommendation model 149 // type. Default value: `no-diversity`. 150 // 151 // Can only be set if 152 // [SolutionType][google.cloud.discoveryengine.v1beta.SolutionType] is 153 // [SOLUTION_TYPE_RECOMMENDATION][google.cloud.discoveryengine.v1beta.SolutionType.SOLUTION_TYPE_RECOMMENDATION]. 154 string diversity_level = 5; 155 156 // Bring your own embedding config. The config is used for search semantic 157 // retrieval. The retrieval is based on the dot product of 158 // [SearchRequest.EmbeddingSpec.EmbeddingVector.vector][google.cloud.discoveryengine.v1beta.SearchRequest.EmbeddingSpec.EmbeddingVector.vector] 159 // and the document embeddings that are provided by this EmbeddingConfig. If 160 // [SearchRequest.EmbeddingSpec.EmbeddingVector.vector][google.cloud.discoveryengine.v1beta.SearchRequest.EmbeddingSpec.EmbeddingVector.vector] 161 // is provided, it overrides this 162 // [ServingConfig.embedding_config][google.cloud.discoveryengine.v1beta.ServingConfig.embedding_config]. 163 EmbeddingConfig embedding_config = 20; 164 165 // The ranking expression controls the customized ranking on retrieval 166 // documents. To leverage this, document embedding is required. The ranking 167 // expression setting in ServingConfig applies to all search requests served 168 // by the serving config. However, if 169 // [SearchRequest.ranking_expression][google.cloud.discoveryengine.v1beta.SearchRequest.ranking_expression] 170 // is specified, it overrides the ServingConfig ranking expression. 171 // 172 // The ranking expression is a single function or multiple functions that are 173 // joined by "+". 174 // * ranking_expression = function, { " + ", function }; 175 // Supported functions: 176 // * double * relevance_score 177 // * double * dotProduct(embedding_field_path) 178 // Function variables: 179 // relevance_score: pre-defined keywords, used for measure relevance between 180 // query and document. 181 // embedding_field_path: the document embedding field 182 // used with query embedding vector. 183 // dotProduct: embedding function between embedding_field_path and query 184 // embedding vector. 185 // 186 // Example ranking expression: 187 // If document has an embedding field doc_embedding, the ranking expression 188 // could be 0.5 * relevance_score + 0.3 * dotProduct(doc_embedding). 189 string ranking_expression = 21; 190 191 // Output only. ServingConfig created timestamp. 192 google.protobuf.Timestamp create_time = 8 193 [(google.api.field_behavior) = OUTPUT_ONLY]; 194 195 // Output only. ServingConfig updated timestamp. 196 google.protobuf.Timestamp update_time = 9 197 [(google.api.field_behavior) = OUTPUT_ONLY]; 198 199 // Filter controls to use in serving path. 200 // All triggered filter controls will be applied. 201 // Filter controls must be in the same data store as the serving config. 202 // Maximum of 20 filter controls. 203 repeated string filter_control_ids = 11; 204 205 // Boost controls to use in serving path. 206 // All triggered boost controls will be applied. 207 // Boost controls must be in the same data store as the serving config. 208 // Maximum of 20 boost controls. 209 repeated string boost_control_ids = 12; 210 211 // IDs of the redirect controls. Only the first triggered redirect 212 // action is applied, even if multiple apply. Maximum number of 213 // specifications is 100. 214 // 215 // Can only be set if 216 // [SolutionType][google.cloud.discoveryengine.v1beta.SolutionType] is 217 // [SOLUTION_TYPE_SEARCH][google.cloud.discoveryengine.v1beta.SolutionType.SOLUTION_TYPE_SEARCH]. 218 repeated string redirect_control_ids = 14; 219 220 // Condition synonyms specifications. If multiple synonyms conditions 221 // match, all matching synonyms controls in the list will execute. 222 // Maximum number of specifications is 100. 223 // 224 // Can only be set if 225 // [SolutionType][google.cloud.discoveryengine.v1beta.SolutionType] is 226 // [SOLUTION_TYPE_SEARCH][google.cloud.discoveryengine.v1beta.SolutionType.SOLUTION_TYPE_SEARCH]. 227 repeated string synonyms_control_ids = 15; 228 229 // Condition oneway synonyms specifications. If multiple oneway synonyms 230 // conditions match, all matching oneway synonyms controls in the list 231 // will execute. Maximum number of specifications is 100. 232 // 233 // Can only be set if 234 // [SolutionType][google.cloud.discoveryengine.v1beta.SolutionType] is 235 // [SOLUTION_TYPE_SEARCH][google.cloud.discoveryengine.v1beta.SolutionType.SOLUTION_TYPE_SEARCH]. 236 repeated string oneway_synonyms_control_ids = 16; 237 238 // Condition do not associate specifications. If multiple do not 239 // associate conditions match, all matching do not associate controls in 240 // the list will execute. 241 // Order does not matter. 242 // Maximum number of specifications is 100. 243 // 244 // Can only be set if 245 // [SolutionType][google.cloud.discoveryengine.v1beta.SolutionType] is 246 // [SOLUTION_TYPE_SEARCH][google.cloud.discoveryengine.v1beta.SolutionType.SOLUTION_TYPE_SEARCH]. 247 repeated string dissociate_control_ids = 17; 248 249 // Condition replacement specifications. 250 // Applied according to the order in the list. 251 // A previously replaced term can not be re-replaced. 252 // Maximum number of specifications is 100. 253 // 254 // Can only be set if 255 // [SolutionType][google.cloud.discoveryengine.v1beta.SolutionType] is 256 // [SOLUTION_TYPE_SEARCH][google.cloud.discoveryengine.v1beta.SolutionType.SOLUTION_TYPE_SEARCH]. 257 repeated string replacement_control_ids = 18; 258 259 // Condition ignore specifications. If multiple ignore 260 // conditions match, all matching ignore controls in the list will 261 // execute. 262 // Order does not matter. 263 // Maximum number of specifications is 100. 264 repeated string ignore_control_ids = 19; 265} 266