Skip to main content
bge-reranker-v2-m3 是智源研究院(BAAI)开源的多语言重排序模型。它解决的是检索系统里最常见的一类问题:向量召回把相关文档捞回来了,但排在前面的偏偏不是最该看的那几篇。 API易 已开通标准 /v1/rerank 端点,一个令牌即可调用。
模型名bge-reranker-v2-m3(大小写敏感);端点POST /v1/rerankdefault / svip 分组均可用。 本页所有数据来自 API易 2026 年 7 月 30 日 (UTC+8) 的实测,共 60+ 用例。

它是什么,什么时候该用

重排序模型是交叉编码器(Cross-Encoder):把 query 和每一篇候选文档拼在一起、完整过一遍模型,直接输出一个相关性分数。 这和 embedding 模型有本质区别: 所以它不是向量检索的替代品,而是接在向量检索后面的第二级
重排序模型不能建索引、不能做召回。它没有向量输出,也无法脱离 query 单独处理文档。 如果你想要的是”把文档存进向量库”,需要的是 文本向量化 而不是本页的模型。

一个实测对比

同一批 10 篇候选文档、同一个查询(“API 请求一直返回 429 错误,怎么解决?”),只改排序方法: 向量检索把”HTTP 状态码 4xx 科普”和一篇提到 “4 月 29 日”的机房公告排进了前三——它们和 query 主题接近、字面重合,但不回答问题。重排序把这两篇挤了下去。 这就是重排序的核心价值:把「同一个话题」和「真正回答了问题」区分开。

模型信息

定价

便宜到可以忽略:一次 100 篇候选(约 2700 tokens)的重排序约合 $0.000027,一百万次也才 $27。 重排序几乎从不是 RAG 系统的成本瓶颈——瓶颈是延迟,不是钱,调优时优先看候选集大小对延迟的影响。
usage 口径(实测):
  • prompt_tokens = query(计一次)+ 全部候选文档。实测严格线性:≈ 26.9 × 文档数 + 7(拟合偏差 < 0.31%),可在客户端精确预估
  • total_tokensprompt_tokens 大,差值随候选数增长——相当于把 query 按「query + 每篇文档」这一对重复计入
  • input_tokens / output_tokens 该通道恒为 0,不要用
  • top_nreturn_documents 都不影响用量——所有候选都要过一遍模型,只是少返回几条
本轮测试未能通过账单反推确认实际扣费依据是 prompt_tokens 还是 total_tokens (测试令牌读不到账户余额接口)。两者在 100 篇候选时相差约 45%。 对成本敏感的场景请以控制台账单为准,不要直接拿 usage 字段做财务核算。

最简调用

响应:
index 是最重要的字段。它是该文档在你传入的 documents 数组中的原始下标, 用它回填你自己的文档对象(ID、URL、元数据),而不是拿返回的 text 去反查。

请求参数

实测能力矩阵

三个必须知道的坑

很多人第一反应是”设个 0.5 的阈值过滤一下”。实测这样做会出事也就是说:一个 0.5 的阈值会滤掉全部跨语言正确结果、滤掉多数非中文场景的第二名, 同时放行那篇讲苹果种植的干扰文档。正确做法:把它当排序依据,不要当绝对置信度。要过滤就用相对阈值 (score >= top1_score × 0.3)或直接取 Top-N,并在你自己的数据上标注一批样本来定阈值。
查询”哪些景点适合冬天去?“,候选里放两篇明确说不适合冬天的文档:模型看到的是”冬天 + 景点 + 旅游”的话题匹配,没有理解”不”字。nDCG@3 只有 0.47。应对:涉及否定、排除、条件判断(“不含麸质的”、“除了北京以外”、“未成年人不适用”)的查询, 重排序之后必须再过一层大模型做判断,不能直接把 Top-N 喂给用户。
实测同一句命中内容,后面接不同长度的无关填充:同时,无关内容变长反而会抬高得分:同一篇不相关文档,短版 0.029、长版 0.121,翻了 4 倍。应对:把长文档切成 200–500 字的小块再送进重排序,用「块的最高分」代表文档得分。 切块是这个模型上收益最大的一步预处理。
完整的调参方法、切块策略、阈值确定流程见 RAG 实战调优

已知问题

