重排序模型（Reranker）

1. 重排序模型（Reranker）

• https://aiping.cn/api/v1/rerank
• Note: 若用 SDK 封装，请保持 base_url 为 https://aiping.cn/api/v1，实际请求路径为 /rerank（SDK 需自行实现该方法或走 HTTP）
• 说明: 与主流 Rerank API 兼容（如 Cohere/SiliconFlow 等）；为实现多供应商路由/计费，扩展了 extra_body（请求）与 provider（响应）等字段

1.1 认证

Authorization

Bearer Token

在 Header 添加参数 Authorization ， 其值为在 Bearer 之后拼接 Token

示例:

Authorization: Bearer ********************

1.2 Body 参数

Body

modelstring必需

标准 Rerank 模型名，服务端会自动标准化大小写；需在标准 Rerank 模型目录内

querystring必需

查询文本

documentsarray必需

待重排的文档列表

top_ninteger可选

仅返回前 N 条结果，默认为供应商默认值或全部

可选值:

>0

return_documentsboolean可选

是否在结果中返回对应文档内容

可选值:

truefalse

默认值:

true

extra_bodyExtraBody可选

路由与策略控制等扩展字段

providerProvider必需

供应商选择/过滤/排序策略

onlyarray可选

白名单；仅在该集合内挑选供应商

可选值:

供应商

orderarray可选

供应商排序

可选值:

供应商

sortstringarray可选

排序策略，详见[路由策略] 支持多关键字排序，优先级按顺序降低。

可选值:

input_priceoutput_pricethroughputlatencyinput_length

input_price_rangearray可选

限制输入价格范围，单位： ¥ / 1M Token，如：[1,2]，表示筛选输入价格 price：1<=price<=2 的供应商

output_price_rangearray可选

限制输出价格范围，单位： ¥ / 1M Token

throughput_rangearray可选

限制吞吐范围，单位：tokens/s, 基于实时的吞吐数据调度

latency_rangearray可选

限制延迟范围，单位：s, 基于实时的延迟数据调度

input_length_rangearray可选

限制最大输入长度范围

allow_filter_prompt_lengthboolean可选

是否允许打开自动按照输入提示词长度筛选供应商，默认为 True

ignorearray可选

黑名单；从候选中排除

allow_fallbacksboolean可选

值为 True 时，系统按照用户指定筛选策略(延迟、吞吐、最大输入长度)无法找到合适的供应商时，为了保证接口可用，将按照指定排序策略调度给其他的供应商。默认为 True

enable_thinkingboolean可选

思考功能开关，接受该字段；在 Rerank 中不生效

可选值:

truefalse

consume_typestring可选

建议传 api，便于计费/追踪

可选值:

chatapi

默认值:

api

• 策略应用顺序：only → ignore → 各种范围过滤 → order → sort
• 冲突：only 与 ignore 不可交叉包含相同供应商（将返回 422）
• 指标依赖：范围/排序依赖实时指标（吞吐、时延、价格、输入长度能力）；无指标时可能跳过范围过滤或降级排序

1.3 请求格式示例（JSON）

{
  "model": "bge-reranker-v2-m3",
  "query": "什么是机器学习？",
  "documents": [
    "机器学习是人工智能的一个分支，它使计算机能够从数据中学习。",
    "深度学习是机器学习的一个子集，使用神经网络进行学习。",
    "Python是一种流行的编程语言，广泛用于数据科学。"
  ],
  "top_n": 2,
  "return_documents": true,
  "extra_body": {
    "provider": {
      "only": [],
      "ignore": [],
      "order": [],
      "sort": ["throughput"], // throughput/latency/input_price/output_price/input_length
      "input_price_range": [],
      "output_price_range": [],
      "throughput_range": [],
      "latency_range": [],
      "input_length_range": []
    },
    "consume_type": "api"
  }
}

1.4 返回格式

• 顶层字段

字段	类型	必填	描述
model	string	是	标准 Rerank 模型名（与请求对齐）
results	array[RerankResult]	是	重排结果列表
usage	object	否	{prompt_tokens, completion_tokens, total_tokens}；下游无提供时服务端可能估算，仅用于计费/统计
provider	string	否	实际路由到的供应商名

• RerankResult（results 内元素）

字段	类型	必填	描述
index	integer	是	文档在原始 documents 列表中的索引
relevance_score	number	是	相关性分值（越大越相关）
document	string	否	当 return_documents=true 时返回对应文档内容（服务端会将对象形态如 {"text": "..."} 规范化为字符串）

• 返回示例

{
  "model": "bge-reranker-v2-m3",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.92,
      "document": "机器学习是人工智能的一个分支，它使计算机能够从数据中学习。"
    },
    {
      "index": 1,
      "relevance_score": 0.76,
      "document": "深度学习是机器学习的一个子集，使用神经网络进行学习。"
    }
  ],
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 0,
    "total_tokens": 123
  },
  "provider": "某供应商A"
}

1.5 请求示例

Python requests

import requests
import json

headers = {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json",
}

payload = {
    "model": "bge-reranker-v2-m3",
    "query": "什么是机器学习？",
    "documents": [
        "机器学习是人工智能的一个分支，它使计算机能够从数据中学习。",
        "深度学习是机器学习的一个子集，使用神经网络进行学习。",
        "Python是一种流行的编程语言，广泛用于数据科学。"
    ],
    "top_n": 2,
    "return_documents": True,
    "extra_body": {
        "provider": {
            "only": [],
            "ignore": [],
            "order": [],
            "sort": ["throughput"],
            "input_price_range": [],
            "output_price_range": [],
            "input_length_range": [],
            "throughput_range": [],
            "latency_range": []
        },
        "consume_type": "api"
    }
}

response = requests.post(
    "https://aiping.cn/api/v1/rerank",
    headers=headers,
    json=payload,
    timeout=30
)

print(response.status_code)
print(json.dumps(response.json(), ensure_ascii=False, indent=2))

curl（非流式）

curl -N -X POST https://aiping.cn/api/v1/rerank \\
-H "Authorization: Bearer <API_KEY>" \\
-H "Content-Type: application/json" \\
-d '{
    "model": "bge-reranker-v2-m3",
    "query": "什么是机器学习？",
    "documents": [
        "机器学习是人工智能的一个分支，它使计算机能够从数据中学习。",
        "深度学习是机器学习的一个子集，使用神经网络进行学习。",
        "Python是一种流行的编程语言，广泛用于数据科学。"
    ],
    "top_n": 2,
    "return_documents": true,
    "extra_body": {
        "provider": {
            "only": [],
            "ignore": [],
            "order": [],
            "sort": ["throughput"],
            "input_price_range": [],
            "output_price_range": [],
            "input_length_range": [],
            "throughput_range": [],
            "latency_range": []
        },
        "consume_type": "api"
    }
}'

1.6 其他说明

• Rerank 不支持流式
• 模型名大小写不敏感（服务端自动标准化）；供应商名大小写敏感
• 响应的 usage 若下游未提供，服务端会基于请求内容估算输入 token（用于计费/统计），可能不会直接在响应中体现
• 个别供应商返回的 document 可能为对象（如 { "text": "..." }），服务端会规范化为字符串返回