文本排序 Rerank

给定一个查询和一组候选文档,返回每个文档与查询的相关性分数,并按相关性排序。常用于 RAG 检索后的精排。请求和响应采用 Jina / Cohere Rerank 风格(query + documents → results[].relevance_score),已有 Jina / Cohere 客户端只需替换 Base URL 和 Key。

项 值
方法与路径 POST /v1/rerank
鉴权 Authorization: Bearer YOUR_API_KEY
Content-Type application/json

快速示例

cURL

BASH
curl https://www.nextai-code.com/v1/rerank \
  -H "Authorization: Bearer $NEXTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "query": "如何重置密码?",
    "documents": [
      "在设置页点击「忘记密码」即可通过邮箱重置。",
      "我们的办公时间是工作日 9:00-18:00。",
      "密码需包含字母和数字,长度不少于 8 位。"
    ],
    "top_n": 2,
    "return_documents": true
  }'

Python(requests)

OpenAI SDK 没有 rerank 方法,直接发 HTTP 请求即可。

PYTHON
import os, requests

resp = requests.post(
    "https://www.nextai-code.com/v1/rerank",
    headers={"Authorization": f"Bearer {os.environ['NEXTAI_API_KEY']}"},
    json={
        "model": "YOUR_MODEL",
        "query": "如何重置密码?",
        "documents": ["在设置页点击「忘记密码」即可通过邮箱重置。", "我们的办公时间是工作日 9:00-18:00。"],
        "top_n": 1,
    },
)
resp.raise_for_status()
for r in resp.json()["results"]:
    print(r["index"], r["relevance_score"])

可用的 Rerank 模型以 模型列表(GET /v1/models)为准。

请求参数

参数 类型 必填 说明
model string 是 Rerank 模型名。缺失时返回 400(未指定模型名称)
query string 是 查询文本。为空时返回 400(query 不能为空)
documents array 是 候选文档列表,建议使用字符串;对象形式(如 {"text": "..."})是否支持取决于模型。为空时返回 400(documents 不能为空)
top_n integer 否 只返回相关性最高的前 N 条。未传时返回条数取决于模型(部分模型默认只返回 1 条),建议显式传入
return_documents boolean 否 是否在结果中附带原文档,默认 false;部分模型会忽略该参数始终返回文档
max_chunk_per_doc integer 否 长文档切块上限,是否生效取决于模型
overlap_tokens integer 否 切块重叠 Token 数,是否生效取决于模型

响应

无论底层是哪家模型服务商,响应都统一为以下结构:

JSON
{
  "results": [
    { "index": 0, "relevance_score": 0.92, "document": "在设置页点击「忘记密码」即可通过邮箱重置。" },
    { "index": 2, "relevance_score": 0.31, "document": "密码需包含字母和数字,长度不少于 8 位。" }
  ],
  "usage": { "prompt_tokens": 58, "completion_tokens": 0, "total_tokens": 58 }
}
字段 说明
results[].index 文档在请求 documents 中的下标
results[].relevance_score 相关性分数,越大越相关;分数区间取决于模型
results[].document 原文档,仅在返回文档时出现;形态(字符串或 {"text": ...})取决于模型
usage 用量;prompt_tokens 与 total_tokens 为计费 Token 数。对象中可能还有其他取值为 0 的统计字段,可忽略

results 通常已按 relevance_score 从高到低排列;需要严格顺序时请在客户端按分数排序。

计费

按 Token 计费,Token 数以响应中的 usage 为准。按次计价的模型每次请求固定扣费。

相关文档