Cohere 重排序格式（Rerank）

重要提示

cohere 的 Rerank 模型介面和 Jina的Rerank模型介面格式是一樣的。

官方文件

📝 簡介

給定查詢和文字列表，重排序API將根據與查詢的相關性對文字進行排序。每個文字都會被分配一個相關性分數，從而產生一個有序的陣列結果。此功能特別適用於搜尋和檢索應用，可以最佳化文件的排序，幫助使用者更快找到相關資訊。

💡 請求示例

基礎重排序請求 ✅

curl https://88api.ai/v1/rerank \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-v3.5",
    "query": "什麼是美國的首都？",
    "documents": [
      "內華達州的首府是卡森城。",
      "北馬里亞納群島是太平洋上的一組島嶼，其首都是塞班島。",
      "華盛頓特區（也稱為華盛頓或特區，正式名稱為哥倫比亞特區）是美國的首都。",
      "英語語法中的大寫是在單詞開頭使用大寫字母。英語用法與其他語言的大寫不同。",
      "自美國成為一個國家之前，美國就存在死刑。截至2017年，在50個州中有30個州死刑合法。"
    ],
    "top_n": 3
  }'

響應示例:

{
  "results": [
    {
      "index": 2,
      "relevance_score": 0.999071
    },
    {
      "index": 0,
      "relevance_score": 0.32713068
    },
    {
      "index": 1,
      "relevance_score": 0.1867867
    }
  ],
  "id": "07734bd2-2473-4f07-94e1-0d9f0e6843cf",
  "meta": {
    "api_version": {
      "version": "2",
      "is_experimental": false
    },
    "billed_units": {
      "search_units": 1
    }
  }
}

使用結構化資料 ✅

curl https://88api.ai/v1/rerank \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-v3.5",
    "query": "尋找適合初學者的高價效比單反相機",
    "documents": [
      "型號: Canon EOS 800D\n價格: 4299元\n功能: 2410萬畫素, 光學取景器, Wi-Fi\n適合人群: 初學者, 愛好者",
      "型號: Nikon D3500\n價格: 3099元\n功能: 2416萬畫素, 光學取景器, 長達1550張的電池續航\n適合人群: 新手, 學生",
      "型號: Sony A7III\n價格: 12999元\n功能: 2420萬畫素, 全畫幅, 4K影片\n適合人群: 專業攝影師, 影片創作者"
    ],
    "max_tokens_per_doc": 512
  }'

響應示例:

{
  "results": [
    {
      "index": 1,
      "relevance_score": 0.918472
    },
    {
      "index": 0,
      "relevance_score": 0.854321
    },
    {
      "index": 2,
      "relevance_score": 0.423156
    }
  ],
  "id": "8f734bd2-2473-4f07-94e1-0d9f0e68ebfa",
  "meta": {
    "api_version": {
      "version": "2"
    },
    "billed_units": {
      "search_units": 1
    }
  }
}

📮 請求

端點

POST /v1/rerank

根據與查詢的相關性對文字列表進行重新排序。

鑑權方法

在請求頭中包含以下內容進行 API 金鑰認證：

Authorization: Bearer $API_KEY

其中 $API_KEY 是您的 API 金鑰。

請求頭引數

`X-Client-Name`

型別：字串
必需：否
說明：發起請求的專案名稱。

請求體引數

`model`

型別：字串
必需：是
說明：要使用的模型識別符號，例如 rerank-v3.5。

`query`

型別：字串
必需：是
說明：搜尋查詢文字。這是使用者輸入的問題或查詢內容。

`documents`

型別：字串陣列
必需：是
說明：將與查詢進行比較的文字列表。為獲得最佳效能，建議單個請求中不要傳送超過1,000個文件。
注意事項：
- 長文件將自動截斷為 max_tokens_per_doc 指定的值
- 結構化資料應格式化為YAML字串以獲得最佳效能

`top_n`

型別：整數
必需：否
說明：限制返回的重排結果數量。如果不指定，將返回所有重排結果。

`max_tokens_per_doc`

型別：整數
必需：否
預設值：4096
說明：長文件將自動截斷為指定的令牌數量。

📥 響應

成功響應

返回一個包含排序後文件列表的物件。

`results`

型別：物件陣列
說明：排序後的文件列表，按相關性降序排列
屬性：
- index: 整數，對應於原始文件列表中文件的索引
- relevance_score: 浮點數，相關性分數範圍為[0, 1]。接近1的分數表示與查詢高度相關，接近0的分數表示相關性較低

`id`

型別：字串
說明：請求的唯一識別符號

`meta`

型別：物件
說明：包含關於請求的後設資料
屬性：
- api_version: 物件，包含API版本資訊
  - version: 字串，API版本號
  - is_deprecated: 布林值，是否已棄用
  - is_experimental: 布林值，是否為實驗性功能
- billed_units: 物件，包含計費資訊
  - search_units: 浮點數，計費的搜尋單位數
- tokens: 物件，包含令牌使用統計
  - input_tokens: 浮點數，作為模型輸入的令牌數
  - output_tokens: 浮點數，模型產生的令牌數

`warnings`

型別：字串陣列
必需：否
說明：API返回的警告資訊

錯誤響應

當請求出現問題時，API可能返回以下HTTP狀態碼及相應錯誤：

400 Bad Request: 請求格式或引數錯誤
401 Unauthorized: 未提供有效的API金鑰
403 Forbidden: 沒有許可權訪問此資源
404 Not Found: 請求的資源不存在
422 Unprocessable Entity: 請求格式正確但包含語義錯誤
429 Too Many Requests: 請求頻率超過限制
500 Internal Server Error: 伺服器內部錯誤
503 Service Unavailable: 服務暫時不可用

🌟 最佳實踐

文件準備建議

文件長度：每個文件保持簡潔明瞭，避免過長。長文件會被自動截斷。
結構化資料：將結構化資料格式化為YAML字串，以獲得最佳效能。例如：
```
title: 產品名稱
price: 9999元
features:
  - 特性1
  - 特性2
```
文件數量：單次請求中不要超過1,000個文件，以獲得最佳效能。

查詢最佳化

明確具體：制定明確、具體的查詢，以獲得更準確的排序結果。
避免模糊查詢：儘量避免過於模糊或通用的查詢詞，這可能導致相關性分數差異不明顯。

理解相關性分數

相關性分數是歸一化到[0, 1]範圍內的值：

接近1的分數表示與查詢高度相關
接近0的分數表示相關性低

注意：不能簡單地認為分數0.9的文件比分數0.45的文件相關性高2倍。相關性分數是一個相對指標，用於排序，而非絕對比較。

目錄