UOUODUO AI Gateway

API

Rerank

根据查询对候选文档重新排序，适用于 RAG、搜索和召回结果精排。

概述

Rerank 接口接收一个查询和一组候选文档，返回按相关性排序的结果。它适合放在向量召回之后，用于提升搜索、问答和推荐的最终排序质量。

请求

`POST https://api.example.com/v1/rerank`

Headers

Header	必需	说明
Authorization	✓	`Bearer $UOUODUO_API_KEY`
Content-Type	✓	`application/json`

Body 参数

参数	类型	必需	默认	说明
model	string	✓	-	rerank 模型 ID
query	string	✓	-	查询文本
documents	array<string 或 object>	✓	-	待排序文档
top_n	integer	否	全量	只返回前 N 条
return_documents	boolean	否	false	是否在响应里带回文档内容
max_tokens_per_doc	integer	否	模型默认	每篇文档截断 token 上限，若模型支持

示例

curl https://api.example.com/v1/rerank \
  -H "Authorization: Bearer $UOUODUO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-english-v2.0",
    "query": "如何排查 429 限流",
    "documents": [
      "429 通常表示请求频率或 token 使用超过限制。",
      "401 表示 API key 无效。",
      "图像生成接口支持 size 和 quality 参数。"
    ],
    "top_n": 2,
    "return_documents": true
  }'

响应

字段	类型	说明
id	string	请求 ID
results	array<object>	排序结果
results[].index	integer	原始 documents 中的索引
results[].relevance_score	number	相关性分数，通常 0 到 1
results[].document	object 或 string	`return_documents=true` 时返回
meta	object	上游元信息

{
  "id": "rerank_abc",
  "results": [
    { "index": 0, "relevance_score": 0.97, "document": "429 通常表示..." },
    { "index": 1, "relevance_score": 0.12, "document": "401 表示..." }
  ],
  "meta": {}
}

错误

HTTP	说明	处理建议
400	documents 为空、query 为空或文档过长	限制候选数量并截断长文档
401	API key 无效	重新创建 key
429	rerank 模型限流	降低并发或使用队列
500	上游 rerank 服务异常	fallback 到向量召回排序

注意事项

不要把上千篇长文档直接丢给 rerank；先用 embedding 或 BM25 做粗召回。
如果文档是结构化对象，建议序列化成稳定的 YAML 或短文本。
Rerank 分数只适合在同一次请求内比较，不建议跨请求直接排序。