跳到主要内容
版本：1.6.0

重排序

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

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

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

准备工作​

请先准备以下内容：

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

导出网关连接和请求值：

# AISIX_PROXY 不含尾部斜杠或 /v1 等端点路径
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="rerank-prod"

发送重排序请求​

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

curl -sS -X POST "${AISIX_PROXY}/v1/rerank" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "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 需要专门适配器后才会将其视为兼容。

对于 Jina，请根据服务提供方参考文档配置服务提供方密钥的 base URL。AISIX 会追加 rerank 路径，并在 base URL 已以版本前缀结尾时避免重复追加常见 API 版本片段。对于 Cohere，无论 base URL 是裸主机地址还是兼容性 API 基础地址，AISIX 都会把 rerank 发到 base URL 主机根地址下的原生 /v2/rerank 端点。请参阅 AISIX 如何构造 Cohere URL。

重排序行为​

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

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

成功的 rerank 响应会以原上游内容类型和字节返回，只有一处例外：当上游响应在顶层携带 model 字段时，AISIX 会将其改写为请求所使用的模型别名，使响应中的模型名称与调用方请求的一致，而不是上游模型 ID；顶层不含 model 字段的响应不会被添加该字段，嵌套在响应其它位置的模型名称也会保持服务提供方写入的原值。AISIX 只会尽力解析用量用于遥测；如果用量缺失或格式无法识别，AISIX 仍会原样返回上游响应的其余部分。

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

下一步​

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