文本排序 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 为准。按次计价的模型每次请求固定扣费。