帮你快速理解、总结文档立即下载
文档中心>模型路由>操作指南>模型接入指南>重排序模型

重排序模型

最近更新时间：2026-10-21 11:21:24
本文档已由 AI 辅助审校
我的收藏

本页目录：

概述

CMR Rerank API 根据查询内容，对一组候选内容进行相关性排序，适用于搜索结果优化、知识库检索等场景。使用统一的接口和 CMR API Key，即可调用不同厂商的 Rerank 模型。排序结果和分数由所选模型提供。文本、图片、视频使用同一个接口：
POST /v1/rerank
请求形式
查询内容 query
候选列表 documents
文本重排
一段文本
多段文本
图片查询
一张图片
文本、图片或视频候选
视频查询
一个视频
文本、图片或视频候选
混合候选重排
文本、图片或视频
包含不同内容类型的候选列表
图片、视频和混合候选是否可用，以所选模型的支持情况为准。每次请求只提供一份查询，每条候选只包含一段文本、一张图片或一个视频。

前提条件

1. 建议提前阅读 使用约束 与 支持的模型提供商 了解相关信息。
2. 已创建模型路由实例，详细操作指导请参见 创建模型路由实例。
3. 已创建 BYOK 实例，详细操作指导请参见 创建 BYOK 实例。
4. 已创建模型路由访问密钥（API Key），详细操作指导请参见 创建模型路由访问密钥。
5. 已完成重排序模型关联和模型路由策略配置，详细操作指导请参见 配置模型调度管理。

接口地址与鉴权

请求地址

POST {CMR_BASE_URL}/v1/rerank
CMR_BASE_URL 为控制台展示的实例访问地址。请求使用 CMR 模型名称和 CMR API Key，无需填写厂商的接口地址或 API Key。

请求头

Header
必填
说明
Authorization
是
Bearer <CMR_API_KEY>
Content-Type
是
固定为 application/json

快速开始

将示例中的访问地址、API Key 和模型名称替换为自己的配置。

cURL

curl --request POST "${CMR_BASE_URL}/v1/rerank" \\
  --header "Authorization: Bearer ${CMR_API_KEY}" \\
  --header "Content-Type: application/json" \\
  --data '{
    "model": "cmr-text-rerank",
    "query": "如何安装产品？",
    "documents": [
      "产品退款规则。",
      "先固定底座，再连接电源。"
    ]
  }'

Python

import os
import requests

documents = [
    "产品退款规则。",
    "先固定底座，再连接电源。",
]

response = requests.post(
    f"{os.environ['CMR_BASE_URL']}/v1/rerank",
    headers={
        "Authorization": f"Bearer {os.environ['CMR_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "cmr-text-rerank",
        "query": "如何安装产品？",
        "documents": documents,
    },
    timeout=30,
)
response.raise_for_status()

for item in response.json()["results"]:
    print(item["relevance_score"], documents[item["index"]])

请求参数

基本请求参数

参数
类型
必填
说明
model
string
是
CMR 模型名称或模型别名，可用值以控制台关联模型为准
query
string | object
是
本次查询。文本填字符串，图片填 {"image":"..."}，视频填 {"video":"..."}
documents
array
是
待排序的候选列表。每项可以是文本字符串、图片对象或视频对象
top_n
integer
否
请求返回相关性最高的前 N 条。取值范围和未填写时的行为以所选模型为准
return_documents
boolean
否
是否请求模型返回候选内容。实际是否返回，取决于模型
instruct
string
否
排序要求，例如“优先选择提供具体安装步骤的内容”
选填参数是否生效取决于所选模型。未填写的选填参数，CMR 不自动补默认值。

文本输入

query 和文本候选直接填写字符串，最简请求见快速开始。下面演示所选模型支持时，如何添加选填参数来限制结果数量、请求返回候选内容和指定排序要求：
{
  "model": "cmr-text-rerank",
  "query": "如何安装产品？",
  "documents": [
    "产品退款规则。",
    "先固定底座，再连接电源。"
  ],
  "top_n": 1,
  "return_documents": true,
  "instruct": "优先选择提供具体安装步骤的内容。"
}

图片和视频输入

内容
填写格式
可填写的位置
文本
"安装步骤"
query 或 documents[]
图片
{"image":"图片 URL 或 Data URI"}
query 或 documents[]
视频
{"video":"视频 URL"}
query 或 documents[]
图片查询与混合候选示例：
{
  "model": "cmr-multimodal-rerank",
  "query": {"image": "https://example.com/product.png"},
  "documents": [
    "产品退款规则。",
    "先固定底座，再连接电源。",
    {"image": "https://example.com/manual.png"},
    {"video": "https://example.com/tutorial.mp4"}
  ]
}
使用视频查询时，将 query 改为：
{"video": "https://example.com/question.mp4"}
媒体地址和内容格式需符合所选模型的要求；视频查询的可用性和效果也需按模型确认。直接填写 URL 字符串会被当作文本，图片和视频请使用表中的对象格式。

