# 重排序候选内容

根据查询意图为候选内容排序，并从 `results[]` 读取精排结果。文本和多模态候选内容使用同一接口；本页以文本候选内容说明最小请求。

```text
POST https://token.moi.matrixorigin.cn/v1/rerank
```

## 调用前准备

请求地址为 `https://token.moi.matrixorigin.cn/v1/rerank`。准备具有 Genesis 权限的访问凭据、支持 Rerank 的模型 ID，以及候选项与其业务 ID 的映射。

下方示例使用：

- `$GENESIS_ACCESS_TOKEN`：实际访问令牌或服务账号 API Key，通过 `Authorization` Header 传递。
- `$MODEL_ID`：要调用的模型 ID，填入请求体的 `model` 字段。

## 请求头

| 请求头 | 是否必填 | 说明 |
| --- | --- | --- |
| `Authorization` | 是 | 使用 `Bearer <GENESIS_ACCESS_TOKEN>` 传递访问凭据。 |
| `Content-Type` | 是 | 设置为 `application/json`。 |

## 请求体

请求体包含以下字段。

类型后的 `[]` 表示数组。例如，`string[]` 是字符串数组，`object[]` 是对象数组。

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 支持 Rerank 的模型 ID。 |
| `query` | string 或 object | 是 | 排序依据。文本请求使用字符串。 |
| `documents` | string[] 或 object[] | 是 | 待排序的候选内容。文本请求使用字符串数组。 |
| `top_n` | integer | 否 | 限制返回的最高相关性结果数量。 |
| `return_documents` | boolean | 否 | 是否在结果中返回原始候选内容。 |

## 请求示例

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

## 成功响应

```json
{
  "id": "<REQUEST_ID>",
  "model": "<MODEL_ID>",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.987,
      "document": "RAG 通过检索外部知识库增强模型回答能力。"
    }
  ]
}
```

响应中用于读取排序结果的字段如下。

字段路径中的 `[]` 表示数组中的每一项。例如，`results[].index` 表示 `results` 数组中每一项的 `index` 字段。该字段始终用于关联本次请求的 `documents` 下标；不要用排序后的数组位置替代原始候选项位置。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 本次重排序请求的标识。 |
| `model` | string | 实际处理请求的模型 ID。 |
| `results` | array | 按当前请求相关性排序的结果列表。 |
| `results[].index` | integer | 原始 `documents` 数组的下标。 |
| `results[].relevance_score` | number | 当前模型给出的相关性分数。仅在相同模型和业务语境内比较。 |
| `results[].document` | string 或 object | `return_documents` 为 `true` 时返回的原始候选内容。 |
| `results[].document.text` | string | `document` 为对象时的文本候选内容；仅在响应实际包含时读取。 |

## 错误响应

接口不使用 `code`、`msg`、`data` 包络。收到非成功 HTTP 状态时，不要从 `results[]` 读取排序结果。错误对象由兼容的模型服务返回；除 `error.message` 外的字段可能省略。

### 错误对象字段

```json
{
  "error": {
    "message": "<可读错误信息>",
    "type": "<错误类型，可能省略>",
    "code": "<错误代码，可能省略>"
  }
}
```

错误正文中可能出现的字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `error.message` | string | 可读错误信息。 |
| `error.type` | string，可选 | 上游错误类别。 |
| `error.code` | string 或 null，可选 | 上游错误代码。 |

### 常见 HTTP 错误

下表说明收到不同 HTTP 状态时应执行的操作。

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - —
  - 查询、候选内容或参数组合不符合接口要求。
  - 先使用一个短查询和少量文本候选内容验证。
* - `401`
  - —
  - 凭据无效，或当前凭据无权调用该模型。
  - 检查认证 Header 和模型范围。
* - `403`
  - —
  - 凭据无效，或当前凭据无权调用该模型。
  - 检查认证 Header 和模型范围。
* - `413`
  - —
  - 候选内容或请求体超过允许范围。
  - 减少单次候选项数量并分批处理。
* - `429`
  - —
  - 当前服务受到限制或暂时不可用。
  - 降低请求频率，或稍后再次提交请求。
* - `5xx`
  - —
  - 当前服务受到限制或暂时不可用。
  - 降低请求频率，或稍后再次提交请求。
```

## 后续操作

- [Embeddings](embeddings.md)
- [查询模型列表](models.md)