return_documents 参数不生效(2026-07-30 实测):无论传 truefalse 还是省略, 响应中都会回显 document.text。对带宽敏感的场景(大候选集 + 长文档), 响应体会比预期大很多,请自行按 index 回填原文,不要依赖此开关裁剪响应。
模型名写错返回 503 而不是 404:错误信息为 Current group default has no available channels for model xxx。 模型名大小写敏感BGE-Reranker-v2-M3 会被当作不存在的模型。 接入时如果收到 503,先核对模型名拼写,再考虑是不是真的没有可用渠道。
上游配额是这个模型最硬的约束,接入前必须先算 token 预算。上游(华为云 MaaS)给本模型的配额是 TPM 20,000 / RPM 120—— 同平台的 BGE-M3 向量化模型是 1,200,000 TPM,差 60 倍实测分离出两个互相独立的机制:超出槽位的请求直接 429、不排队,错误信息统一是 当前分组上游负载已饱和, 无法区分撞的是哪一个,只能自己按预算推算。接入建议:并发控制在 4 以内 + 指数退避重试,并按下方表格核算每分钟的检索次数上限。

每分钟能跑多少次检索

按实测 ≈26.9 tokens/文档 折算(TPM 20,000): 这也解释了为什么单请求候选集不能太大:1000 条候选就是 26,867 tokens, 一个请求就吃掉整分钟预算的 134%,必然 429。2000 条是 269%。
配额正在扩容中:上述 TPM 20,000 是上游给到的初始配额,API易 已在向平台申请扩容。 如果你的业务量超出上表的测算,请直接联系 API易客服评估提升上游配额, 不必按当前数字自行降级方案。
只有 /v1/rerank 是有效路径。实测请求 /rerank/v2/rerank(Cohere SDK v2 的默认路径) 会返回 HTTP 200 + 网站的 HTML 首页,而不是 JSON 404——客户端只会看到一个诡异的解析错误。 接入平台时若出现”返回内容无法解析”,先确认地址是否带 /v1

常见问题

只用向量检索:能跑,但 Top-N 的精度会明显低于加了重排序(实测 nDCG@3 从 1.00 掉到 0.53)。只用重排序:不行。它没有向量输出,必须先有候选集。百万篇文档逐条打分既不现实也不经济。标准做法是两段式:向量/BM25 召回 50–100 篇 → 重排序精排出 3–5 篇 → 送进大模型。
实测延迟随候选数近似线性增长(短文档):10 条约 2 秒、100 条约 5 秒、500 条约 15 秒、1000 条约 33 秒。推荐 50–100 条。低于 20 条,重排序能挽回的漏排有限;超过 200 条,延迟开始明显影响交互体验, 而召回列表尾部本来就很少含有正确答案。还要看 TPM 预算:100 篇候选约 1,325 tokens,在 TPM 20,000 下每分钟只能跑约 15 次检索。 候选数翻倍,吞吐就减半——候选数的选择同时是质量决策和容量决策
cohere SDK v2 实测不可用:它默认请求 /v2/rerank,该路径返回 HTML 首页而非 JSON,SDK 直接抛解析错误。参数名(query / documents / top_n / return_documents)确实与 Cohere Rerank v1 一致, 但 documents 只接受字符串数组(传 [{"text": "..."}] 返回 400),响应体也没有 Cohere 的 id / meta 字段。最省事的做法是自己包一层 HTTP 调用RAG 实战调优 里有 LangChain / LlamaIndex 的现成封装。实测可用的客户端:requests 裸 POST ✅、openai SDK 的 client.post("/rerank", ...) 逃生舱 ✅。
可以,而且很稳。同一请求重复 10 次,得分逐位一致(漂移 0)。 只有在打乱候选顺序重发时才会出现 3.7e-4 量级的漂移(bf16 批处理抖动),排序不受影响。缓存 key 用 query 归一化 + 候选文档内容哈希(有序)。 注意:由于顺序会带来微小漂移,不要把 relevance_score 本身当幂等标识或去重 key
直接返回 400,错误信息为 This model's maximum context length is 8192 tokens不会静默截断。这个上限是按「query + 单篇文档」这一对算的,不是整个请求的总量—— 实测单请求 400 篇 × 1000 字符(合计 33 万 tokens)可以正常返回。

相关文档