# Rerank

根据查询意图为候选内容重新排序，并返回精排结果。

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

## 调用前准备

准备具有 Genesis 权限的[访问凭据](../../../../guides/genesis/api-keys.md#选择凭据类型)、支持 Rerank 的模型 ID，以及候选内容与业务 ID 的映射。

## 请求体

将 `$GENESIS_ACCESS_TOKEN` 替换为访问令牌或服务账号 API Key，将 `$MODEL_ID` 替换为要调用的模型 ID。

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 请求示例

```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
  }'
```

:::::
:::::{tab-item} 参数说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 要调用的 Rerank 模型 ID。 |
| `query` | string | 是 | 用于判断候选内容相关性的查询文本。 |
| `documents` | array of string | 是 | 待重排的文本候选内容。 |
| `top_n` | integer | 否 | 要返回的最高相关性结果数量。 |
| `return_documents` | boolean | 否 | 是否在结果中返回原始候选内容。 |

:::::
::::::
:::::::

## 成功响应

服务返回候选内容的重排结果。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

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

:::::
:::::{tab-item} 字段说明

::::{tab-set}
:::{tab-item} 通用字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 本次重排序请求的标识。 |
| `model` | string | 实际处理请求的模型 ID。 |
| `results` | array of object | 按相关性排序的结果列表。 |

:::
:::{tab-item} 结果项

下面表格展开示例中 `results` 数组的每一项；每一行是该数组项的一个字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `index` | integer | 原始 `documents` 数组中的下标。 |
| `relevance_score` | number | 当前模型给出的相关性分数，仅在相同模型和业务语境内比较。 |
| `document` | string 或 object | `return_documents` 为 `true` 时返回的原始候选内容。 |

:::
:::{tab-item} 文档对象

下面表格展开示例中 `results[].document` 对象；每一行是该对象的一个字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `text` | string | `document` 为对象时的文本候选内容。 |

:::
::::

:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

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

:::::
:::::{tab-item} 字段说明

::::{tab-set}
:::{tab-item} 通用字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `error` | object | 错误对象。 |

:::
:::{tab-item} 错误对象

下面表格展开示例中 `error` 对象；每一行是该对象的一个字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `message` | string | 可读错误信息。 |
| `type` | string | 错误类别，可能省略。 |
| `code` | string 或 null | 错误代码，可能省略。 |

:::
::::

:::::
::::::
:::::::