POST/v1/rerank

重排序

根据 query 对候选 documents 进行相关性排序。

API Key application/json

统一 Rerank 协议

调用与返回说明

同步 POST /v1/rerank 接收一个 query 和候选 documents，返回按相关性排序的 results。模型、分数和可选字段由当前渠道决定。

请求时注意

先调用 GET /v1/models，使用当前 API Key 返回且支持 Rerank 的完整模型 ID；官方模型目录不等于本站分组权限。
当前 New API DTO 校验 query 非空、documents 非空数组；不能把 SiliconFlow 官方多模态对象示例直接套到本站入口。
当前 DTO 字段是 instruct 和 max_chunk_per_doc；官方 SiliconFlow 页面使用 instruction 和 max_chunks_per_doc。除非已确认渠道映射，否则不要替换字段名。
Rerank 不支持流式或异步任务；不要等待 [DONE]、task_id 或下载 URL。

返回时注意

成功响应由宿主归一化为 results 与 usage；results[].index 才是原始候选文档的位置。
只有 return_documents=true 或渠道返回文档时才读取 results[].document；缺少该字段不表示排序失败。
relevance_score 是模型相关性分数，不要跨模型、版本或渠道设定同一个绝对阈值。

Request

请求

/v1/rerank

Body

必填

Bodyobject

modelstring必填

当前 API Key 可用且支持 Rerank 的完整模型 ID。

示例BAAI/bge-reranker-v2-m3

querystring必填

非空查询文本；当前统一 DTO 不确认对象形式。

长度：1–∞

示例什么是文本排序模型？

documentsarray<string>必填

候选文档数组。当前入口按数组解码，数组元素由上游渠道决定，文本模型使用字符串元素。

元素数量：1–∞

示例["文本排序模型根据相关性对候选文本排序","量子计算是计算科学的前沿领域"]

元素array<string>必填

至少一个候选文档。结果中的 index 回指此数组。

示例文本排序模型根据相关性排序

top_ninteger

最多返回数量，必须 ≥ 1。

范围：[1，+∞

示例2

return_documentsboolean

是否回显文档内容；需要稳定响应时显式设置。

默认：false

示例true

instructstring

当前 New API DTO 字段；只在目标模型/渠道明确支持时发送。

长度：1–∞

示例优先返回能够直接回答问题的文档

max_chunk_per_docinteger

当前 DTO 字段；官方 SiliconFlow 为 max_chunks_per_doc，字段映射需另行确认。

默认：1024范围：[1，+∞

示例1024

overlap_tokensinteger

切片重叠数量，常见范围 0–80。

范围：[0，80]

示例20

路径、查询与 Header 参数

参数	位置	类型	必填	说明	示例
`Authorization`	Header	string	是	必填。使用青云TOP API 的 API Key，保留 Bearer 后的空格。	Bearer YOUR_API_KEY
`Content-Type`	Header	string	是	固定为 application/json。	application/json
`X-Trace-Id`	Header	string	否	可选的客户端追踪标识；是否透传取决于渠道。	-

请求示例application/json

curl -X POST https://top.qingyuntop.ai/v1/rerank \
  -H "Authorization: Bearer ${QINGYUN_TOP_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "BAAI/bge-reranker-v2-m3",
  "query": "什么是文本排序模型？",
  "documents": [
    "文本排序模型根据查询与候选文档的相关性重新排序。",
    "量子计算是计算科学的一个前沿领域。",
    "预训练语言模型推动了文本检索和排序技术的发展。"
  ],
  "top_n": 2,
  "return_documents": true
}'

Response

返回响应 `200`

返回按相关性排序的结果。

响应 200object

resultsarray<object>必填

按相关性分数排序后的结果。index 指向原 documents 数组中的位置。

元素array<object>必填

按相关性排序的结果数组。

indexinteger必填

原始 documents 的零基索引。

示例0

relevance_scorenumber必填

模型相关性分数，不跨模型比较绝对值。

示例0.9155

documentstring | object | array | null

return_documents=true 或渠道回显时出现。

usageobject必填

prompt_tokensinteger必填

输入 token 或渠道估算值。

completion_tokensinteger必填

输出 token；重排渠道通常为 0。

total_tokensinteger必填

归一化总 token 用量。

响应示例application/json

{
  "results": [
    {
      "index": 0,
      "document": {
        "text": "文本排序模型根据查询与候选文档的相关性重新排序。"
      },
      "relevance_score": 0.9155
    },
    {
      "index": 2,
      "relevance_score": 0.7577
    }
  ],
  "usage": {
    "prompt_tokens": 107,
    "completion_tokens": 0,
    "total_tokens": 107
  }
}

Response

返回响应 `400`

query 为空、documents 为空或字段类型不符合当前 DTO。

响应 400object

errorobject

messagestring

typestring

codestring

messagestring

codestring | number

Response

返回响应 `401`

API Key 缺失或无效。

响应 401object

errorobject

messagestring

typestring

codestring

messagestring

codestring | number

Response

返回响应 `403`

当前 API Key、分组或渠道不允许使用该模型。

响应 403object

errorobject

messagestring

typestring

codestring

messagestring

codestring | number

Response

返回响应 `429`

降低并发并按 Retry-After 或错误正文退避。

响应 429object

errorobject

messagestring

typestring

codestring

messagestring

codestring | number

统一 Rerank 协议

调用与返回说明

同步 POST /v1/rerank 接收一个 query 和候选 documents，返回按相关性排序的 results。模型、分数和可选字段由当前渠道决定。

请求时注意

先调用 GET /v1/models，使用当前 API Key 返回且支持 Rerank 的完整模型 ID；官方模型目录不等于本站分组权限。
当前 New API DTO 校验 query 非空、documents 非空数组；不能把 SiliconFlow 官方多模态对象示例直接套到本站入口。
当前 DTO 字段是 instruct 和 max_chunk_per_doc；官方 SiliconFlow 页面使用 instruction 和 max_chunks_per_doc。除非已确认渠道映射，否则不要替换字段名。
Rerank 不支持流式或异步任务；不要等待 [DONE]、task_id 或下载 URL。

返回时注意

成功响应由宿主归一化为 results 与 usage；results[].index 才是原始候选文档的位置。
只有 return_documents=true 或渠道返回文档时才读取 results[].document；缺少该字段不表示排序失败。
relevance_score 是模型相关性分数，不要跨模型、版本或渠道设定同一个绝对阈值。

重排序

调用与返回说明

请求时注意

返回时注意

请求

Body

路径、查询与 Header 参数

返回响应 200

返回响应 400

返回响应 401

返回响应 403

返回响应 429

调用与返回说明

请求时注意

返回时注意

返回响应 `200`

返回响应 `400`

返回响应 `401`

返回响应 `403`

返回响应 `429`