使用 Ranking API 提高搜索和 RAG 质量

在 Agent Search 的检索增强生成 (RAG) 体验中，您可以根据查询对一组文档进行排名。

Ranking API 会接收一个文档列表作为输入，然后根据这些文档与查询的相关程度对它们进行重新排名。嵌入仅关注文档和查询的语义相似度，而 Ranking API 则可以为您提供文档对给定查询的回答程度的精确分数。在检索到初始候选文档集后，可以使用排名 API 来提高搜索结果的质量。

Ranking API 是无状态的，因此在调用该 API 之前无需为文档编制索引。您只需传入查询和文档即可。 这使得该 API 非常适合对 Vector Search 和其他搜索解决方案中的文档进行重新排序。

本页面介绍了如何使用 Ranking API 根据查询对一组文档进行排名。

使用场景

Ranking API 的主要用例是提高搜索结果的质量。

不过，在任何需要查找哪些内容与用户查询最相关的场景中，Ranking API 都很有价值。例如，Ranking API 可以帮助您完成以下任务：

  • 寻找合适的内容提供给 LLM 进行接地

  • 提高现有搜索体验的相关性

  • 识别文档中的相关部分

以下流程概述了如何使用 Ranking API 提高分块文档的结果质量：

  1. 使用 Document AI Layout Parser API 将一组文档拆分为多个文档块。

  2. 使用嵌入 API 为每个分块创建嵌入。

  3. 将嵌入加载到 Vector Search 或其他搜索解决方案中。

  4. 查询搜索索引并检索最相关的分块。

  5. 使用 Ranking API 对相关分块进行重新排序。

输入数据

Ranking API 需要以下输入：

  • 要针对其对记录进行排名的查询。

    例如：

    "query": "Why is the sky blue?"

  • 一组与查询相关的记录。这些记录以对象数组的形式提供。每条记录都可以包含唯一 ID、标题和文档内容。每条记录都必须包含标题、内容或两者。每条记录支持的词元数上限取决于所使用的模型版本。例如，003 之前的模型版本支持 512 个词元，而 004 版本支持 1024 个词元。如果标题和内容的组合长度超过模型的词元限制，则多余的内容会被分块并分段处理。如果记录被认为过长，则部分内容会被截断并忽略。

    每个请求最多可包含 1,000 条记录。

    例如，记录数组如下所示。在实际应用中，数组中会包含更多记录，内容也会长得多：

    "records": [
   {
       "id": "1",
       "title": "The Color of the Sky: A Poem",
       "content": "A canvas stretched across the day,\nWhere sunlight learns to dance and play.\nBlue, a hue of scattered light,\nA gentle whisper, soft and bright."
   },
   {
       "id": "2",
       "title": "The Science of a Blue Sky",
       "content": "The sky appears blue due to a phenomenon called Rayleigh scattering. Sunlight is comprised of all the colors of the rainbow. Blue light has shorter wavelengths than other colors, and is thus scattered more easily."
   }
]

  • 可选：您希望排名 API 返回的记录数上限。默认情况下，系统会返回所有记录；不过，您可以使用 topN 字段返回较少的记录。无论设置了什么值，所有记录都会进行排名。

    例如，以下代码会返回排名前 10 的记录：

    "topN": 10,

  • 可选：此设置用于指定您是希望 API 仅返回记录的 ID，还是希望同时返回记录标题和内容。默认情况下，系统会返回完整记录。设置此参数的主要原因是为了减小响应载荷的大小。

    例如，设置为 true 只会返回记录 ID，而不会返回标题或内容：

    "ignoreRecordDetailsInResponse": true,

  • 可选：模型名称。这指定了用于对文档进行排名的模型。如果未指定模型，则使用 semantic-ranker-default@latest，它会自动指向最新的可用模型。如需指向特定模型，请指定支持的模型中列出的模型名称之一，例如 semantic-ranker-512-003。

    在以下示例中，model 设置为 semantic-ranker-default@latest。 这意味着 Ranking API 将始终使用最新的可用模型。

    "model": "semantic-ranker-default@latest"

输出数据

Ranking API 会返回一个排名记录列表，其中包含以下输出：

  • 得分：一个介于 0 到 1 之间的浮点值，表示记录的相关性。

  • ID：记录的唯一 ID。

  • 如果请求，则返回完整对象：ID、标题和内容。

    例如：

{
    "records": [
        {
            "id": "2",
            "score": 0.98,
            "title": "The Science of a Blue Sky",
            "content": "The sky appears blue due to a phenomenon called Rayleigh scattering. Sunlight is comprised of all the colors of the rainbow. Blue light has shorter wavelengths than other colors, and is thus scattered more easily."
        },
        {
            "id": "1",
            "score": 0.64,
            "title": "The Color of the Sky: A Poem",
            "content": "A canvas stretched across the day,\nWhere sunlight learns to dance and play.\nBlue, a hue of scattered light,\nA gentle whisper, soft and bright."
        }
    ]
}

根据查询对一组记录进行排名（或重新排名）