Provider 自定义请求参数

CMR 实例默认开启参数转换，并默认透传厂商自定义参数。按厂商要求将参数放入请求即可，无需逐个配置放行；如果实例已配置参数过滤规则，则按该规则处理。例如，所选模型支持 return_raw_scores 时，可以这样请求：
{
  "model": "cmr-text-rerank",
  "query": "如何安装产品？",
  "documents": ["产品退款规则。", "先固定底座，再连接电源。"],
  "return_raw_scores": true
}
如需设置默认值、修改参数值或过滤字段，可在目标 CMR 实例的参数转换配置中设置规则。通过管理 API 配置时，使用 CreateParamTranslationConfig 保存、TestParamTranslationConfig 预览；Rerank 规则的端点填写 rerank。自定义参数的名称、填写层级和取值以厂商说明为准。更换模型或厂商后，请确认这些参数仍然适用。

响应参数

基本响应参数

参数
类型
是否一定返回
说明
id
string
是
本次请求的标识
created
integer
是
响应创建时间，Unix 时间戳，单位为秒
object
string
是
固定为 list
model
string
是
本次实际调用成功的 CMR 逻辑模型名称
results
object[]
是
重排结果列表
usage
object
否
模型返回的用量信息；未提供时不返回

响应结果

参数
类型
是否一定返回
说明
results[].index
integer
是
候选在请求 documents 中的下标，从 0 开始，不是排序后的名次
results[].relevance_score
number
是
模型给出的相关性分数
results[].document
string | object
否
模型返回的候选内容：文本为字符串，图片为 {"image":"..."}，视频为 {"video":"..."}
CMR 保留模型返回的顺序和分数。不同模型的分数不一定可直接比较，也不应将分数当作概率。document 是否出现，以模型实际返回为准；即使设置 return_documents=true，也可能不返回。需要原始候选时，可用 index 查找请求中的 documents[index]。

Provider 自定义响应参数

除上述标准响应字段外，CMR 也会透传厂商实际返回的自定义字段，例如 request_id、结果项或用量信息中的附加字段，保留其内容和内部结构，无需额外配置。已经转换为标准字段的信息不会重复返回。自定义字段的含义以厂商说明为准，更换模型或厂商后，这些字段可能不再返回或含义发生变化。

响应示例

以下示例用于说明字段格式，分数和用量以实际返回为准。

文本结果

{
  "id": "rerank-7f3a2c10",
  "created": 1788969600,
  "object": "list",
  "model": "cmr-text-rerank",
  "results": [
    {
      "index": 1,
      "relevance_score": 0.91,
      "document": "先固定底座，再连接电源。"
    }
  ],
  "usage": {
    "prompt_tokens": 60,
    "completion_tokens": 0,
    "total_tokens": 60
  }
}
index=1 表示结果对应请求中的第 2 条候选。模型未返回候选内容或用量时，响应会省略相应字段。

图片结果

{
  "id": "rerank-a1b2c3d4",
  "created": 1788969600,
  "object": "list",
  "model": "cmr-multimodal-rerank",
  "results": [
    {
      "index": 2,
      "relevance_score": 0.91,
      "document": {"image": "https://example.com/manual.png"}
    }
  ],
  "usage": {
    "prompt_tokens": 147,
    "total_tokens": 829,
    "prompt_tokens_details": {"image_tokens": 682}
  }
}

错误响应

请求失败时，CMR 返回统一的错误格式：
{
  "error": {
    "message": "请求参数无效",
    "type": "invalid_request_error",
    "param": null,
    "code": "400"
  }
}
参数
说明
error.message
错误说明
error.type
错误类型
error.param
相关请求参数；无法定位时可能为空
error.code
错误码，以实际响应为准
常见 HTTP 状态码：
HTTP 状态码
常见原因
处理建议
400
请求格式错误，或模型不支持当前参数、内容类型
检查并修正请求
401
API Key 无效或鉴权失败
检查 API Key 和厂商凭证
403
鉴权头有误或没有访问权限
检查 Authorization 和模型权限
404
模型、资源或接口不存在
检查模型名称和接入配置
408 / 504
请求超时
在业务允许时稍后重试
429
请求限流或配额不足
参考 Retry-After，降低请求频率后重试
500 / 502 / 503
服务异常、连接失败或返回内容异常
稍后重试；持续失败时记录请求标识并联系支持

中国站