文档 · 重排序

把检索结果的顺序修回来的那一步

Q: return_documents 是做什么的？

把原文和分数一起返回。

作者：tokenexchage 团队 · 最后更新：2026-10-17

向量检索能给你候选，给不了你顺序。auto/rerank 拿一段查询和一批文档打分，然后按分数还给你——走 POST /v1/rerank，返回形状和现成的 rerank 客户端对得上。

一句话定义

auto/rerank 是一种 tokenexchage 提供的重排序能力别名：给一段查询和一批文档打分，按分数还回排序结果。必填字段是 2 个（query 与 documents），可选字段 1 个（return_documents）；它背后只有 1 个模型，换模型会在不告诉你的情况下改变结果顺序。返回形状和现成的 rerank 客户端对得上，已经会调这类接口的代码不用改解析逻辑。

关键数字

接口	POST /v1/rerank
必填字段	query、documents
可选字段	return_documents
别名背后的候选模型数	1

三步接入

在控制台创建 API 密钥。
向 https://tokenexchage.com/v1/rerank 发 POST，带上 query 和 documents。
按返回的分数取排序结果；需要原文时把 return_documents 打开。

怎么调

curl https://tokenexchage.com/v1/rerank \
  -H "Authorization: Bearer sk-你的key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto/rerank",
    "query": "怎么轮换 API key？",
    "documents": [
      "控制台里可以轮换 key。",
      "计费按请求次数算。",
      "轮换之后旧 key 立刻失效。"
    ],
    "top_n": 2
  }'

{
  "results": [
    { "index": 2, "relevance_score": 0.93 },
    { "index": 0, "relevance_score": 0.71 }
  ],
  "usage": { … }
}

index 指的是你传进去的 documents 数组里的位置——默认不回显原文。加 return_documents: true，每条结果会多一个 document 字段。

它在你流水线里的位置

检索通常是两段。第一段用向量做快速近似搜索，top_k 故意开大一点，因为这个阶段召回比精确重要。第二段对这批候选做更慢、更准的排序。

auto/rerank 就是第二段。当你的 top_k 明显大于真正喂给模型的条数时，它值得加上——多数情况都是这样，因为答案通常在前二十条里，但很少正好在第一条。

它和向量别名配套：向量算一次存起来，查询时再用重排序。

参数

字段	必填	说明
`model`	是	`auto/rerank`
`query`	是	查询串
`documents`	是	字符串数组
`top_n`	否	只要最好的 N 条
`return_documents`	否	把原文和分数一起返回

别名背后只有一个模型。换重排序模型会在不告诉你的情况下改变结果顺序——同一个查询，返回的排序不一样，而返回里没有任何一处看着异常。失败反而更安全。

什么时候需要重排序

向量检索负责「从一百万条里挑出二十条可能相关的」，它算的是整体语义距离，不懂「这条到底能不能回答这个问题」。重排序负责第二步：把这二十条逐条和查询放在一起看，打一个更准的相关度分数，然后重新排队。两步分开做，是因为第一步要快（要扫全库），第二步可以慢（只处理几十条）。

如果检索结果本来就少、或者查询很短很明确，重排序带来的提升有限，先把向量那一步做对更要紧。反过来，查询长、文档长、领域词多的时候，重排序往往是效果提升最大的一步——它能看到查询和文档之间的具体关系，而不只是两个向量的夹角。

怎么用好重排序

控制送进去的条数。一次送五十到一百条是常见区间：太少召不回来，太多既慢又会把噪声带进来。送进去的顺序不重要，但返回的分数不要跨查询直接比较——不同查询的分数分布不一样，只在同一次请求内部有意义。

评估方式要看排序质量而不是命中率。准备一批真实查询，每条人工标出「哪几条是真正相关的」，然后看真正相关的结果平均排在第几位、前三条里命中几条。只算命中率会掩盖排序问题——该出现的都出现了，但排在第 18 位，等于没出现。

和向量接口怎么配合

典型链路是：文档入库时算一次向量并连同原文存好；查询时把问题算成向量做最近邻，拿到候选；再把候选的原文和查询一起送去重排序，取前几条交给模型生成回答。向量那一步算过的结果不用重算，重排序只是给已有的候选重新排序。

两边的候选数量要对上。向量检索的 top-k 应该大于最终要用的条数，给重排序留出调整空间；如果向量只召回五条、重排序也只能在这五条里排，那它几乎没有发挥余地。

常见误用

拿重排序当过滤器用。它的输出是排序，不是「相关 / 不相关」的判定——分数低的结果仍然可能有用，直接按阈值砍掉会把一些边界情况一起砍掉。要不要过滤，先看黄金集上砍掉的那些里有多少是真正相关的。

把不同查询的分数放在一起比较。每个查询的分数分布不一样，A 查询的 0.8 和 B 查询的 0.8 不代表同样的相关程度。只在同一次请求内部比较才有意义。

候选集怎么定

候选太少，重排没有发挥空间；太多，延迟和成本都上去。经验区间是 20–50 条：先由向量或关键词检索召回，再交给重排。

20 条以下：重排提升有限，直接按第一段分数取前 5 更省。
20–50 条：重排收益最明显，适合大多数问答和检索场景。
50 条以上：先做粗筛，再重排，否则延迟会成为瓶颈。

和向量检索怎么配合

向量负责「找得全」，重排负责「排得准」。两段式流程：向量召回 30 条 → 重排取前 5 → 交给模型生成。不要指望重排把没召回的内容找回来。

常见问题

它和向量接口什么关系？

配套使用：向量算一次存起来，查询时再用重排序修顺序。

为什么只有一个候选？

换重排序模型会在不告诉你的情况下改变结果顺序 —— 同一个查询，返回的排序不一样，而返回里没有任何一处看着异常。失败反而更安全。

return_documents 是做什么的？

把原文和分数一起返回。

其他能力

同一套命名，一个能力一个别名，都在 /v1/models 里：

embedding