跳到主要内容

重排序

Rerank 请求会在应用将候选文档用于搜索、检索或 RAG 工作流前，根据查询对这些文档重新排序。

AISIX AI 网关暴露 POST /v1/rerank，让 rerank 流量可以与其它网关流量路径使用相同的调用方 API Key、模型别名、上游凭证和请求侧策略。

本指南将通过 AISIX 发送 rerank 请求，并说明该端点的服务提供方要求。

准备工作​

请先准备以下内容：

  • 一个可以处理代理请求的 AISIX 网关。
  • 一个可以访问该模型别名的调用方 API Key。
  • 一个配置服务提供方标签为 OpenAI、Cohere 或 Jina 的模型别名。

发送重排序请求​

通过网关代理发送 rerank 请求，并在请求体中使用 AISIX 模型别名：

curl -sS -X POST "http://127.0.0.1:3000/v1/rerank" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-prod",
    "query": "gateway docs",
    "documents": ["doc a", "doc b", "doc c"]
  }' \
  -o aisix-rerank-response.json

AISIX 会解析模型别名、检查调用方 API Key、对查询和文档文本执行受支持的输入策略检查，只将 model 字段改写为上游模型 ID，并将请求转发到上游 rerank 端点。

响应保持上游 rerank 响应形态：

{
  "results": [
    {
      "index": 1,
      "relevance_score": 0.95
    },
    {
      "index": 0,
      "relevance_score": 0.42
    },
    {
      "index": 2,
      "relevance_score": 0.18
    }
  ]
}

部分服务提供方会包含响应 ID、模型名称、用量或元数据等额外字段。

检查响应是否包含排序结果：

jq '.results | length' aisix-rerank-response.json

命令应输出返回结果数量：

3

服务提供方要求​

只有当解析出的模型配置为 OpenAI、Cohere 或 Jina 服务提供方标签时，AISIX 才会接受 rerank 请求。这些服务提供方适配器共享 model、query 和 documents 等通用 rerank 字段。可选 rerank 字段会原样转发，不会跨服务提供方标准化。

当解析出的模型使用其它服务提供方标签时，AISIX 会在发送到上游前返回 400，避免将 rerank 请求发送到不使用预期 rerank 格式的服务提供方路由。

Voyage AI 也暴露 rerank API，但其请求和响应字段与当前受支持的 rerank 格式不同。AISIX 需要专门适配器后才会将其视为兼容。

对于 Cohere 和 Jina，请根据服务提供方参考文档配置服务提供方密钥的 base URL。AISIX 会追加 rerank 路径，并在 base URL 已以版本前缀结尾时避免重复追加常见 API 版本片段。

重排序行为​

AISIX 转发请求体时只改写 model 字段，不会添加 Chat Completions 字段，也不会转换服务提供方专属 rerank 参数。

输入安全护栏可以在 AISIX 调用服务提供方之前检查 query 和文档文本。输出安全护栏不会检查该路径上的重排序响应内容，因为响应包含的是排序结果，而不是生成文本。

成功的 rerank 响应会以原上游内容类型和字节返回。AISIX 只会尽力解析用量用于遥测；如果用量缺失或格式无法识别，AISIX 仍会原样返回上游响应。

如果安全护栏没有阻断请求，请检查已配置安全护栏是否能检查 query 或文档文本。如果请求在到达服务提供方前返回 400，请检查解析出的模型服务提供方标签。如果上游返回 404，请检查服务提供方密钥的 base URL。

下一步​

你已经了解 AISIX 如何代理 rerank 请求，以及为什么该能力对服务提供方支持保持较窄范围。接下来请阅读图像生成，了解另一类服务提供方专属端点。