创建重排序请求

本接口是融云提供的语义重排序服务接口，基于预训练模型对查询文本与候选文档的相关性进行精准排序，适用于搜索结果优化、推荐系统精排、信息检索等场景。通过灵活的参数配置和模型能力，可显著提升内容与用户意图的匹配精度。

请求方法

POST： <ai-api-base-url>/llm/v1/rerank

其中，<ai-api-base-url> 为您的 API Key 所属数据中心的域名：

• 北京数据中心：https://ai.rong-api.com
• 北美数据中心：https://ai.us-light-api.com

请求头参数

参数名	类型	必传	默认值	说明
Authorization	string	是	-	身份认证令牌，格式为 Bearer <your API key>，需替换为实际 API Key，用于验证用户权限。

正文参数

参数名	类型	是否必填	默认值	说明
model	enum	是	-	选择用于文档重排序的模型名称，仅支持融云官方发布模型，传入非平台模型将返回错误：“暂不支持此种模型”。平台将定期更新可用模型列表。
query	string	是	"Apple"	查询文本，用于对文档列表进行相关性排序。
documents	string[]	是	[]	待重排序的文档列表（仅支持字符串数组）。
top_n	integer	否	-	输出的结果数量（按相关性降序排列），未指定则返回所有文档。
return_documents	boolean	否	false	输出结果中是否包含原始文档文本： false（默认）：仅返回index(文档索引)和score(分数)； true：返回index(文档索引)、score(分数)及document(原始文本内容)。
max_chunks_per_doc	integer	否	1024	单个文档允许分割的最大块数。长文档会被分割为多个块进行计算，取最高分作为文档最终分数。
overlap_tokens	integer	否	80	文档分块时相邻块之间的 token 重叠数量（最大值为 80），确保语义连贯性。

请求示例

cURL

bash

   curl --request POST \
     --url <ai-api-base-url>/llm/v1/rerank \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --data '{
     "model": "Pro/BAAI/bge-reranker-v2-m3",
     "query": "Apple",
     "documents": [
       "apple",
       "banana",
       "fruit",
       "vegetable"
     ],
     "top_n": 4,
     "return_documents": false,
     "max_chunks_per_doc": 1024,
     "overlap_tokens": 80
   }'

Python

python

 import requests

 url = "<ai-api-base-url>/llm/v1/rerank"

 payload = {
     "model": "Pro/BAAI/bge-reranker-v2-m3",
     "query": "Apple",
     "documents": ["apple", "banana", "fruit", "vegetable"],
     "top_n": 4,
     "return_documents": False,
     "max_chunks_per_doc": 1024,
     "overlap_tokens": 80
 }
 headers = {
     "Authorization": "Bearer <token>",
     "Content-Type": "application/json"
 }

 response = requests.request("POST", url, json=payload, headers=headers)

 print(response.text)

JavaScript

JavaScript

 const options = {
   method: 'POST',
   headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
   body: '{"model":"Pro/BAAI/bge-reranker-v2-m3","query":"Apple","documents":["apple","banana","fruit","vegetable"],"top_n":4,"return_documents":false,"max_chunks_per_doc":1024,"overlap_tokens":80}'
 };

 fetch('<ai-api-base-url>/llm/v1/rerank', options)
   .then(response => response.json())
   .then(response => console.log(response))
   .catch(err => console.error(err));

响应参数

参数名	类型	是否必返	说明
id	string	是	本次请求的唯一标识符，用于追踪和调试。
tokens	object	是	token 使用统计信息，包含： prompt_tokens：查询和文档的总 token 数； total_tokens：处理过程中使用的总 token 数。
results	object[]	是	重排序结果列表，每个元素包含： document：原始文档文本（若输入参数 return_documents 设为 true）； score：相关性分数（降序排列）； index：文档在输入列表中的原始索引。

返回结果示例

JSON

  {
    "id": "<string>",
    "results": [
      {
        "document": {
          "text": "<string>"
        },
        "index": 123,
        "relevance_score": 123
      }
    ],
    "tokens": {
      "input_tokens": 123,
      "output_tokens": 123
    }
  }