Alibaba Cloud Model Studio：文本排序

檢索系統在“召回”階段為保證效率，返回的結果可能不夠精準。排序模型能對召回的文檔進行二次精準排序，確保將與使用者查詢最相關的結果排在最前，有效提升應用準確率。

模型概覽

• 單條最大輸入Token：每個Query或Document的最大Token數量。單條 Query 或 Document 的輸入超過該限制時，API 會傳回 HTTP 400 錯誤，不會截斷輸入內容。
• 單次請求最大文檔數：單次請求允許的最大文檔數量。對於 qwen3-vl-rerank 模型，該限制會根據文件類型（文本、圖片、視頻、混合模態）的不同而有所差異。
• 請求最大輸入Token：計算公式為 Query Tokens × Document 數量 + Document Tokens 總和，該值不得超過請求最大輸入Token。

輸入格式限制：

前提條件

您需要已擷取 API Key並配置API Key到環境變數DASHSCOPE_API_KEY。如果通過SDK調用，還需要安裝DashScope SDK。

HTTP調用

不同模型使用不同的API介面：

• qwen3-rerank：POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-api/v1/reranks
• qwen3-vl-rerank / gte-rerank-v2：POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank

調用時請將{WorkspaceId}替換為真實的業務空間ID。

兩種介面的請求體結構和響應格式不同，請參考對應模型的請求樣本和響應樣本。

curl --request POST \
  --url https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/reranks \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
        "model": "qwen3-rerank",
        "documents": [
                "文本排序模型廣泛用於搜尋引擎和推薦系統中，它們根據文本相關性對候選文本進行排序",
                "量子計算是計算科學的一個前沿領域",
                "預訓練語言模型的發展給文本排序模型帶來了新的進展"
        ],
        "query": "什麼是文本排序模型",
        "top_n": 2,
        "instruct": "Given a web search query, retrieve relevant passages that answer the query."
}'

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "qwen3-vl-rerank",
    "input":{
         "query": {"text": "什麼是文本排序模型"},
         "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"}
         ]
    },
    "parameters": {
        "return_documents": true,
        "top_n": 2,
        "fps": 1.0
    }
}'

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "qwen3-vl-rerank",
    "input":{
         "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"}
         ]
    },
    "parameters": {
        "return_documents": true,
        "top_n": 2,
        "fps": 1.0
    }
}'

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "gte-rerank-v2",
    "input":{
         "query": "什麼是文本排序模型",
         "documents": [
         "文本排序模型廣泛用於搜尋引擎和推薦系統中，它們根據文本相關性對候選文本進行排序",
         "量子計算是計算科學的一個前沿領域",
         "預訓練語言模型的發展給文本排序模型帶來了新的進展"
         ]
    },
    "parameters": {
        "return_documents": true,
        "top_n": 2
    }
}'

{
    "object": "list",
    "results": [
        {
            "index": 0,
            "relevance_score": 0.9334521178273196
        },
        {
            "index": 2,
            "relevance_score": 0.34100082626411193
        }
    ],
    "model": "qwen3-rerank",
    "id": "85ba5752-1900-47d2-8896-23f99b13f6e1",
    "usage": {
        "total_tokens": 79
    }
}

{
    "output": {
        "results": [
            {
                "document": {
                    "text": "文本排序模型廣泛用於搜尋引擎和推薦系統中，它們根據文本相關性對候選文本進行排序"
                },
                "index": 0,
                "relevance_score": 0.9334521178273196
            },
            {
                "document": {
                    "text": "預訓練語言模型的發展給文本排序模型帶來了新的進展"
                },
                "index": 2,
                "relevance_score": 0.34100082626411193
            }
        ]
    },
    "usage": {
        "total_tokens": 79
    },
    "request_id": "85ba5752-1900-47d2-8896-23f99b13f6e1"
}

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1"
}

SDK調用

調用樣本

以下樣本展示了調用文檔排序模型API的程式碼範例。

SDK 的參數命名與HTTP介面基本一致，參數結構進行了一定封裝。比如 HTTP 使用嵌套的 input 和 parameters 結構，但SDK 使用扁平參數。請在開發時注意區分。

import dashscope
# 以下為華北2（北京）地區的配置，調用時請將{WorkspaceId}替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

def text_rerank():
    resp = dashscope.TextReRank.call(
        model="gte-rerank-v2",
        query="什麼是文本排序模型",
        documents=[
            "文本排序模型廣泛用於搜尋引擎和推薦系統中，它們根據文本相關性對候選文本進行排序",
            "量子計算是計算科學的一個前沿領域",
            "預訓練語言模型的發展給文本排序模型帶來了新的進展"
        ],
        top_n=2,
        return_documents=True
    )
    print(resp)

if __name__ == '__main__':
    text_rerank()

以下樣本展示了使用qwen3-vl-rerank模型進行多模態排序（以圖片作為查詢）的程式碼範例。

import dashscope
from http import HTTPStatus
import json
# 以下為華北2（北京）地區的配置，調用時請將{WorkspaceId}替換為真實的業務空間ID。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

def vl_rerank():
    resp = dashscope.TextReRank.call(
        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
    )
    if resp.status_code == HTTPStatus.OK:
        print(json.dumps(resp, default=str, ensure_ascii=False, indent=4))
    else:
        print(resp)

if __name__ == '__main__':
    vl_rerank()

輸出樣本

{
    "status_code": 200,
    "request_id": "4b0805c0-6b36-490d-8bc1-4365f4c89905",
    "code": "",
    "message": "",
    "output": {
        "results": [
            {
                "index": 0,
                "relevance_score": 0.9334521178273196,
                "document": {
                    "text": "文本排序模型廣泛用於搜尋引擎和推薦系統中，它們根據文本相關性對候選文本進行排序"
                }
            },
            {
                "index": 2,
                "relevance_score": 0.34100082626411193,
                "document": {
                    "text": "預訓練語言模型的發展給文本排序模型帶來了新的進展"
                }
            }
        ]
    },
    "usage": {
        "total_tokens": 79
    }
}

錯誤碼

如果模型調用失敗並返回報錯資訊，請參見錯誤碼進行解決。