通用文本排序模型API使用詳情 - Alibaba Cloud Model Studio

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

模型概覽

模型名稱	最大Document數量	單條最大輸入Token	請求最大輸入Token	語種支援	單價（每百萬輸入Token）	應用情境
gte-rerank-v2	500	4,000	30,000	中、英、日、韓、泰語、西、法、葡、德、印尼語、阿拉伯語等50餘語種	$0.115	文本語義檢索 RAG應用

單條最大輸入Token：每個Query或Document的最大Token數量為4,000。輸入內容超長將被截斷。API僅基於截斷後的內容計算，這可能導致排序結果不準確。
最大Document數量：每次請求中Document的最大數量為500。
請求最大輸入Token：每次請求中所有Query和Document的Token總數不得超過30,000。

前提條件

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

HTTP調用

POST https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-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": "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`（必選）模型名稱。支援的模型：gte-rerank-v2。
input `object` （必選）輸入內容。屬性 query `string`（必選）查詢文本。最大長度不能超過4,000個Token。 documents `array`（必選）待排序的候選文檔列表。每個元素是一個字串。最多包含500個文檔，每個文檔長度不超過4,000個Token。
parameters object （可選）選擇性參數。屬性 top_n `int`（可選）返回排序後的top_n個文檔。預設返回全部文檔。如果指定的值大於文檔總數，將返回全部文檔。 return_documents `bool`（可選）是否在排序結果中返迴文檔原文。預設值`false`，以減少網路傳輸開銷。

響應	成功響應 `{ "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()

輸出樣本

說明

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

錯誤碼

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

模型概覽

前提條件

HTTP調用

請求

文本排序

要求標頭（Headers）

請求體（Request Body）

響應

成功響應

失敗響應

SDK調用

調用樣本

輸出樣本

錯誤碼