Skip to main content
POST
文档重排序:bge-reranker-v2-m3
右側 Playground 可直接除錯:在 AuthorizationBearer sk-your-api-key, 預設示例已填好中文語料,點擊發送即可看到排序結果。
模型能力、定價、實測資料與三個必踩的坑見 概覽; 召回數量、切塊、閾值等調參方法見 RAG 實戰調優

引數說明速查

未識別的引數(如 max_chunks_per_docrank_fieldstruncate)會被靜默忽略,不報錯。

響應要點

  • index —— 該文件在入參 documents 陣列中的原始下標。用它回填你自己的文件物件, 不要拿返回的 text 去反查原文。
  • relevance_score —— 範圍 0–1。只在同一次請求內可比, 不同 query 之間不可比、跨語言場景會整體偏低,詳見 概覽的閾值說明
  • results 恆按 relevance_score 降序排列;index 全覆蓋且不重複。
  • 用量看 usage.prompt_tokens(query 計一次 + 全部文件)與 total_tokens(query 按對重複計); input_tokens / output_tokens 該通道恆為 0,不要用。 本輪未能通過賬單確認實際扣的是哪個欄位,成本核算以控制台賬單為準。

錯誤碼對照

503 優先懷疑模型名。請求體解析失敗時(例如 Content-Type 寫成 text/plain), 閘道讀不到 model 欄位,同樣會返回這條 503 且模型名位置為空,很容易誤判成”渠道故障”。
路徑寫錯不會給 404。實測 /rerank/v2/rerank(Cohere SDK v2 預設路徑)都返回 HTTP 200 + 網站 HTML 首頁,客戶端表現為”響應無法解析”。 只有 https://api.apiyi.com/v1/rerank 是有效路徑。

除錯要點

候選太少時分數差距會很誇張(第一名 0.97、第二名 0.12),看不出模型的判別邊界。 建議放 10–20 篇、其中混入 2–3 篇「主題相近但不回答問題」的干擾項, 這樣才能看出分數在你的語料上大致落在什麼區間——這是後續定閾值的依據。
中文 query 配英文文件,正確結果的得分可能只有 0.003–0.3,但排序是對的。 這是模型的固有特性,不是調用出錯。判斷標準看排序,不看絕對值。
即使只傳 1 篇候選,實測 P50 也在 2 秒左右——這部分是閘道與上游的固定開銷。 候選數從 1 加到 100,P50 只從 2.0 秒漲到 3.8 秒。 所以不要為了壓延遲把候選集砍得很小,收益遠小於預期。
上游 TPM 只有 20,000。用 100 篇候選反覆除錯,約 15 次就會把整分鐘預算用光並開始 429。 除錯階段建議用 10–20 篇候選,既夠看分數分佈,也不會因為配額中斷。 詳見 RAG 實戰調優的配額章節

授權

Authorization
string
header
必填

在请求头中添加 Authorization: Bearer YOUR_API_KEY

主體

application/json
model
string
必填

固定 bge-reranker-v2-m3(大小写敏感,写错返回 503)

範例:

"bge-reranker-v2-m3"

query
string
必填

检索问题。不可为空字符串,否则返回 400

documents
string[]
必填

候选文档,只接受字符串数组(传 [{"text": "..."}] 对象数组会返回 400)。 不可为空数组。建议单请求 ≤ 100 条。

top_n
integer

返回前 N 条。省略、传 0 或负数都返回全部。 必须是整数,传字符串返回 400。 不影响用量 —— 所有候选文档都会过一遍模型。

範例:

2

return_documents
boolean

是否在结果中回显文档原文。 注意:当前通道该参数不生效,无论传什么都会回显 document.text 对带宽敏感的场景请自行按 index 回填,不要依赖此开关裁剪响应体。

範例:

true

回應

重排序成功

results
object[]

按 relevance_score 降序排列

usage
object

用量统计。本模型只有输入侧消耗