Reranking search results with VertexRanker

Agent Retrieval (formerly Vector Search 2.0) provides VertexRanker for semantic reranking, which is powered by the Ranking API.

After Agent Retrieval retrieves and fuses candidate results (using Reciprocal Rank Fusion (RRF)), VertexRanker rescores the merged candidates against your natural-language query using a dedicated semantic model. This improves the relevance of the top-k results, especially for queries where search alone misses nuance. Reranking happens server-side with calls to BatchSearchDataObjects. No additional client-side wiring or additional round trips are needed.

VertexRanker

VertexRanker is configured as the reranker for the combine.ranker field of the BatchSearchDataObjectsRequest object. You must configure a primary ranker (only RRF is supported). The reranker runs after the RRF fusion step and replaces the output with the semantically rescored list.

The following table lists ranker configuration fields.

The following example demonstrates the body of a request.

{
  "searches": [
    { "semantic_search": { "search_text": "running shoes", "search_field": "embedding", "task_type": "RETRIEVAL_QUERY", "top_k": 50 } },
    { "text_search":     { "search_text": "running shoes", "data_field_names": ["title"], "top_k": 50 } }
  ],
  "combine": {
    "top_k": 10,
    "ranker": {
      "rrf": { "weights": [1.0, 1.0] },
      "vertex_ranker": {
        "model": "semantic-ranker-fast@latest",
        "top_n": 50,
        "text_record_spec": {
          "query": "running shoes",
          "title_template": "{title}",
          "content_template": "{body.text}"
        }
      }
    }
  }
}

Templates use dot-paths to Data Object data fields, for example, {title} or {nested.field}. These fields must exist in the Collection schema, otherwise the request is rejected during validation. If a Data Object is missing the provided field, the server transparently refetches the full record from storage so the template can still be populated.

Quota and pricing

VertexRanker on Agent Retrieval uses a free-tier allowance with usage-based overage billing. Each project receives a free allowance of ranking usage per 30-day period. Usage within this allowance incurs no cost. Standard Ranking API pricing applies to the consumer project for any usage beyond this allowance.

The following table lists the quota values.

Reaching the free-tier allowance doesn't fail your requests. After the 80,000 ranking unit allowance is consumed, subsequent VertexRanker usage continues to succeed and is billed as overage. The allowance resets 30 days from the time of your first usage.

Ranking units are computed from the number of records sent to the ranker and the size of their title and content templates, using the same accounting as the standalone Ranking API. See Ranking API pricing for full details.

Before you can use VertexRanker, the Discovery Engine must be enabled on the consumer project. For more information, see Failure conditions.

Failure handling and warnings

VertexRanker is a best-effort reranker. If the ranking call fails, the BatchSearchDataObjects RPC still succeeds and returns the RRF-fused results truncated to top_k. The failure is reported in the search_response_metadata.warnings field in the response. The full status code from the Ranking API is preserved. The warning code for unexpected statuses is UNAVAILABLE with the warning message: "Reranking is temporarily unavailable. Returning fused (RRF) results without semantic reranking."

Failure conditions

The entire BatchSearchDataObjects RPC fails with FAILED_PRECONDITION (no fallback to RRF) in the following cases.

• Discovery Engine API not enabled — the Ranking API returns FAILED_PRECONDITION with the message Discovery Engine API is not enabled for the consumer project /<N/>. Please enable the API and try again." Fix: enable the Discovery Engine API on the consumer project.

The customer must enable the Discovery Engine for the consumer project for reranking to occur.

The following table lists warning codes, the typical causes generating the warnings, and the message explaining the warning.