文档重排序:bge-reranker-v2-m3
curl --request POST \
--url https://api.apiyi.com/v1/rerank \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "bge-reranker-v2-m3",
"query": "杭州有哪些适合旅游的景点?",
"documents": [
"西湖是杭州著名的旅游景点,拥有断桥、苏堤和雷峰塔等景观。",
"上海外滩位于黄浦江畔,是上海的标志性景点。",
"灵隐寺位于杭州西湖区,是中国著名的佛教寺院。"
]
}
'import requests
url = "https://api.apiyi.com/v1/rerank"
payload = {
"model": "bge-reranker-v2-m3",
"query": "杭州有哪些适合旅游的景点?",
"documents": ["西湖是杭州著名的旅游景点,拥有断桥、苏堤和雷峰塔等景观。", "上海外滩位于黄浦江畔,是上海的标志性景点。", "灵隐寺位于杭州西湖区,是中国著名的佛教寺院。"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: 'bge-reranker-v2-m3',
query: '杭州有哪些适合旅游的景点?',
documents: [
'西湖是杭州著名的旅游景点,拥有断桥、苏堤和雷峰塔等景观。',
'上海外滩位于黄浦江畔,是上海的标志性景点。',
'灵隐寺位于杭州西湖区,是中国著名的佛教寺院。'
]
})
};
fetch('https://api.apiyi.com/v1/rerank', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.apiyi.com/v1/rerank",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => 'bge-reranker-v2-m3',
'query' => '杭州有哪些适合旅游的景点?',
'documents' => [
'西湖是杭州著名的旅游景点,拥有断桥、苏堤和雷峰塔等景观。',
'上海外滩位于黄浦江畔,是上海的标志性景点。',
'灵隐寺位于杭州西湖区,是中国著名的佛教寺院。'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.apiyi.com/v1/rerank"
payload := strings.NewReader("{\n \"model\": \"bge-reranker-v2-m3\",\n \"query\": \"杭州有哪些适合旅游的景点?\",\n \"documents\": [\n \"西湖是杭州著名的旅游景点,拥有断桥、苏堤和雷峰塔等景观。\",\n \"上海外滩位于黄浦江畔,是上海的标志性景点。\",\n \"灵隐寺位于杭州西湖区,是中国著名的佛教寺院。\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.apiyi.com/v1/rerank")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"bge-reranker-v2-m3\",\n \"query\": \"杭州有哪些适合旅游的景点?\",\n \"documents\": [\n \"西湖是杭州著名的旅游景点,拥有断桥、苏堤和雷峰塔等景观。\",\n \"上海外滩位于黄浦江畔,是上海的标志性景点。\",\n \"灵隐寺位于杭州西湖区,是中国著名的佛教寺院。\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.apiyi.com/v1/rerank")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"bge-reranker-v2-m3\",\n \"query\": \"杭州有哪些适合旅游的景点?\",\n \"documents\": [\n \"西湖是杭州著名的旅游景点,拥有断桥、苏堤和雷峰塔等景观。\",\n \"上海外滩位于黄浦江畔,是上海的标志性景点。\",\n \"灵隐寺位于杭州西湖区,是中国著名的佛教寺院。\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"results": [
{
"document": {
"text": "西湖是杭州著名的旅游景点,拥有断桥、苏堤和雷峰塔等景观。"
},
"index": 0,
"relevance_score": 0.97265625
},
{
"document": {
"text": "灵隐寺位于杭州西湖区,是中国著名的佛教寺院。"
},
"index": 2,
"relevance_score": 0.1181640625
}
],
"usage": {
"prompt_tokens": 70,
"total_tokens": 91
}
}重排序模型
重排序 API 參考
bge-reranker-v2-m3 重排序 API 參考與線上除錯:/v1/rerank 端點引數說明、響應結構、錯誤碼對照與除錯要點。
POST
/
v1
/
rerank
文档重排序:bge-reranker-v2-m3
curl --request POST \
--url https://api.apiyi.com/v1/rerank \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "bge-reranker-v2-m3",
"query": "杭州有哪些适合旅游的景点?",
"documents": [
"西湖是杭州著名的旅游景点,拥有断桥、苏堤和雷峰塔等景观。",
"上海外滩位于黄浦江畔,是上海的标志性景点。",
"灵隐寺位于杭州西湖区,是中国著名的佛教寺院。"
]
}
'import requests
url = "https://api.apiyi.com/v1/rerank"
payload = {
"model": "bge-reranker-v2-m3",
"query": "杭州有哪些适合旅游的景点?",
"documents": ["西湖是杭州著名的旅游景点,拥有断桥、苏堤和雷峰塔等景观。", "上海外滩位于黄浦江畔,是上海的标志性景点。", "灵隐寺位于杭州西湖区,是中国著名的佛教寺院。"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: 'bge-reranker-v2-m3',
query: '杭州有哪些适合旅游的景点?',
documents: [
'西湖是杭州著名的旅游景点,拥有断桥、苏堤和雷峰塔等景观。',
'上海外滩位于黄浦江畔,是上海的标志性景点。',
'灵隐寺位于杭州西湖区,是中国著名的佛教寺院。'
]
})
};
fetch('https://api.apiyi.com/v1/rerank', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.apiyi.com/v1/rerank",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => 'bge-reranker-v2-m3',
'query' => '杭州有哪些适合旅游的景点?',
'documents' => [
'西湖是杭州著名的旅游景点,拥有断桥、苏堤和雷峰塔等景观。',
'上海外滩位于黄浦江畔,是上海的标志性景点。',
'灵隐寺位于杭州西湖区,是中国著名的佛教寺院。'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.apiyi.com/v1/rerank"
payload := strings.NewReader("{\n \"model\": \"bge-reranker-v2-m3\",\n \"query\": \"杭州有哪些适合旅游的景点?\",\n \"documents\": [\n \"西湖是杭州著名的旅游景点,拥有断桥、苏堤和雷峰塔等景观。\",\n \"上海外滩位于黄浦江畔,是上海的标志性景点。\",\n \"灵隐寺位于杭州西湖区,是中国著名的佛教寺院。\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.apiyi.com/v1/rerank")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"bge-reranker-v2-m3\",\n \"query\": \"杭州有哪些适合旅游的景点?\",\n \"documents\": [\n \"西湖是杭州著名的旅游景点,拥有断桥、苏堤和雷峰塔等景观。\",\n \"上海外滩位于黄浦江畔,是上海的标志性景点。\",\n \"灵隐寺位于杭州西湖区,是中国著名的佛教寺院。\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.apiyi.com/v1/rerank")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"bge-reranker-v2-m3\",\n \"query\": \"杭州有哪些适合旅游的景点?\",\n \"documents\": [\n \"西湖是杭州著名的旅游景点,拥有断桥、苏堤和雷峰塔等景观。\",\n \"上海外滩位于黄浦江畔,是上海的标志性景点。\",\n \"灵隐寺位于杭州西湖区,是中国著名的佛教寺院。\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"results": [
{
"document": {
"text": "西湖是杭州著名的旅游景点,拥有断桥、苏堤和雷峰塔等景观。"
},
"index": 0,
"relevance_score": 0.97265625
},
{
"document": {
"text": "灵隐寺位于杭州西湖区,是中国著名的佛教寺院。"
},
"index": 2,
"relevance_score": 0.1181640625
}
],
"usage": {
"prompt_tokens": 70,
"total_tokens": 91
}
}右側 Playground 可直接除錯:在 Authorization 填
Bearer sk-your-api-key,
預設示例已填好中文語料,點擊發送即可看到排序結果。引數說明速查
| 引數 | 型別 | 必填 | 說明 |
|---|---|---|---|
model | string | ✓ | 固定 bge-reranker-v2-m3,大小寫敏感(寫錯返回 503,不是 404) |
query | string | ✓ | 檢索問題。傳空字串返回 400 query is required |
documents | string[] | ✓ | 候選文件。只接受字串陣列;空陣列返回 400 |
top_n | int | 返回前 N 條。省略 / 0 / 負數均返回全部;傳字串返回 400 | |
return_documents | bool | ⚠️ 當前通道不生效,無論傳什麼都會回顯原文 |
max_chunks_per_doc、rank_fields、truncate)會被靜默忽略,不報錯。
響應要點
{
"results": [
{ "document": { "text": "..." }, "index": 0, "relevance_score": 0.97265625 }
],
"usage": { "prompt_tokens": 70, "total_tokens": 91,
"input_tokens": 0, "output_tokens": 0 }
}
index—— 該文件在入參documents陣列中的原始下標。用它回填你自己的文件物件, 不要拿返回的text去反查原文。relevance_score—— 範圍 0–1。只在同一次請求內可比, 不同 query 之間不可比、跨語言場景會整體偏低,詳見 概覽的閾值說明。results恆按relevance_score降序排列;index全覆蓋且不重複。- 用量看
usage.prompt_tokens(query 計一次 + 全部文件)與total_tokens(query 按對重複計);input_tokens/output_tokens該通道恆為 0,不要用。 本輪未能通過賬單確認實際扣的是哪個欄位,成本核算以控制台賬單為準。
錯誤碼對照
| HTTP | 錯誤資訊 | 原因與處理 |
|---|---|---|
| 400 | query is required | 缺 query,或傳了空字串 |
| 400 | documents is required | 缺 documents,或傳了空陣列 |
| 400 | Input should be a valid string | documents 裡傳了物件;改成純字串陣列 |
| 400 | cannot unmarshal string into ... top_n of type int | top_n 傳了字串;改成整數 |
| 400 | This model's maximum context length is 8192 tokens | 單個「query + 文件」對超過 8192 tokens;切塊後重試 |
| 401 | Invalid token. | API Key 無效或未帶 Authorization 頭 |
| 429 | 當前分組上游負載已飽和,請稍後再試 | 撞上游配額(TPM 20,000 / RPM 120)。兩種成因錯誤資訊相同:① 併發超過約 4–5 個在途請求;② 一分鐘內累計 token 超 20,000(候選集 ≥ 1000 條時單請求即超)。併發降到 4 以內 + 退避重試,並核算 token 預算。該配額正在擴容中,業務量大可聯絡 API易客服 |
| 503 | Current group ... has no available channels for model | 模型名拼錯(大小寫敏感)或該分組確實無可用渠道。先查拼寫 |
503 優先懷疑模型名。請求體解析失敗時(例如
Content-Type 寫成 text/plain),
閘道讀不到 model 欄位,同樣會返回這條 503 且模型名位置為空,很容易誤判成”渠道故障”。路徑寫錯不會給 404。實測
/rerank、/v2/rerank(Cohere SDK v2 預設路徑)都返回
HTTP 200 + 網站 HTML 首頁,客戶端表現為”響應無法解析”。
只有 https://api.apiyi.com/v1/rerank 是有效路徑。除錯要點
想看真實分佈,別隻放 3 篇候選
想看真實分佈,別隻放 3 篇候選
候選太少時分數差距會很誇張(第一名 0.97、第二名 0.12),看不出模型的判別邊界。
建議放 10–20 篇、其中混入 2–3 篇「主題相近但不回答問題」的干擾項,
這樣才能看出分數在你的語料上大致落在什麼區間——這是後續定閾值的依據。
除錯跨語言時別被低分嚇到
除錯跨語言時別被低分嚇到
中文 query 配英文文件,正確結果的得分可能只有 0.003–0.3,但排序是對的。
這是模型的固有特性,不是調用出錯。判斷標準看排序,不看絕對值。
延遲基線約 2 秒
延遲基線約 2 秒
即使只傳 1 篇候選,實測 P50 也在 2 秒左右——這部分是閘道與上游的固定開銷。
候選數從 1 加到 100,P50 只從 2.0 秒漲到 3.8 秒。
所以不要為了壓延遲把候選集砍得很小,收益遠小於預期。
除錯時也會撞配額
除錯時也會撞配額
上游 TPM 只有 20,000。用 100 篇候選反覆除錯,約 15 次就會把整分鐘預算用光並開始 429。
除錯階段建議用 10–20 篇候選,既夠看分數分佈,也不會因為配額中斷。
詳見 RAG 實戰調優的配額章節。
授權
在请求头中添加 Authorization: Bearer YOUR_API_KEY
主體
application/json
固定 bge-reranker-v2-m3(大小写敏感,写错返回 503)
範例:
"bge-reranker-v2-m3"
检索问题。不可为空字符串,否则返回 400
候选文档,只接受字符串数组(传 [{"text": "..."}] 对象数组会返回 400)。
不可为空数组。建议单请求 ≤ 100 条。
返回前 N 条。省略、传 0 或负数都返回全部。 必须是整数,传字符串返回 400。 不影响用量 —— 所有候选文档都会过一遍模型。
範例:
2
是否在结果中回显文档原文。
注意:当前通道该参数不生效,无论传什么都会回显 document.text。
对带宽敏感的场景请自行按 index 回填,不要依赖此开关裁剪响应体。
範例:
true
這個頁面有幫助嗎?
⌘I