> ## Documentation Index > Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt > Use this file to discover all available pages before exploring further. # bge-reranker-v2-m3 文本重排序 > 多語言重排序模型 bge-reranker-v2-m3：對召回的候選文件逐條打相關性分並重新排序，是 RAG 檢索品質最划算的一次升級。API易 已開通 /v1/rerank 端點，$0.01 每 1M tokens。 `bge-reranker-v2-m3` 是智源研究院（BAAI）開源的多語言重排序模型。它解決的是檢索系統裡最常見的一類問題：**向量召回把相關文件撈回來了，但排在前面的偏偏不是最該看的那幾篇。** API易 已開通標準 `/v1/rerank` 端點，一個令牌即可呼叫。 **模型名**：`bge-reranker-v2-m3`（大小寫敏感）；**端點**：`POST /v1/rerank`；`default` / `svip` 分組均可用。 本頁所有資料來自 API易 2026 年 7 月 30 日 (UTC+8) 的實測，共 60+ 用例。 ## 它是什麼，什麼時候該用 重排序模型是**交叉編碼器**（Cross-Encoder）：把 query 和每一篇候選文件拼在一起、完整過一遍模型，直接輸出一個相關性分數。 這和 embedding 模型有本質區別： | | Embedding（向量檢索） | Rerank（重排序） | | ------- | ------------------------- | ---------------------- | | 計算方式 | query 和文件**各自**編碼成向量，再算距離 | query 和文件**拼在一起**過模型 | | 能否預先建索引 | ✅ 文件向量可離線算好存進向量庫 | ❌ 必須拿到 query 才能算，無法預計算 | | 速度 | 快，百萬級庫毫秒返回 | 慢，與候選數成正比 | | 準確度 | 一般 | 高 | | 定位 | **召回**：從百萬篇裡撈出幾十篇 | **精排**：從幾十篇裡挑出最相關的幾篇 | 所以它不是向量檢索的替代品，而是**接在向量檢索後面的第二級**。 重排序模型**不能建索引、不能做召回**。它沒有向量輸出，也無法脫離 query 單獨處理文件。 如果你想要的是"把文件存進向量庫"，需要的是 [文本向量化](/zh-Hant/api-capabilities/text-embedding) 而不是本頁的模型。 ### 一個實測對比 同一批 10 篇候選文件、同一個查詢（"API 請求一直返回 429 錯誤，怎麼解決？"），只改排序方法： | 排序方法 | nDCG\@3 | P\@3 | 排在前三的是什麼 | | ------------------------------- | -------- | -------- | ----------------------------- | | 純向量排序（`text-embedding-3-small`） | 0.53 | 0.33 | 直答、**HTTP 4xx 科普**、**機房割接公告** | | 加一層 `bge-reranker-v2-m3` | **1.00** | **1.00** | 直答、直答、指數退避說明 | 向量檢索把"HTTP 狀態碼 4xx 科普"和一篇提到 "4 月 29 日"的機房公告排進了前三——它們和 query 主題接近、字面重合，但**不回答問題**。重排序把這兩篇擠了下去。 這就是重排序的核心價值：**把「同一個話題」和「真正回答了問題」區分開。** ## 模型資訊 | 項 | 值 | | --------- | -------------------------------------------------- | | **模型名稱** | `bge-reranker-v2-m3`（大小寫敏感，寫錯返回 503） | | **架構** | Cross-Encoder，XLM-RoBERTa-large 骨架，基於 bge-m3 微調 | | **引數量** | 約 568M（0.6B） | | **上下文上限** | **8192 tokens，按「query + 單篇文件」計**（實測超限返回 400，不靜默截斷） | | **多語言** | 實測中 / 英 / 日 / 韓 / 俄 / 法 / 阿拉伯語排序均正確，支援跨語言檢索 | | **端點** | `POST /v1/rerank` | | **可用分組** | `default`、`svip` | | **上游** | 華為雲 ModelArts（官轉資源） | | **開源許可** | Apache 2.0 | ## 定價 | 專案 | 價格 | | -- | ------------------ | | 輸入 | \$0.01 / 1M tokens | | 輸出 | 無（本模型不產生輸出 token） | **便宜到可以忽略**：一次 100 篇候選（約 2700 tokens）的重排序約合 \$0.000027，一百萬次也才 \$27。 重排序幾乎從不是 RAG 系統的成本瓶頸——**瓶頸是延遲，不是錢**，調優時優先看候選集大小對延遲的影響。 **usage 口徑**（實測）： * `prompt_tokens` = query（計一次）+ 全部候選文件。實測嚴格線性：`≈ 26.9 × 文件數 + 7`（擬合偏差 \< 0.31%），可在客戶端精確預估 * `total_tokens` 比 `prompt_tokens` 大，差值隨候選數增長——相當於把 query 按「query + 每篇文件」這一對重複計入 * `input_tokens` / `output_tokens` 該通道**恆為 0**，不要用 * `top_n` 和 `return_documents` **都不影響用量**——所有候選都要過一遍模型，只是少返回幾條 本輪測試**未能通過賬單反推確認實際扣費依據是 `prompt_tokens` 還是 `total_tokens`** （測試令牌讀不到賬戶餘額介面）。兩者在 100 篇候選時相差約 45%。 對成本敏感的場景請以控制台賬單為準，不要直接拿 `usage` 欄位做財務核算。 ## 最簡呼叫 ```bash cURL theme={null} curl https://api.apiyi.com/v1/rerank \ -H "Authorization: Bearer $APIYI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "bge-reranker-v2-m3", "query": "杭州有哪些適合旅遊的景點？", "documents": [ "西湖是杭州著名的旅遊景點，擁有斷橋、蘇堤和雷峰塔等景觀。", "上海外灘位於黃浦江畔，是上海的標誌性景點。", "靈隱寺位於杭州西湖區，是中國著名的佛教寺院。" ], "top_n": 2 }' ``` ```python Python theme={null} import os, requests resp = requests.post( "https://api.apiyi.com/v1/rerank", headers={"Authorization": f"Bearer {os.environ['APIYI_API_KEY']}"}, json={ "model": "bge-reranker-v2-m3", "query": "杭州有哪些適合旅遊的景點？", "documents": [ "西湖是杭州著名的旅遊景點，擁有斷橋、蘇堤和雷峰塔等景觀。", "上海外灘位於黃浦江畔，是上海的標誌性景點。", "靈隱寺位於杭州西湖區，是中國著名的佛教寺院。", ], "top_n": 2, }, timeout=60, ).json() for r in resp["results"]: print(f"{r['relevance_score']:.4f} {r['document']['text']}") ``` ```javascript Node.js theme={null} const resp = await fetch('https://api.apiyi.com/v1/rerank', { method: 'POST', headers: { Authorization: `Bearer ${process.env.APIYI_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ model: 'bge-reranker-v2-m3', query: '杭州有哪些適合旅遊的景點？', documents: [ '西湖是杭州著名的旅遊景點，擁有斷橋、蘇堤和雷峰塔等景觀。', '上海外灘位於黃浦江畔，是上海的標誌性景點。', '靈隱寺位於杭州西湖區，是中國著名的佛教寺院。', ], top_n: 2, }), }); const data = await resp.json(); data.results.forEach((r) => console.log(r.relevance_score, r.document.text)); ``` 響應： ```json theme={null} { "results": [ { "document": { "text": "西湖是杭州著名的旅遊景點..." }, "index": 0, "relevance_score": 0.97265625 }, { "document": { "text": "靈隱寺位於杭州西湖區..." }, "index": 2, "relevance_score": 0.1181640625 } ], "usage": { "prompt_tokens": 70, "total_tokens": 91 } } ``` **`index` 是最重要的欄位**。它是該文件在你傳入的 `documents` 陣列中的**原始下標**， 用它回填你自己的文件物件（ID、URL、後設資料），而不是拿返回的 `text` 去反查。 ## 請求引數 | 引數 | 型別 | 必填 | 說明 | | ------------------ | --------- | -- | --------------------------------- | | `model` | string | ✓ | 固定 `bge-reranker-v2-m3`，**大小寫敏感** | | `query` | string | ✓ | 檢索問題。空字串返回 400 | | `documents` | string\[] | ✓ | 候選文件，**只接受字串陣列**。空陣列返回 400 | | `top_n` | int | | 返回前 N 條。省略 / 傳 0 / 傳負數都返回全部。不影響用量 | | `return_documents` | bool | | 是否回顯原文。**當前通道該引數不生效**，詳見下方已知問題 | ## 實測能力矩陣 | 能力 | 實測結果 | | ------------------------- | ------------------------------------------------------ | | 中文語義排序 | ✅ nDCG\@3 = 1.00 | | 關鍵詞幹擾抵抗 | ✅ Top-2 正確，但干擾項絕對分可能很高（見下） | | 跨語言檢索（中↔英） | ✅ 排序正確，但絕對分數被壓低 1–2 個數量級 | | 多語言（日 / 韓 / 俄 / 法 / 阿） | ✅ 5 語種全部排序正確 | | **否定語義理解** | ❌ **明顯弱項**，nDCG\@3 = 0.47（見下） | | 結果確定性 | ✅ 同請求重複 10 次得分逐位一致；打亂候選順序漂移僅 3.7e-4 | | 重複文件一致性 | ✅ 相同文件得分逐位一致 | | 單請求候選上限 | ✅ 實測 2000 條可用；**建議 ≤ 100 條** | | 單文件長度上限 | 8192 tokens/對，超限返回 400（不靜默截斷） | | **上游配額** | ⚠️ TPM 20,000 / RPM 120，併發槽位約 4–5；100 篇候選約 15 次/分鐘（見下） | | `return_documents: false` | ❌ 引數被忽略 | ## 三個必須知道的坑 很多人第一反應是"設個 0.5 的閾值過濾一下"。**實測這樣做會出事**： | 場景 | 真正相關文件的得分割槽間 | | ------------------- | ---------------------------- | | 中文 query × 中文文件 | 0.289 – 1.000（中位數 0.948） | | 非中文同語言（日/韓/俄/法/阿） | **0.005 – 0.998**（中位數 0.241） | | **跨語言（中↔英）** | **0.0038 – 0.205** | | 關鍵詞高度重合但**不相關**的干擾項 | 最高衝到 **0.945** | 也就是說：一個 0.5 的閾值會**濾掉全部跨語言正確結果**、濾掉多數非中文場景的第二名， 同時**放行**那篇講蘋果種植的干擾文件。 **正確做法**：把它當排序依據，不要當絕對置信度。要過濾就用相對閾值 （`score >= top1_score × 0.3`）或直接取 Top-N，並在你自己的資料上標註一批樣本來定閾值。 查詢"哪些景點適合冬天去？"，候選裡放兩篇**明確說不適合冬天**的文件： | 排名 | 得分 | 文件 | 是否真的相關 | | -- | ----- | ---------------- | ------ | | #1 | 0.811 | 哈爾濱冰雪大世界⋯⋯冬季旅遊首選 | ✅ | | #2 | 0.769 | 北戴河⋯⋯**不適合冬季旅遊** | ❌ | | #3 | 0.531 | 青海湖⋯⋯**不建議冬天前往** | ❌ | | #4 | 0.375 | 霧凇島⋯⋯冬季必去 | ✅ | | #5 | 0.289 | 三亞⋯⋯冬天避寒熱門 | ✅ | 模型看到的是"冬天 + 景點 + 旅遊"的話題匹配，**沒有理解"不"字**。nDCG\@3 只有 0.47。 **應對**：涉及否定、排除、條件判斷（"不含麩質的"、"除了北京以外"、"未成年人不適用"）的查詢， 重排序之後必須再過一層大模型做判斷，不能直接把 Top-N 餵給使用者。 實測同一句命中內容，後面接不同長度的無關填充： | 文件總長 | 命中句在**開頭**的得分 | 命中句在**結尾**的得分 | | ------- | ------------- | ------------- | | 528 字元 | 0.933 | 0.720 | | 1028 字元 | 0.931 | 0.500 | | 4028 字元 | 0.907 | 0.351 | | 8028 字元 | 0.828 | 0.181 | 同時，**無關內容變長反而會抬高得分**：同一篇不相關文件，短版 0.029、長版 0.121，翻了 4 倍。 **應對**：把長文件切成 200–500 字的小塊再送進重排序，用「塊的最高分」代表文件得分。 切塊是這個模型上收益最大的一步預處理。 完整的調參方法、切塊策略、閾值確定流程見 [RAG 實戰調優](/zh-Hant/api-capabilities/rerank/rag-best-practices)。 ## 已知問題 **`return_documents` 引數不生效**（2026-07-30 實測）：無論傳 `true`、`false` 還是省略， 響應中都會回顯 `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 倍**。 實測分離出兩個**互相獨立**的機制： | 機制 | 實測表現 | | ------------------- | -------------------------------------------------------------------------- | | **併發槽位約 4–5 個在途請求** | 10 併發只成功 4 個、20 併發只成功 5 個（此時 token 僅佔 3–4% TPM）；**序列 20 次則 20/20 全過** | | **TPM 20,000 滑動視窗** | **完全序列**也會觸發：連發 1.3K tokens 的請求，第 8 個在累計 16,093 tokens 時 429，連掛 9 個後窗口滑動恢復 | 超出槽位的請求**直接 429、不排隊**，錯誤資訊統一是 `當前分組上游負載已飽和`， 無法區分撞的是哪一個，只能自己按預算推算。 **接入建議**：併發控制在 4 以內 + 指數退避重試，並按下方表格核算每分鐘的檢索次數上限。 ### 每分鐘能跑多少次檢索 按實測 `≈26.9 tokens/文件` 折算（TPM 20,000）： | 每次查詢的候選數 | 單次 tokens | 理論上限 | | -------- | --------- | ------------- | | 50 條 | 673 | 約 29 次/分鐘 | | 100 條 | 1,325 | **約 15 次/分鐘** | | 200 條 | 2,629 | 約 7 次/分鐘 | 這也解釋了為什麼**單請求候選集不能太大**：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 實戰調優](/zh-Hant/api-capabilities/rerank/rag-best-practices) 裡有 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）可以正常返回。 ## 相關文件 * [重排序 API 線上除錯](/zh-Hant/api-capabilities/rerank/rerank-api) * [RAG 實戰調優：怎麼用好重排序](/zh-Hant/api-capabilities/rerank/rag-best-practices) * [文本向量化](/zh-Hant/api-capabilities/text-embedding) * [模型價格](/models)