TokenLab

文字

重新排序文件

依據與查詢的關聯性對文件進行重新排序

POST
/v1/rerank

使用 GET /v1/models?recommended_for=rerank 列出目前的重新排序模型。請使用其詳細資訊中列有 rerank 操作的模型。

使用語意相似度模型對文件進行重新排序。適用於改善搜尋結果與 RAG 應用。

請求主體 (Request Body)

此端點會在排序完成後返回。對於大型文件集,請將您的 HTTP 客戶端逾時時間設定為至少 120s。

modelstring必填

要使用的重新排序模型 ID(例如:qwen3-vl-rerank)。

querystring必填

用於對文件進行排序的查詢字串。長度上限:32,000 個字元。

documentsarray必填

要重新排序的文件清單(字串陣列)。限制:最多 1,000 份文件,每份文件最多 100,000 個字元,且文件總字元數最多 2,000,000 個字元。

top_ninteger

要返回的前幾名結果數量,範圍從 1 到 documents.length。若省略,則由所選模型決定結果數量。

return_documentsboolean預設值: false

是否在每個結果中包含原始文件文字。僅在模型詳細資訊中列有 return_documents 時才傳送此參數。

回應 (Response)

resultsarray

排序後的文件清單及其分數。

每個結果包含:

  • index (integer):原始文件索引
  • relevance_score (number):關聯性分數。其範圍取決於所選模型。
  • document (string):原始文字(若 return_documents=true)
modelstring

用於重新排序的模型(若可用)。

usageobject

請求所報告的用量(若可用):total_tokens,或按搜尋次數計費的模型之 search_units。

請求

curl -X POST "https://api.tokenlab.sh/v1/rerank" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-vl-rerank",
    "query": "What is machine learning?",
    "documents": [
      "Machine learning is a subset of AI",
      "The weather is nice today",
      "Deep learning uses neural networks"
    ],
    "top_n": 2,
    "return_documents": true
  }'

回應

Response
{
  "results": [
    {
      "index": 0,
      "relevance_score": 0.95,
      "document": "Machine learning is a subset of AI"
    },
    {
      "index": 2,
      "relevance_score": 0.82,
      "document": "Deep learning uses neural networks"
    }
  ],
  "model": "qwen3-vl-rerank",
  "usage": {
    "total_tokens": 45
  }
}

錯誤 (Errors)

狀態代碼原因
400invalid_request欄位缺失、為空或超過上述限制。param 會指出該欄位
400unsupported_endpoint此模型尚未針對此端點發布

其他狀態的處理方式請參閱處理 API 錯誤。

授權

BearerAuth
AuthorizationBearer <token>

API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。

位置: header

請求標頭

X-TokenLab-Delivery-Policy?string

單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified,並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。

可選值

  • "auto"
  • "verified"
  • "official"

請求主體

application/json

回應

application/json

application/json

application/json

application/json

application/json

application/json

application/json