文档重排

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

鉴权

在请求头中携带 API Key：

Authorization: Bearer <API Key>

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

请求头

请求体

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

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

选择模型

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

也可以用 GET /v1/models 筛选。返回的每个模型带 api_types 字段，含 rerank 的可调用本接口：

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 时不会出现在筛选结果里，可以在模型广场确认。字段说明见列出模型，筛选向量模型的方法见创建向量。

请求示例

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

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

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"])

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 是模型没有在本工作空间开通且工作空间没有设置默认模型。

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

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

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

计费

按模型广场列出的计费项计费，用量取自上游响应的 usage；按次计价的模型读取其中的 search_units。单价以模型广场为准，每次调用的实际费用在日志中查看。费用估算方法见调用费用与缓存计费。

网关行为

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

常见错误

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

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