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)可以正常返回。

相關文件