文本重排序 - Cohere 兼容格式

接口概述

兼容 Cohere Rerank API 格式：给定查询（query）与候选文档列表（documents），输出按相关性从高到低排列的结果，常用于搜索引擎与 RAG 场景的精排。

本页只讲扁平体（query 与 documents 直接放在顶层）。另一种嵌套体写法（input.query + input.documents）见「重排序-DashScope 格式」页——两者是同一个地址、不同报文，按所选模型的原生格式提交即可。

接口地址

POST https://test.jw-info.com/v1/rerank

请求头

请求头	是否必填	说明
Content-Type	是	固定为 `application/json`
Authorization	是	`Bearer {API_KEY}`；也可用 `x-api-key: {API_KEY}`

请求参数

参数名	类型	是否必填	默认值	说明
model	string	是	-	模型名称，见「可用模型」
query	string	是	-	查询文本（例如用户搜索词）
documents	array	是	-	待排序的文档列表，每个元素为一个文档文本（字符串）
top_n	integer	否	全部	只返回最相关的前 N 条（N 需小于文档数量）
return_documents	boolean	否	true	是否在结果里带回原始文档文本
max_chunks_per_doc	integer	否	模型默认	每个文档的最大分块数

请求示例

最简请求：

{
  "model": "qwen3-rerank",
  "query": "什么是文本排序模型",
  "documents": [
    "文本排序模型广泛用于搜索引擎和推荐系统中",
    "量子计算是计算科学的一个前沿领域",
    "预训练语言模型的发展给文本排序模型带来了新的进展"
  ]
}

指定返回数量并带回原文：

{
  "model": "qwen3-rerank",
  "query": "什么是文本排序模型",
  "documents": [
    "文本排序模型广泛用于搜索引擎和推荐系统中",
    "量子计算是计算科学的一个前沿领域",
    "预训练语言模型的发展给文本排序模型带来了新的进展"
  ],
  "top_n": 2,
  "return_documents": true
}

curl https://test.jw-info.com/v1/rerank \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-rerank",
    "query": "什么是文本排序模型",
    "documents": ["文本排序模型用于搜索引擎", "量子计算是前沿领域"],
    "top_n": 2
  }'

响应参数

参数名	类型	说明
id	string	请求唯一标识
results	array	排序结果列表，按相关性降序
results[].index	integer	文档在原始 `documents` 数组中的索引
results[].relevance_score	float	相关性得分（0~1），越高越相关
results[].document	object	原始文档（`return_documents=true` 时返回）
results[].document.text	string	文档文本
usage.total_tokens	integer	用量统计（部分模型返回，按它计费）
meta	object	元信息（部分模型返回，如 `meta.api_version`、`meta.tokens`）

不同型号还会多带 model、object、created 之类的通用字段，取结果时看 results[] 即可。

响应示例

{
  "id": "rerank-abc123",
  "results": [
    {
      "index": 2,
      "relevance_score": 0.92,
      "document": { "text": "预训练语言模型的发展给文本排序模型带来了新的进展" }
    },
    {
      "index": 0,
      "relevance_score": 0.85,
      "document": { "text": "文本排序模型广泛用于搜索引擎和推荐系统中" }
    },
    {
      "index": 1,
      "relevance_score": 0.12,
      "document": { "text": "量子计算是计算科学的一个前沿领域" }
    }
  ],
  "meta": { "api_version": { "version": "1" } },
  "usage": { "total_tokens": 44 }
}

代码示例（Python）

import requests

BASE = "https://test.jw-info.com"
HEADERS = {
    "Content-Type": "application/json",
    "Authorization": "Bearer sk-你的密钥",
}


def rerank(query, documents, model="qwen3-rerank", top_n=None):
    payload = {"model": model, "query": query, "documents": documents,
               "return_documents": True}
    if top_n is not None:
        payload["top_n"] = top_n
    r = requests.post(f"{BASE}/v1/rerank", json=payload, headers=HEADERS)
    r.raise_for_status()
    data = r.json()
    for item in data["results"]:
        text = item.get("document", {}).get("text", "")
        print(item["index"], item["relevance_score"], text[:30])
    print("用量:", data.get("usage"))


rerank("什么是文本排序模型",
       ["文本排序模型用于搜索引擎", "量子计算是前沿领域"], top_n=2)

错误响应

参数不合法（模型名写错、缺少 query/documents 等）时返回错误对象：

{
  "error": {
    "message": "model is required",
    "type": "invalid_request_error",
    "code": "invalid_request_error"
  }
}

完整状态码与错误字段说明见「错误码」页。

可用模型

模型 ID	说明	备注
`qwen3-rerank`	通义千问重排序模型	标准 Cohere 兼容体
`bge-reranker-large`	BGE 重排序模型（Large）	同为扁平体；可另传 `truncate_prompt_tokens`（最大 token 数，范围 1~8192），响应里会多 `code`/`created`/`model` 字段
`bge-reranker-v2-m3`	BGE 重排序模型 v2-m3	同上

模型清单与上架状态以模型广场为准；gte-rerank-v2 走的是另一种嵌套体，见「重排序-DashScope 格式」页。

计费

按输入 tokens 计费（命中缓存的输入按缓存价、未命中按标准价；多数重排序模型只有输入腿）。每次调用的费用可在控制台「费用中心」查看，响应里不返回费用信息。

在模型广场查看支持「重排序」的模型 →