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

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