# 文档重排

来源: https://platform.lyrouter.com/ai_gateway/docs/rerank
更新日期: 2026-10-19

按与查询的相关度给一组文档打分并排序，适合在检索增强（RAG）、语义搜索中对召回结果做精排；把文本转换成向量用[创建向量](https://platform.lyrouter.com/ai_gateway/docs/embeddings)。OpenAI 没有重排接口，LYRouter 把请求体原样发到通道的 `/rerank` 地址，只替换 `model`，所以字段名、取值和响应格式以模型所属服务商的 rerank 文档为准。请求和响应都是 JSON，不支持流式；OpenAI SDK 没有重排方法，请直接发 HTTP 请求。

`POST /v1/rerank`

## 鉴权

在请求头中携带 API Key：

```text
Authorization: Bearer <API Key>
```

`Bearer` 区分大小写。也可以改用 `x-api-key: <API Key>`，两者同时存在时只读 `Authorization`。API Key 在工作空间的 **API 密钥** 页面创建，只用于 LYRouter 鉴权，不会转发给上游服务商。完整说明见[接入地址与鉴权](https://platform.lyrouter.com/ai_gateway/docs/call-gateway)，环境变量 `LYROUTER_API_KEY` 的设置见[完成第一次模型调用](https://platform.lyrouter.com/ai_gateway/docs/quickstart)。

## 请求头

| 请求头 | 必填 | 说明 |
| --- | --- | --- |
| `Content-Type` | 是 | `application/json`，其他类型返回 400 |

## 请求体

下表是 Jina、Cohere 等常见重排接口通用的字段，具体字段名和取值以模型所属服务商的 rerank 文档为准。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 重排模型 ID，获取方法见下文「选择模型」。请始终写明：不写时使用工作空间的默认模型，而默认模型通常是对话模型，落到它上面会返回 400 `unsupported_model_api` 或上游的错误，见下文「网关行为」 |
| `query` | string | 是 | 查询文本 |
| `documents` | array | 是 | 待排序的文档，通常是字符串数组。条数和长度上限由服务商决定 |
| `top_n` | integer | 否 | 只返回相关度最高的前 N 条。透传给上游，是否生效取决于模型 |
| `return_documents` | boolean | 否 | 结果中是否带回文档原文。透传给上游，是否生效取决于模型 |

其他字段原样转发给上游，是否生效取决于模型。

### 选择模型

可用的重排模型以工作空间的模型广场为准：在模型广场搜索 `rerank` 等关键词，复制模型 ID 替换示例中的 `MODEL_ID`。

也可以用 [`GET /v1/models`](https://platform.lyrouter.com/ai_gateway/docs/models) 筛选。返回的每个模型带 `api_types` 字段，含 `rerank` 的可调用本接口：

```bash
curl -s https://api.lyrouter.com/v1/models \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  | jq -r '.data[] | select((.api_types // []) | index("rerank")) | .id'
```

模型没有声明 `api_types` 时不会出现在筛选结果里，可以在模型广场确认。字段说明见[列出模型](https://platform.lyrouter.com/ai_gateway/docs/models)，筛选向量模型的方法见[创建向量](https://platform.lyrouter.com/ai_gateway/docs/embeddings)。

## 请求示例

Python 示例使用 `httpx`，安装 `openai` 时已一并安装。

**请求示例**

cURL:
```bash
curl https://api.lyrouter.com/v1/rerank \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "query": "如何查看一次调用实际使用的模型？",
    "documents": [
      "日志详情的「模型（实际）」显示最终回答的模型。",
      "API Key 在工作空间的 API 密钥页面创建。",
      "智能路由页面可以设置默认模型。"
    ],
    "top_n": 2,
    "return_documents": true
  }'
```

Python:
```python
import os
import httpx

resp = httpx.post(
    "https://api.lyrouter.com/v1/rerank",
    headers={"Authorization": f"Bearer {os.environ['LYROUTER_API_KEY']}"},
    json={
        "model": "MODEL_ID",
        "query": "如何查看一次调用实际使用的模型？",
        "documents": [
            "日志详情的「模型（实际）」显示最终回答的模型。",
            "API Key 在工作空间的 API 密钥页面创建。",
            "智能路由页面可以设置默认模型。",
        ],
        "top_n": 2,
        "return_documents": True,
    },
    timeout=60,
)
resp.raise_for_status()
for item in resp.json()["results"]:
    print(item["index"], item["relevance_score"])
```

Node.js:
```js
const resp = await fetch("https://api.lyrouter.com/v1/rerank", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYROUTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "MODEL_ID",
    query: "如何查看一次调用实际使用的模型？",
    documents: [
      "日志详情的「模型（实际）」显示最终回答的模型。",
      "API Key 在工作空间的 API 密钥页面创建。",
      "智能路由页面可以设置默认模型。",
    ],
    top_n: 2,
    return_documents: true,
  }),
});
if (!resp.ok) throw new Error(await resp.text());
const { results } = await resp.json();
for (const item of results) console.log(item.index, item.relevance_score);
```

## 响应

成功时的响应由服务商返回，网关不改写；出错时返回 `error` 对象。下面的 200 是常见形态，400 是请求落到了不支持重排接口的模型（多为默认模型，见下文「网关行为」），403 是模型没有在本工作空间开通且工作空间没有设置默认模型。

**响应示例**

200:
```json
{
  "model": "MODEL_ID",
  "results": [
    { "index": 0, "relevance_score": 0.92, "document": { "text": "日志详情的「模型（实际）」显示最终回答的模型。" } },
    { "index": 2, "relevance_score": 0.31, "document": { "text": "智能路由页面可以设置默认模型。" } }
  ],
  "usage": { "total_tokens": 86 }
}
```

400:
```json
{
  "error": {
    "message": "This model does not support the rerank API",
    "type": "invalid_request_error",
    "code": "unsupported_model_api"
  }
}
```

403:
```json
{
  "error": {
    "message": "Model is not available in the model plaza",
    "type": "access_denied",
    "code": "model_not_available"
  }
}
```

| 字段 | 说明 |
| --- | --- |
| `results[].index` | 文档在请求 `documents` 中的位置 |
| `results[].relevance_score` | 相关度分数，按它从高到低排列。分数范围由模型决定，不同模型之间不可直接比较 |
| `results[].document` | 设置了 `return_documents` 且模型支持时返回原文 |
| `usage` | 用量，字段由服务商决定；有的服务商放在 `meta` 等其他位置 |

### 计费

按模型广场列出的计费项计费，用量取自上游响应的 `usage`；按次计价的模型读取其中的 `search_units`。单价以模型广场为准，每次调用的实际费用在[日志](https://platform.lyrouter.com/ai_gateway/docs/logs)中查看。费用估算方法见[调用费用与缓存计费](https://platform.lyrouter.com/ai_gateway/docs/estimate)。

## 网关行为

- **请求原样转发**：网关只把 `model` 换成通道的真实模型名，其余字段原样转发（通过虚拟模型调用时见下文）。网关会重新编码 JSON：对象的键按固定顺序排列，数字最多保留 14 位有效数字。
- **通道回退**：同一模型有多个通道时，按工作空间的[路由策略](https://platform.lyrouter.com/ai_gateway/docs/routing)依次尝试，前一个通道失败就换下一个。
- **默认模型兜底**：工作空间在智能路由中设置了默认模型时，下面三种情况会落到默认模型上。默认模型通常是对话模型，此时得到的是报错，而不是你预期的结果（默认模型声明了 `api_types` 时，网关返回 400 `This model does not support the rerank API`；没有声明时，请求会转发给上游，由上游报错）：
  - 请求没写 `model`；
  - `model` 写错，或该模型没有在本工作空间开通；
  - 该模型的所有通道都失败了。这时上游的真实报错被默认模型的报错取代，请到日志详情的「上游调用尝试」查看前面每次尝试的原因。
- **虚拟模型与 Auto**：[虚拟模型](https://platform.lyrouter.com/ai_gateway/docs/presets)可以用于本接口，前提是它的模型列表全部是重排模型；虚拟模型的系统提示词不会注入，但设置的推理参数会按字段名合并进请求体，因此给重排接口使用的虚拟模型不要设置推理参数。[`lyrouter/auto`](https://platform.lyrouter.com/ai_gateway/docs/auto) 的候选是对话模型，不要用于本接口。
- **安全围栏**：[安全围栏](https://platform.lyrouter.com/ai_gateway/docs/guardrails)的封禁、模型访问控制和客户端访问控制照常生效；敏感信息、提示词注入和意图安全检测不作用于本接口。

## 常见错误

错误响应为 `{"error":{"message":"...","type":"...","code":"..."}}`，`code` 只有部分错误才有。

| 状态码 | `error.message` | `error.code` | 原因与处理 |
| --- | --- | --- | --- |
| 400 | `This model does not support the rerank API` | `unsupported_model_api` | 所用模型声明了 `api_types` 且不支持重排接口，多为请求落到了默认模型，见上文「默认模型兜底」。写上正确的重排模型 ID |
| 400 | `you must provide a model parameter` | `missing_model` | 没写 `model`，工作空间也没有默认模型 |
| 400 | `unsupported content-type: <类型>, only application/json is supported` | — | `Content-Type` 不是 JSON。响应体是一行纯文本，但响应头 `Content-Type` 目前是 `application/json`，解析前先判断正文是否为 JSON |
| 403 | `Model is not available in the model plaza` | `model_not_available` | 模型没有在本工作空间开通，且没有设置默认模型。请管理员在模型广场开通，或换用已开通的模型 |
| 503 | `all routed candidates exhausted` | `no_route_candidate` | 找不到可服务这次请求的通道，见[模型不可用](https://platform.lyrouter.com/ai_gateway/docs/unavailable) |

- 文档条数、长度超限等由上游服务商返回，状态码和报错原文由上游决定。
- 用没有声明 `api_types` 的模型（见[列出模型](https://platform.lyrouter.com/ai_gateway/docs/models)）调用本接口时，网关不返回 400 `unsupported_model_api`，而是把请求转发给上游，由上游报错。
- 网关先解析模型，再检查 `Content-Type`：没写 `model` 或模型没有开通时，先返回模型相关的错误（400 `missing_model`、403 `model_not_available`）；模型有效时才返回 400 `unsupported content-type: …`。
- 401 / 403 鉴权问题见[401 / 403：鉴权与权限](https://platform.lyrouter.com/ai_gateway/docs/auth-errors)，429 见[429：限流与配额](https://platform.lyrouter.com/ai_gateway/docs/rate-errors)。完整列表见[错误码与请求标识](https://platform.lyrouter.com/ai_gateway/docs/errors)。