檢索系統在“召回”階段為保證效率,返回的結果可能不夠精準。排序模型能對召回的文檔進行二次精準排序,確保將與使用者查詢最相關的結果排在最前,有效提升應用準確率。
模型概覽
重要gte-rerank模型將於2026年05月30日下線,推薦使用qwen3-rerank模型替代。
新加坡
模型名稱 | 最大文檔數 | 單條最大輸入Token | 請求最大輸入Token | 語種支援 | 應用情境 |
|---|---|---|---|---|---|
qwen3-rerank | 500 | 4,000 | 120,000 | 中文、英語、西班牙語、法語、葡萄牙語、印尼語、日語、韓語、德語、俄羅斯語等100+主流語種 |
|
北京
模型名稱 | 最大文檔數 | 單條最大輸入Token | 請求最大輸入Token | 語種支援 | 應用情境 |
|---|---|---|---|---|---|
qwen3-rerank | 500 | 4,000 | 120,000 | 中文、英語、西班牙語、法語、葡萄牙語、印尼語、日語、韓語、德語、俄羅斯語等100+主流語種 |
|
qwen3-vl-rerank | 文本:100 圖片:40 視頻:4 | 8,000 | 120,000 | 中、英、日、韓、法、德等33種主流語言 |
|
gte-rerank-v2 | 500 | 4,000 | 30,000 | 中、英、日、韓、泰語、西、法、葡、德、印尼語、阿拉伯語等50餘語種 |
|
- 單條最大輸入Token:每個Query或Document的最大Token數量。單條 Query 或 Document 的輸入超過該限制時,API 會傳回 HTTP 400 錯誤,不會截斷輸入內容。
- 單次請求最大文檔數:單次請求允許的最大文檔數量。對於 qwen3-vl-rerank 模型,該限制會根據文件類型(文本、圖片、視頻、混合模態)的不同而有所差異。
- 請求最大輸入Token:計算公式為
Query Tokens × Document 數量 + Document Tokens 總和,該值不得超過請求最大輸入Token。
輸入格式限制:
模型 | 圖片 | 視頻 |
|---|---|---|
qwen3-vl-rerank | JPEG, PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS, SGI(支援URL或Base64) | MP4, AVI, MOV(僅支援URL) |
前提條件
您需要已擷取 API Key並配置API Key到環境變數DASHSCOPE_API_KEY。如果通過SDK調用,還需要安裝DashScope SDK。
HTTP調用
調用時請將{WorkspaceId}替換為真實的業務空間ID。
本節介紹 DashScope HTTP 介面。
qwen3-rerank和qwen3.7-text-rerank還支援 OpenAI 相容介面,參見OpenAI 相容介面。
請求要求標頭(Headers)Content-Type 請求內容類型。此參數必須設定為 Authorization 請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值:Bearer sk-xxxx。 請求體(Request Body)model 模型名稱。支援的模型:qwen3-rerank、gte-rerank-v2、qwen3-vl-rerank。 input 輸入內容。
parameters 選擇性參數。
| qwen3-rerank
qwen3-vl-rerank文字查詢 圖片查詢 gte-rerank-v2 |
響應request_id 請求唯一標識。可用於請求明細溯源和問題排查。 output 任務輸出資訊。 usage 輸出資訊統計。 code 請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤碼。 message 請求失敗的詳細資料。請求成功時不會返回此參數,詳情請參見錯誤碼。 | 成功響應失敗響應在訪問請求出錯的情況下,輸出的結果中會通過 |
OpenAI 相容介面
qwen3-rerank和qwen3.7-text-rerank支援透過 OpenAI 相容介面調用;gte-rerank-v2和qwen3-vl-rerank不支援,調用時會返回model_not_supported錯誤。
請求地址:POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-api/v1/reranks
與 DashScope HTTP 介面的差異:
- 請求體為扁平結構,
query、documents、top_n、instruct、return_documents與model同級,不巢狀於input和parameters中。 - 排序結果位於響應的
results陣列中,每項包含index(文件在請求中的序號)和relevance_score(相關性得分);return_documents為true時額外返回document.text。
請求示例
curl --request POST \
--url https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-api/v1/reranks \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "qwen3-rerank",
"query": "什麼是重排序模型",
"documents": [
"重排序模型廣泛應用於搜尋引擎和推薦系統",
"量子計算是計算科學的前沿領域"
],
"top_n": 2,
"return_documents": true
}'
響應示例
{
"object": "list",
"results": [
{
"document": {
"text": "重排序模型廣泛應用於搜尋引擎和推薦系統"
},
"index": 0,
"relevance_score": 0.7597635537722445
},
{
"document": {
"text": "量子計算是計算科學的前沿領域"
},
"index": 1,
"relevance_score": 0.26261397125850783
}
],
"model": "qwen3-rerank",
"id": "d754cead-2de8-9dc8-89cb-0171b84d0ea0",
"usage": {
"total_tokens": 65
}
}
Python 和 Node.js 調用示例請參見重排序。
SDK調用
調用樣本
以下樣本展示了調用文檔排序模型API的程式碼範例。
SDK 的參數命名與HTTP介面基本一致,參數結構進行了一定封裝。比如 HTTP 使用嵌套的
input和parameters結構,但SDK 使用扁平參數。請在開發時注意區分。
import os
import dashscope
# 以下為華北2(北京)地區的配置,調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區的region取值不同。
client = dashscope.Client(
# 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
# 各地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
def text_rerank():
resp = client.rerank.create(
model="gte-rerank-v2",
query="什麼是文本排序模型",
documents=[
"文本排序模型廣泛用於搜尋引擎和推薦系統中,它們根據文本相關性對候選文本進行排序",
"量子計算是計算科學的一個前沿領域",
"預訓練語言模型的發展給文本排序模型帶來了新的進展"
],
top_n=2,
return_documents=True
)
print(resp)
if __name__ == '__main__':
text_rerank()
以下樣本展示了使用qwen3-vl-rerank模型進行多模態排序(以圖片作為查詢)的程式碼範例。
import os
import dashscope
import json
# 以下為華北2(北京)地區的配置,調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區的region取值不同。
client = dashscope.Client(
# 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
# 各地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
def vl_rerank():
resp = client.rerank.create(
model="qwen3-vl-rerank",
query={"image": "https://img.alicdn.com/imgextra/i3/O1CN01rdstgY1uiZWt8gqSL_!!6000000006071-0-tps-1970-356.jpg"},
documents=[
{"text": "文本排序模型廣泛用於搜尋引擎和推薦系統中,它們根據文本相關性對候選文本進行排序"},
{"image": "https://img.alicdn.com/imgextra/i3/O1CN01rdstgY1uiZWt8gqSL_!!6000000006071-0-tps-1970-356.jpg"},
{"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"}
],
top_n=2,
return_documents=True
)
print(json.dumps(resp.model_dump(), ensure_ascii=False, indent=4))
if __name__ == '__main__':
vl_rerank()
輸出樣本
說明SDK 2.0 返回結構化響應對象,排序結果通過 resp.results 訪問(resp.results[i].index / .relevance_score / .document);請求失敗時拋出 DashScopeError 異常。
{
"request_id": "4b0805c0-6b36-490d-8bc1-4365f4c89905",
"output": {
"results": [
{
"index": 0,
"relevance_score": 0.9334521178273196,
"document": {
"text": "文本排序模型廣泛用於搜尋引擎和推薦系統中,它們根據文本相關性對候選文本進行排序"
}
},
{
"index": 2,
"relevance_score": 0.34100082626411193,
"document": {
"text": "預訓練語言模型的發展給文本排序模型帶來了新的進展"
}
}
]
},
"usage": {
"total_tokens": 79
}
}
錯誤碼
如果模型調用失敗並返回報錯資訊,請參見錯誤碼進行解決。