通常，您需要向排名 API 提供一个查询和一组与该查询相关的记录，这些记录已经通过其他方法（例如关键字搜索或 Vector Search）进行了排名。然后，您可以使用 Ranking API 来提高排名质量，并确定一个分数，用于表示每条记录与查询的相关性。

  1. 获取查询和结果记录。确保每条记录都有一个 ID，以及标题和/或内容。

    每条记录支持的 token 数量上限取决于模型版本。003 及更低版本的模型（例如 semantic-ranker-512-003）支持每条记录 512 个 token。从 004 版开始，此限制增加到 1024 个 token。如果标题和内容的组合长度超过模型的 token 限制，则额外内容会被分块并分段处理。在极端情况下，如果记录被认为过长，则部分内容将被截断并忽略。

  2. 使用以下代码调用 rankingConfigs.rank 方法：

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/rankingConfigs/default_ranking_config:rank" \
-d '{
"model": "semantic-ranker-default@latest",
"query": "QUERY",
"records": [
    {
        "id": "RECORD_ID_1",
        "title": "TITLE_1",
        "content": "CONTENT_1"
    },
    {
        "id": "RECORD_ID_2",
        "title": "TITLE_2",
        "content": "CONTENT_2"
    },
    {
        "id": "RECORD_ID_3",
        "title": "TITLE_3",
        "content": "CONTENT_3"
    }
]
}'

替换以下内容：

  • PROJECT_ID：您的 Google Cloud 项目的 ID。
  • QUERY：要针对其对记录进行排名和评分的查询。
  • RECORD_ID_n：用于标识记录的唯一字符串。
  • TITLE_n：记录的标题。
  • CONTENT_n：记录的内容。

如需了解此方法的一般信息，请参阅 rankingConfigs.rank。

点击查看示例 curl 命令和响应。

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: my-project-123" \
    "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/rankingConfigs/default_ranking_config:rank" \
    -d '{
        "model": "semantic-ranker-default@latest",
        "query": "what is Google gemini?",
        "records": [
            {
                "id": "1",
                "title": "Gemini",
                "content": "The Gemini zodiac symbol often depicts two figures standing side-by-side."
            },
            {
                "id": "2",
                "title": "Gemini",
                "content": "Gemini is a cutting edge large language model created by Google."
            },
            {
                "id": "3",
                "title": "Gemini Constellation",
                "content": "Gemini is a constellation that can be seen in the night sky."
            }
        ]
    }'
    
{
    "records": [
        {
            "id": "2",
            "title": "Gemini",
            "content": "Gemini is a cutting edge large language model created by Google.",
            "score": 0.97
        },
        {
            "id": "3",
            "title": "Gemini Constellation",
            "content": "Gemini is a constellation that can be seen in the night sky.",
            "score": 0.18
        },
        {
            "id": "1",
            "title": "Gemini",
            "content": "The Gemini zodiac symbol often depicts two figures standing side-by-side.",
            "score": 0.05
        }
    ]
}

Python

如需了解详情，请参阅 Agent Search Python API 参考文档。

如需向 Agent Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"

client = discoveryengine.RankServiceClient()

# The full resource name of the ranking config.
# Format: projects/{project_id}/locations/{location}/rankingConfigs/default_ranking_config
ranking_config = client.ranking_config_path(
    project=project_id,
    location="global",
    ranking_config="default_ranking_config",
)
request = discoveryengine.RankRequest(
    ranking_config=ranking_config,
    model="semantic-ranker-default@latest",
    top_n=10,
    query="What is Google Gemini?",
    records=[
        discoveryengine.RankingRecord(
            id="1",
            title="Gemini",
            content="The Gemini zodiac symbol often depicts two figures standing side-by-side.",
        ),
        discoveryengine.RankingRecord(
            id="2",
            title="Gemini",
            content="Gemini is a cutting edge large language model created by Google.",
        ),
        discoveryengine.RankingRecord(
            id="3",
            title="Gemini Constellation",
            content="Gemini is a constellation that can be seen in the night sky.",
        ),
    ],
)

response = client.rank(request=request)

# Handle the response
print(response)

支持的模型

您可以使用以下模型。

模型名称 最新默认模型 (semantic-ranker-default@latest) 最新快速模型 (semantic-ranker-fast@latest) 输入 上下文窗口 发布日期 停用日期
semantic-ranker-default-005 是 否 文字（25 种语言） 1024 2026 年 9 月 1 日 待定
semantic-ranker-fast-005 否 是 文字（25 种语言） 1024 2026 年 9 月 1 日 待定
semantic-ranker-default-004 否 否 文字（25 种语言） 1024 2025 年 4 月 9 日 待定
semantic-ranker-fast-004 否 否 文字（25 种语言） 1024 2025 年 4 月 9 日 待定
semantic-ranker-default-003 否 否 文字（25 种语言） 512 2024 年 9 月 10 日 待定
semantic-ranker-default-002 否 否 文字（仅限英语） 512 2024 年 6 月 3 日 待定

后续步骤

了解如何将排名方法与其他 RAG API 搭配使用，以根据非结构化数据生成接地回答。