# 文本与多模态 Rerank

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

## 前提条件

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

## 请求地址

```text
POST <GENESIS_BASE_URL>/rerank
```

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

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

```bash
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` 数组，数组可混合文本和图像片段：

```bash
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 | 否 | 控制每个结果是否包含原始候选文档。 |

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

## 成功响应

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

```json
{
  "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 | 按[身份认证](../getting-started/authentication.md)重新配置当前环境的凭据。 |

## 下一步

- [将文本或图文内容转换为向量](embeddings.md)
- [查看当前凭证可用的模型](../getting-started/available-models.md)
- [使用 Responses API 生成结果](../openai-compatible/responses-api.md)