使用API與SDK調用文本排序模型-大模型服務平台百鍊-阿里雲

模型概覽

新加坡

模型名稱

最大Document數量

單條最大輸入Token

請求最大輸入Token

語種支援

單價（每百萬Token）

免費額度

應用情境

qwen3-rerank

500

4,000

120,000

中文、英語、西班牙語、法語、葡萄牙語、印尼語、日語、韓語、德語、俄羅斯語等100+主流語種

$0.1

100萬Token

有效期間：百鍊開通後90天內

文本語義檢索
RAG應用

北京

模型名稱

最大Document數量

單條最大輸入Token

請求最大輸入Token

語種支援

單價（每百萬Token）

免費額度

應用情境

qwen3-vl-rerank

100

8,000

120,000

中、英、日、韓、法、德等33種主流語言

圖片：$0.258

文字：$0.1

無免費額度

映像聚類
跨模態搜尋
圖片檢索
視頻檢索

gte-rerank-v2

500

4,000

30,000

中、英、日、韓、泰語、西、法、葡、德、印尼語、阿拉伯語等50餘語種

$0.115

文本語義檢索
RAG應用

單條最大輸入Token：每個Query或Document的最大Token數量。輸入內容超長將被截斷。API僅基於截斷後的內容計算，這可能導致排序結果不準確。
最大Document數量：每次請求中Document的最大數量。
請求最大輸入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調用

POST https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank

請求	qwen3-rerank curl --request POST \ --url https://dashscope-intl.aliyuncs.com/compatible-api/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." }' qwen3-vl-rerank 文字查詢 curl --location 'https://dashscope.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://dashscope.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 } }' gte-rerank-v2 curl --location 'https://dashscope.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 } }'
要求標頭（Headers）
Content-Type `string` （必選）請求內容類型。此參數必須設定為`application/json`。
Authorization `string`（必選）請求身份認證。介面使用阿里雲百鍊API-Key進行身份認證。樣本值：Bearer sk-xxxx。
請求體（Request Body）
model `string`（必選）模型名稱。支援的模型：qwen3-rerank、gte-rerank-v2、qwen3-vl-rerank。
input `object` （必選）輸入內容。當使用 `qwen3-rerank` 模型時，無需使用 `input` 對象參數。此時，`query` 和 documents 參數需與 `model` 等參數位於同一層級。屬性 query `string \| object`（必選）查詢內容。最大長度不能超過4,000個Token。當使用`qwen3-vl-rerank`模型時，`query`支援以下兩種格式：字串格式：直接傳入文本字串，例如`"query": "什麼是文本排序模型"`。對象格式：傳入字典指定模態類型和值，格式為`{"模態類型": "輸入內容"}`。支援`text`和`image`兩種模態類型。文字查詢：`"query": {"text": "什麼是文本排序模型"}` 圖片查詢：`"query": {"image": "圖片URL或Base64"}` documents `array`（必選）待排序的候選文檔列表。每個元素是一個字串。當使用`qwen3-vl-rerank`模型時，每個元素是一個字典或者字串，用於指定內容的類型和值。格式為{"模態類型": "輸入字串或映像、視頻url"}。支援`text`, `image`, `video`三種模態類型。文本：key為`text`。value為字串形式。也可不通過dict直接傳入字串。圖片：key為`image`。value可以是公開可訪問的URL，或Base64編碼的Data URI。Base64格式為 `data:image/{format};base64,{data}`，其中 `{format}` 是圖片格式（如 `jpeg`、`png`），`{data}` 是Base64編碼字串。視頻：key為`video`，value必須是公開可訪問的URL。
parameters object （可選）選擇性參數。當使用 `qwen3-rerank` 模型時，無需使用 `parameters` 對象參數。此時，`top_n` 和 `instruct` 參數需與 `model` 等參數位於同一層級。屬性 top_n `int`（可選）返回排序後的top_n個文檔。預設返回全部文檔。如果指定的值大於文檔總數，將返回全部文檔。 return_documents `bool`（可選）是否在排序結果中返迴文檔原文。預設值`false`，以減少網路傳輸開銷。支援的模型：`gte-rerank-v2`、`qwen3-vl-rerank`。 instruct `string` 可選添加自訂排序任務類型說明，僅在使用 `qwen3-rerank` 及`qwen3-vl-rerank`模型時生效。通過該參數可以指導模型採用不同的排序策略，例如：問答檢索任務（預設）：`"Given a web search query, retrieve relevant passages that answer the query."` 側重點：尋找問題的答案。模型會優先評估文檔是否解答了Query中的問題。樣本：對於Query“如何預防感冒？”，文檔“勤洗手是預防感冒的有效方法”會獲得高分；而文檔“感冒是一種常見疾病”雖然主題相關，但因未提供答案，得分會顯著更低。語義相似性排序任務：`"Retrieve semantically similar text."` 側重點：判斷語義的等價性。模型會評估Query和文檔的核心含義是否一致，而不管具體措辭或句式。樣本：在FAQ情境中，使用者Query“如何修改密碼？”與候選問題“忘記密碼怎麼辦？”在語義上高度相似，應獲得高分。模型會關注兩者是否指向同一個使用者意圖。建議使用英文撰寫。如不指定該參數，將預設按問答檢索任務進行排序。更多任務指令可參考模型倉庫中的樣本。 fps `float` 可選僅`qwen3-vl-rerank`模型支援此參數。控制視頻的幀數，比例越小，實際抽取的幀數越少，範圍為 [0,1]。預設值為1.0。

響應	成功響應 `{ "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`和`message`指明出錯原因。 `{ "code":"InvalidApiKey", "message":"Invalid API-key provided.", "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1" }`
request_id `string` 請求唯一標識。可用於請求明細溯源和問題排查。
output `object` 任務輸出資訊。屬性 results `array` 排序結果清單。按 `relevance_score` 從高到低排列。屬性 document `dict` 文檔原文對象。僅在請求參數 `return_documents` 為 `true` 時返回。結構為 `{"text": "文檔原文"}`。 index `int` 表示該結果對應於輸入 `documents` 列表中的原始索引位置。 relevance_score `double` 該文檔與查詢的語義相關性得分，取值範圍為 0.0 到 1.0。分數越高，相關性越強。說明此分數為當前請求中的相對分數，主要用於對本次請求內的文檔排序，不可作為跨請求比較的絕對值。
usage `object` 輸出資訊統計。屬性 total_tokens `int` 本次請求消耗的總 Token 數量。
code `string` 請求失敗的錯誤碼。請求成功時不會返回此參數，詳情請參見錯誤資訊。
message `string` 請求失敗的詳細資料。請求成功時不會返回此參數，詳情請參見錯誤資訊。

SDK調用

調用樣本

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

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

Python

import dashscope

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模型進行多模態排序（以圖片作為查詢）的程式碼範例。

Python

import dashscope
from http import HTTPStatus
import json

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()

輸出樣本

說明

SDK對原始HTTP響應進行了封裝，成功時會固定返回code和message欄位，值為空白字串。

{
    "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
    }
}

錯誤碼

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