Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

使用 VertexRanker 对搜索结果进行重新排名

代理检索（以前称为 Vector Search 2.0）提供用于语义重新排名的 VertexRanker，该排名器由 Ranking API 提供支持。

在 Agent Retrieval 检索并融合候选结果（使用倒数排序融合 [RRF]）后，VertexRanker 会使用专用语义模型根据您的自然语言查询对融合的候选结果重新评分。这有助于提高前 k 个结果的相关性，尤其是在仅通过搜索无法发现细微差别的查询中。重新排名在服务器端进行，通过调用 BatchSearchDataObjects 实现。无需额外的客户端连接或额外的往返。

VertexRanker

VertexRanker 配置为 BatchSearchDataObjectsRequest 对象的 combine.ranker 字段的重排序器。您必须配置一个主要排序器（仅支持 RRF）。重新排名器在 RRF 融合步骤之后运行，并用语义重新评分的列表替换输出。

下表列出了排名器配置字段。

字段	必需	说明
`combine.ranker.rrf.weights`	是	用于对底层搜索结果进行 RRF 融合的权重。
`combine.ranker.vertex_ranker.model`	是	排名模型名称。仅支持 `semantic-ranker-fast@latest`。
`combine.ranker.vertex_ranker.top_n`	是	要从融合列表中发送到排序器的候选对象数量上限。有效值的范围介于 `1` 到 `1000` 之间。
`combine.ranker.vertex_ranker.text_record_spec.query`	是	排名工具用于对记录进行评分的自然语言查询。
`combine.ranker.vertex_ranker.text_record_spec.title_template`	是	模板字符串，例如 `{title}`，用于指定如何提取（构建）每条记录的标题。使用点路径指定数据字段。
`combine.ranker.vertex_ranker.text_record_spec.content_template`	是	模板字符串，例如 `{body.text}`，用于指定如何提取（构建）每条记录的主要内容。使用点路径指定数据字段。
`combine.top_k`	可选	重新排名后要返回的最终结果数。此值必须小于或等于 `vertex_ranker.top_n` 且小于或等于 1000。

以下示例展示了请求的正文。

{
  "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}"
        }
      }
    }
  }
}

模板使用指向数据对象数据字段的点路径，例如 {title} 或 {nested.field}。这些字段必须存在于集合架构中，否则系统会在验证期间拒绝相应请求。如果数据对象缺少提供的字段，服务器会透明地从存储空间中重新提取完整记录，以便模板仍可填充。

配额和价格

Agent Retrieval 中的 VertexRanker 采用免费层级配额，并根据用量收取超额费用。每个项目每 30 天可免费使用一次排名功能。在此限额内的使用量不会产生任何费用。如果使用量超出此限额，则使用方项目需按标准排名 API 价格付费。

下表列出了配额值。

项	值
免费层级限额	每个使用方项目每 30 天 80,000 个排名单元。
超量	在使用方项目中按标准排名 API 价格计费。
每次重新排名调用的记录数上限	1000（`top_n` 必须在 `[1, 1000]` 和 `top_k` 范围内，且 `top_k` <= `top_n`）。

达到免费层级限额不会导致请求失败。在 8 万个排名单元的许可用量耗尽后，后续的 VertexRanker 使用仍会成功，但会按超额用量计费。自您首次使用起 30 天后，系统会重置限额。

排名单元是根据发送给排名器的记录数以及标题和内容模板的大小计算得出的，所用的计算方式与独立 Ranking API 相同。如需了解完整详情，请参阅 Ranking API 价格。

您必须先在消费方项目中启用 Discovery Engine，然后才能使用 VertexRanker。如需了解详情，请参阅失败条件。

故障处理和警告

VertexRanker 是一种尽力而为的重新排名器。如果排名调用失败，BatchSearchDataObjects RPC 仍会成功，并返回截断为 top_k 的 RRF 融合结果。失败情况会在响应的 search_response_metadata.warnings 字段中报告。保留来自 Ranking API 的完整状态代码。意外状态的警告代码为 UNAVAILABLE，警告消息为："Reranking is temporarily unavailable. Returning fused (RRF) results without semantic reranking."

失败条件

在以下情况下，整个 BatchSearchDataObjects RPC 会失败并显示 FAILED_PRECONDITION（不会回退到 RRF）。

未启用 Discovery Engine API - Ranking API 返回 FAILED_PRECONDITION，并显示消息 Discovery Engine API is not enabled for the consumer project /<N/>. Please enable the API and try again." 修复：在消费方项目中启用 Discovery Engine API。

客户必须为使用方项目启用 Discovery Engine，才能进行重新排名。

下表列出了警告代码、生成警告的常见原因以及说明警告的消息。

警告代码	典型原因	警告消息
`RESOURCE_EXHAUSTED`	使用方项目中的排名 API 配额已超出。注意：超出 8 万个排名单元的限额不会导致此警告；系统会改为针对超额用量结算费用。	`<Quota exceeded message>; RankService.Rank call failed for consumer project <N> with request query: <query> and <model>: semantic-ranker-fast@latest number of records: <N>`
`DEADLINE_EXCEEDED`	`Ranker.Rank` 未在请求截止期限内完成。	`<deadline-exceeded message from Ranker.Rank>; RankService.Rank call failed for consumer project <N> with request query: <query> and <model>: semantic-ranker-fast@latest number of records: <N>`
`UNAVAILABLE`	返回了 `Ranker.Rank` `UNAVAILABLE`，或者返回了非保留代码（例如 `INTERNAL`），该代码会折叠为 `UNAVAILABLE`。	如果底层代码为 `UNAVAILABLE`：`"RankService.Rank call failed for consumer project...` 否则：`"Reranking is temporarily unavailable. Returning fused (RRF) results without semantic reranking."`
`FAILED_PRECONDITION`	由 Ranking API 返回的任何 `FAILED_PRECONDITION`。	`RankService.Rank call failed for consumer project <N> with request query: <query> and <model>: semantic-ranker-fast@latest number of records: <N>`
`CANCELLED`	调用方在重新排名完成之前取消了 `BatchSearchDataObjects` RPC。	`<cancellation message from the cancelled RankService.Rank RPC>; RankService.Rank call failed for consumer project <N> with request query: <query> and <model>: semantic-ranker-fast@latest number of records: <N>`