feat: add preview support for precision reranking via Ranking API. Includes free usage up to a specific quota for vector-search-2 users during the preview period

Google APIs · copybara-github · commit 4e923f988fbb · 2026-05-05T08:19:37.000-07:00
PiperOrigin-RevId: 910700163
diff --git a/google/cloud/vectorsearch/v1beta/data_object_search_service.proto b/google/cloud/vectorsearch/v1beta/data_object_search_service.proto
@@ -24,6 +24,7 @@ import "google/cloud/vectorsearch/v1beta/common.proto";
 import "google/cloud/vectorsearch/v1beta/data_object.proto";
 import "google/cloud/vectorsearch/v1beta/embedding_config.proto";
 import "google/protobuf/struct.proto";
+import "google/rpc/status.proto";
 
 option csharp_namespace = "Google.Cloud.VectorSearch.V1Beta";
 option go_package = "cloud.google.com/go/vectorsearch/apiv1beta/vectorsearchpb;vectorsearchpb";
@@ -325,6 +326,10 @@ message SearchResponseMetadata {
     // K-Nearest Neighbor (KNN) index engine.
     bool used_knn = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
   }
+
+  // Output only. Warnings or non-fatal errors that occurred during execution.
+  repeated google.rpc.Status warnings = 3
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // Response for a search request.
@@ -453,6 +458,13 @@ message Ranker {
     // Reciprocal Rank Fusion ranking.
     ReciprocalRankFusion rrf = 1;
   }
+
+  // The reranker to use for final ranking of the results combined by the
+  // ranker.
+  oneof reranker {
+    // Optional. Vertex AI ranking.
+    VertexRanker vertex_ranker = 2 [(google.api.field_behavior) = OPTIONAL];
+  }
 }
 
 // Defines the Reciprocal Rank Fusion (RRF) algorithm for result ranking.
@@ -461,6 +473,39 @@ message ReciprocalRankFusion {
   repeated double weights = 1 [(google.api.field_behavior) = REQUIRED];
 }
 
+// Defines a ranker using the Vertex AI ranking service.
+// See https://cloud.google.com/generative-ai-app-builder/docs/ranking for
+// details.
+message VertexRanker {
+  // The record spec for text search.
+  message TextRecordSpec {
+    // Required. The query against which the records are ranked and scored.
+    string query = 1 [(google.api.field_behavior) = REQUIRED];
+
+    // Optional. The template used to generate the record's title.
+    string title_template = 2 [(google.api.field_behavior) = OPTIONAL];
+
+    // Optional. The template used to generate the record's content.
+    string content_template = 3 [(google.api.field_behavior) = OPTIONAL];
+  }
+
+  // The record specification for ranking. At least one record spec must be
+  // set.
+  oneof record_spec {
+    // The record spec for text search.
+    TextRecordSpec text_record_spec = 6;
+  }
+
+  // Required. The model used for ranking documents. The list of available
+  // models is described in
+  // https://docs.cloud.google.com/generative-ai-app-builder/docs/ranking#models.
+  // Currently, only `semantic-ranker-fast@latest` is supported.
+  string model = 4 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The number of documents to be processed for ranking.
+  int32 top_n = 5 [(google.api.field_behavior) = REQUIRED];
+}
+
 // A response from a batch search operation.
 message BatchSearchDataObjectsResponse {
   // Output only. A list of search responses, one for each request in the batch.
