Cohere 重排序格式（Rerank）

重要提示 cohere 的 Rerank 模型接口和 Jina的Rerank模型接口格式是一样的。

官方文档

Cohere Rerank

📝 简介

给定查询和文本列表，重排序API将根据与查询的相关性对文本进行排序。每个文本都会被分配一个相关性分数，从而产生一个有序的数组结果。此功能特别适用于搜索和检索应用，可以优化文档的排序，帮助用户更快找到相关信息。

💡 请求示例

基础重排序请求 ✅

curl https://$Burncloud_API_BaseUrl/v1/rerank \
  -H "Authorization: Bearer $Burncloud_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://$Burncloud_API_BaseUrl/v1/rerank \
  -H "Authorization: Bearer $Burncloud_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 $Burncloud_API_KEY

其中 $Burncloud_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倍。相关性分数是一个相对指标，用于排序，而非绝对比较。

Revision #3
Created 14 August 2025 06:11:27 by Burncloud
Updated 19 August 2025 04:33:42 by Burncloud