文本与多模态 Rerank¶

使用 Rerank API 按查询意图为候选内容重新排序。文本和多模态请求使用同一个接口，但 query 与 documents 的结构不同；完成本页后，你可以保留候选项映射，并按 results[] 返回的顺序使用精排结果。

前提条件¶

已从获取可用模型取得 Rerank 模型 ID。图文候选内容需要支持多模态 Rerank 的模型。
已按身份认证配置访问令牌。
已准备待排序的候选内容，并为每项保留业务 ID 与提交顺序的映射。

请求地址¶

POST <GENESIS_BASE_URL>/rerank

对文本候选内容重新排序¶

文本请求使用字符串 query 和字符串数组 documents。top_n 用于限制返回的候选数量，return_documents 控制结果是否包含原始文档：

curl -X POST "$GENESIS_BASE_URL/rerank" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -d '{
    "model": "<TEXT_RERANK_MODEL_ID>",
    "query": "什么是检索增强生成？",
    "documents": [
      "RAG 通过检索外部知识库增强大模型回答能力。",
      "深度学习是机器学习的一个分支。",
      "向量数据库可以高效存储和检索高维向量。"
    ],
    "top_n": 2,
    "return_documents": true
  }'

响应中的 results[].index 对应本次 documents 数组的下标。将该下标映射回候选项的业务 ID，不要把排序后的数组位置当作原始文档位置。

对图文候选内容重新排序¶

多模态请求使用对象形式的 query 和 documents。每个对象包含 content 数组，数组可混合文本和图像片段：

curl -X POST "$GENESIS_BASE_URL/rerank" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -d '{
    "model": "<MULTIMODAL_RERANK_MODEL_ID>",
    "query": {
      "content": [
        {
          "type": "text",
          "text": "找出与这张商品图最相关的描述"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://<IMAGE_HOST>/<QUERY_IMAGE_PATH>"
          }
        }
      ]
    },
    "documents": [
      {
        "content": [
          {
            "type": "text",
            "text": "这是一款蓝色包装的智能设备，适合办公桌面使用。"
          }
        ]
      },
      {
        "content": [
          {
            "type": "image_url",
            "image_url": {
              "url": "https://<IMAGE_HOST>/<DOCUMENT_IMAGE_PATH>"
            }
          }
        ]
      }
    ],
    "top_n": 2,
    "return_documents": true
  }'

图片 URL 必须能被当前模型服务读取。也可以按当前接口支持的形态使用 image_base64 提供图片 Base64 内容。不要将 Chat Completions 的 messages 结构用于 /rerank。

请求参数¶

字段	类型	必需	说明
`model`	string	是	Rerank 模型 ID。文本与图文候选内容需要选择对应能力的模型。
`query`	string 或 object	是	排序依据。文本请求传字符串；多模态请求传包含 `content` 的对象。
`query.content`	array	多模态请求时	查询的文本和图像内容片段数组。
`documents`	string[] 或 object[]	是	待排序的候选内容。文本请求传字符串数组；多模态请求传对象数组。
`documents[].content`	array	多模态请求时	一个候选项的文本和图像内容片段数组。
`content[].type`	string	多模态请求时	内容片段类型：`text`、`image_url` 或 `image_base64`。
`content[].text`	string	`type` 为 `text` 时	文本内容。
`content[].image_url.url`	string	`type` 为 `image_url` 时	可访问的图像 URL，或当前接口支持的 Data URL。
`content[].image_base64`	string	`type` 为 `image_base64` 时	图片的 Base64 内容。
`top_n`	integer	否	限制返回的最高相关性结果数量。
`return_documents`	boolean	否	控制每个结果是否包含原始候选文档。

候选数量、输入大小和图片限制以当前模型和接口说明为准。先使用少量候选内容验证输入与结果映射，再接入完整检索链路。

成功响应¶

结果按相关性排序。以下示例中的分数仅说明字段形态，不是通用相关性阈值：

{
  "id": "<request-id>",
  "model": "<RERANK_MODEL_ID>",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.987,
      "document": "RAG 通过检索外部知识库增强大模型回答能力。"
    },
    {
      "index": 2,
      "relevance_score": 0.614,
      "document": "向量数据库可以高效存储和检索高维向量。"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "total_tokens": 0
  }
}

多模态请求在 return_documents 为 true 时，results[].document 可以是原始多模态候选对象，而不一定是字符串。

字段	类型	返回条件	说明
`id`	string	成功响应返回	本次响应的标识。排查调用问题时提供该值。
`model`	string	成功响应返回	实际处理本次请求的模型 ID。
`results`	array	成功响应返回	按当前请求相关性排序的结果列表。
`results[].index`	integer	每个结果项返回	原始 `documents` 数组中的下标。用于关联候选项业务 ID。
`results[].relevance_score`	number	每个结果项返回	当前模型给出的相关性分数。适合在同一模型和评测语境中排序，不应直接作为跨模型阈值。
`results[].document`	string 或 object	`return_documents` 为 `true` 时	原始候选内容。多模态请求可能返回对象。
`usage`	object	当前响应包含时	本次请求的 Token 用量信息。只读取实际返回的字段。

在检索链路中使用¶

典型链路是先使用 Embeddings 召回候选内容，再由 Rerank 精排，并将前几项交给后续生成任务。候选数量和 top_n 应根据业务数据评测确定；不要将全部语料直接提交给 Rerank。

常见问题¶

现象	先检查	下一步
排序结果无法对应原始文档	`results[].index` 与提交的 `documents` 顺序	在请求前保存候选项业务 ID 与数组下标的映射。
图文候选内容被拒绝	模型能力、`query` 和 `documents` 的对象结构	更换为支持多模态 Rerank 的模型，并按 `content` 数组重新构造请求。
分数看似异常	所用模型、候选集和评测数据是否一致	仅在同一模型和业务语境中比较分数；通过离线评测确定阈值。
结果缺少原文	`return_documents` 是否设置为 `true`	需要在响应中读取原始候选内容时，重新发送带该参数的请求。
认证失败	请求地址、令牌和 `Authorization` Header	按身份认证重新配置当前环境的凭据。

下一步¶

最后更新于 2026 年 8 月 14 日