2026年openlux rerank api怎么接入：请求参数、返回结果与调用示例

2026年openlux rerank api怎么接入：请求参数、返回结果与调用示例

向量检索能快速召回一批候选文档，但召回的排序常常不够准，rerank 就是用来把候选重新精排一次的那一步。

搜索 openlux rerank api 怎么接入的开发者，通常已经有了一套向量检索流程，想在召回之后加一层精排。难点不在调用本身，而在请求参数怎么组织、返回的分数怎么解读、排序结果如何映射回原始文档列表。

下面按参数说明、返回结构、调用示例和常见问题四个部分展开。所有字段名称与取值范围请以 openlux 官方文档为准，不同服务在命名习惯上会有差异。

rerank 在检索链路里解决什么问题

典型的检索流程是两段式：先用向量检索从海量文档里召回几十到上百条候选，再用 rerank 模型对这几十条做精排，最后取前几条交给大模型生成答案。第一段追求“不漏”，第二段追求“排得准”。

之所以要分两段，是因为两者的计算方式不同。向量检索把查询和文档各自编码成向量再比距离，速度快但精度有限；rerank 模型通常把查询和文档放在一起做交叉计算，打分更准，但代价是慢，所以只适合处理少量候选。

如果你的检索结果经常出现“相关文档明明在召回列表里，却没被排到前面”的情况，加一层 rerank 往往比调向量库参数更直接。前提是候选本身质量过关，精排只能重新排序，不能凭空召回。

接入前要确认的接口信息

接口地址与鉴权方式

先确认 rerank 端点是否与对话补全端点共用同一个 Base URL，以及鉴权头是 Authorization: Bearer 还是自定义字段。很多服务把 rerank 挂在同一基础地址下的独立路径上，也有服务单独提供域名。两种写法都常见，照文档抄即可。

请求字段的命名习惯

rerank 接口的参数命名各家不完全一致，主流写法用 query 与 documents，也有服务用 texts 或 passages。字段名写错时服务端通常不会给出友好提示，只会报参数校验失败。接入前先通读一次文档里的请求体示例。

请求参数怎么组织

一个最小可用的请求体结构大致如下，字段顺序不影响结果，但结构必须正确。documents 是字符串数组，不要传对象数组，除非文档明确说明支持带元数据的结构。

{
  "model": "你的-rerank-模型标识",
  "query": "用户提出的问题",
  "documents": [
    "候选文档一的内容",
    "候选文档二的内容",
    "候选文档三的内容"
  ],
  "top_n": 2
}

如果候选文档本身较长，建议先做切分，让每条候选控制在合理长度内。过长的文档会被截断，截断位置之后的内容不参与打分，可能导致结果与你的直觉不符。

返回结果怎么读

rerank 的返回通常是按得分降序排列的数组，每一项包含一个指向原始输入的下标和对应的相关性分数：

{
  "results": [
    { "index": 2, "relevance_score": 0.93 },
    { "index": 0, "relevance_score": 0.41 }
  ]
}

读这个结果有两个关键点。第一，index 指的是你在 documents 数组中的原始位置，不是它在新排序里的名次。你拿到 index 之后，要回到自己的候选列表里取那条文档，映射错了就会把不相关的内容交给大模型。

第二，relevance_score 一般只在本批次内做相对比较有意义，不同查询、不同模型之间的分数不宜直接横向对比。想设置一个阈值过滤低分结果时，最好用你自己的数据实测一遍再定。

一个完整的调用示例

用 curl 验证最快，能排除掉 SDK 或封装层带来的干扰：

curl -X POST "$BASE_URL/rerank" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你的-rerank-模型标识",
    "query": "如何选择大模型接口",
    "documents": ["文档一", "文档二", "文档三"],
    "top_n": 2
  }'

Python 里用 requests 直接发也可以，注意 Base URL 与路径的拼接方式，以及 Key 从环境变量读取，不要硬编码在代码里：

import os, requests

BASE_URL = os.environ["OPENLUX_BASE_URL"]
headers = {
    "Authorization": "Bearer " + os.environ["OPENLUX_API_KEY"],
    "Content-Type": "application/json"
}
payload = {
    "model": "你的-rerank-模型标识",
    "query": "如何选择大模型接口",
    "documents": ["文档一", "文档二", "文档三"],
    "top_n": 2
}
resp = requests.post(BASE_URL + "/rerank", headers=headers, json=payload, timeout=30)
print(resp.status_code, resp.json())

常见问题与排查方向

• 返回结果为空：多为 top_n 设置异常，或 documents 传了空数组。
• 分数普遍偏低且差距很小：候选文档本身相关性不足，问题出在召回阶段，不是 rerank。
• 文档顺序对不上：没有按 index 回映射原始列表，而是直接用了返回顺序。
• 请求体过大被拒：单次传入的候选数量或总长度超限，需要分批调用再合并。
• 报鉴权错误：Key 与端点不匹配，或该 Key 未开通对应模型的调用权限。

rerank 只负责重排，不负责召回。如果正确答案压根不在候选列表里，再好的精排模型也无能为力——优化顺序应该是先补召回，再上精排。

多模型场景下如何统一接入

当你的应用里同时用到对话模型和 rerank 模型，甚至来自不同厂商时，Key、Base URL 和用量统计会迅速变得零散。此时可以考虑使用 千聚AI中转站 这类 AI 聚合平台：用统一的接口地址管理多家厂商的模型调用，API Key 与余额集中在一处查看，模型切换时不必反复改配置。

接入前建议先在平台控制台确认三件事：rerank 类接口是否被支持、对应的模型标识是什么、以及该模型的计费方式。不同接口的计费口径可能不一样，批量精排的消耗值得提前估算。具体可用模型与实时计费规则，以 千聚官网 页面信息为准。

总结一下 openlux rerank api 的接入要点：请求侧管好 query、documents 与 top_n 三个字段，返回侧靠 index 回映射原始列表、只看批内相对分数，工程侧做好分批与超时处理。把这三件事做扎实，精排这一层就能稳定地为你的检索质量服务。

如果你准备在检索链路里加入精排，并希望把对话与 rerank 模型的调用统一管理，可以进入千聚控制台注册账号，查看模型列表与接口文档，确认支持的接口类型后再开始联调。

进入千聚控制台查看模型并开始接入