模型路由 重排序模型

一、概述

POST /v1/rerank

图片、视频和混合候选是否可用，以所选模型的支持情况为准。每次请求只提供一份查询，每条候选只包含一段文本、一张图片或一个视频。

二、前提条件

1. 建议提前阅读 使用约束 与 支持的模型提供商 了解相关信息。

2. 已创建模型路由实例，详细操作指导请参见 创建模型路由实例。

3. 已创建 BYOK 实例，详细操作指导请参见 创建 BYOK 实例。

4. 已创建模型路由访问密钥（API Key），详细操作指导请参见 创建模型路由访问密钥。

5. 已完成重排序模型关联和模型路由策略配置，详细操作指导请参见 配置模型调度管理。

四、请求地址

POST {CMR_BASE_URL}/v1/rerank

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

五、请求头

六、快速开始

将示例中的访问地址、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 osimport requestsdocuments = [ "产品退款规则。", "先固定底座，再连接电源。",]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"]])

十、基本请求参数

选填参数是否生效取决于所选模型。未填写的选填参数，CMR 不自动补默认值。

十一、文本输入

query 和文本候选直接填写字符串，最简请求见快速开始。下面演示所选模型支持时，如何添加选填参数来限制结果数量、请求返回候选内容和指定排序要求：

{ "model": "cmr-text-rerank", "query": "如何安装产品？", "documents": [ "产品退款规则。", "先固定底座，再连接电源。" ], "top_n": 1, "return_documents": true, "instruct": "优先选择提供具体安装步骤的内容。"}

十二、图片和视频输入

图片查询与混合候选示例：

{ "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。自定义参数的名称、填写层级和取值以厂商说明为准。更换模型或厂商后，请确认这些参数仍然适用。

十五、基本响应参数

十六、响应结果

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 条候选。模型未返回候选内容或用量时，响应会省略相应字段。

20、图片结果

{ "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} }}

21、错误响应

·请求失败时，CMR 返回统一的错误格式：

{ "error": { "message": "请求参数无效", "type": "invalid_request_error", "param": null, "code": "400" }}

·常见 HTTP 状态码：