背景描述

模型网关对外提供两种 API 规范：OpenAI 规范提供对话、文生图、向量等接口；Cohere 规范只提供一个接口——重排序（rerank）。两者在网关内部是完全互斥的：网关的 rerank 端点只接受 Cohere 规范的后端，而其余所有端点只接受 OpenAI 规范的后端，互相调用会被网关拒绝。

重排序是检索增强生成（RAG）链路里的第二道筛选。第一道用向量检索从海量文档里粗筛出几十条候选，速度快但精度有限；第二道把「查询 + 每条候选」成对送进重排序模型，逐对打分后重新排序，只把最相关的几条交给大模型。把重排序接入模型网关，意味着它和对话模型一样纳入统一的域名、鉴权、套餐限流和 Token 计量体系，业务侧不需要再为它单独维护一套地址和密钥。

本文以部署一个重排序模型并通过 Cohere 规范对外提供服务为例，介绍从上传推理镜像到验证调用、查看用量的完整流程。

前提条件

已具备项目管理员权限，可以初始化命名空间和设置配额。
环境中有可用的 AI 加速卡资源（英伟达 GPU、海光 HCU 或昇腾 NPU）。
已准备好用于上传镜像的客户端环境（安装有 ctr 或 docker 命令）。
推理引擎必须使用 vLLM。具体原因见下方说明。

说明：

SGLang 目前不能用于 Cohere 规范的重排序服务。网关的 Cohere 转换器要求后端提供 /v2/rerank 接口，vLLM 会同时注册 /rerank、/v1/rerank、/v2/rerank 三个等价接口，而 SGLang 只注册 /v1/rerank。因此用 SGLang 部署的重排序模型，在创建 AI 服务提供者时不会出现 Cohere 选项。此类模型仍可用 SGLang 部署后由业务直连，只是无法通过模型网关以 Cohere 规范发布。

操作步骤

上传推理镜像到容器镜像服务。

在《容器镜像服务》中创建一个共享空间（建议命名为 engines），把所有推理引擎镜像集中存放在该空间下，便于统一管理和授权。

从如下地址列表中拉取与本环境加速卡型号匹配的 vLLM 镜像，重新打标签后推送到环境的镜像仓库。重排序模型的输出是一组分数，属于文本类输出，使用非 omni 镜像。

加速卡型号	镜像地址	需打的标签
英伟达 GPU	`vllm/vllm-openai:v0.29.0` `hub.easystack.cn/engines/vllm-openai:v0.29.0`	`vllm`、`nvidia`
海光 HCU	`harbor.sourcefind.cn:5443/dcu/admin/base/vllm:0.18.1-ubuntu22.04-dtk26.04-py3.10` `hub.easystack.cn/engines/vllm:0.18.1-ubuntu22.04-dtk26.04-py3.10`	`vllm`、`hygon`
昇腾 NPU	`quay.io/ascend/vllm-ascend:v0.23.0` `hub.easystack.cn/engines/vllm-ascend:v0.23.0`	`vllm`、`huawei-ascend`

说明：

访问hub.easystack.cn需要联系EasyStack相关人员下载

在《容器镜像服务》的镜像详情页面，为镜像打上表中对应的两个标签。标签决定了后续创建推理引擎时能否自动带出该镜像，漏打标签会导致推理引擎页面选不到镜像。

初始化项目命名空间。

项目管理员登录后进入《模型广场》，按页面提示完成本项目所需命名空间的初始化。该操作每个项目只需执行一次。
设置项目配额。

在《配额设置》中为本项目分配所需配额，容器规格选择「安全容器服务」的配置。分配CPU，内存容量和AI 加速卡数量，重排序模型通常远小于对话模型（bge-reranker-v2-m3 约 2.3GB），显存配额可以相应调低，但需要为并发预留余量。

新建模型。

进入《模型广场》，单击 新建模型。
选择模型来源。可以从 ModelScope 在线导入，也可以先在《模型仓库》创建上传任务手动上传模型文件，再在此处选择「绑定已有模型文件」。

选择适用于重排序的模型。两类模型都能通过校验，但效果差别很大：

模型类型	代表模型	说明
交叉编码器（推荐）	`BAAI/bge-reranker-v2-m3`	把「查询 + 文档」拼成一对送入模型联合打分，能捕捉两者之间的交互信息，这是重排序真正的价值所在
双塔向量模型	`BAAI/bge-m3`	查询和文档分别独立编码后算相似度

说明：

双塔向量模型也能通过重排序接口调用并返回分数，但实测其返回的分数与「自行调用向量接口再计算余弦相似度」的结果完全一致（四位小数内无差异）。也就是说，用向量模型做重排序，相当于把粗筛阶段已经算过的相似度重新算了一遍，并不能提升排序质量。如果目标是提升 RAG 的最终效果，请使用交叉编码器模型。 如果只是想让一个已部署的向量模型顺带提供 rerank 接口，用双塔模型也可以，但要清楚它不会带来额外收益。

创建推理引擎。
1. 进入《推理引擎》，单击 创建推理引擎。
2. 选择 AI 加速卡型号，镜像会根据步骤 1 中打的标签自动带出，选择对应的 vLLM 镜像。
3. 其余参数保持默认即可，按需修改。
部署模型。
1. 回到《模型广场》，选择步骤 4 中新建的模型，编辑设置推理引擎，或直接单击 部署。
2. 选择步骤 5 中创建的推理引擎，单击 创建，等待模型部署状态变为就绪。
3. 部署就绪后，务必先确认该服务已注册重排序接口，再进行下一步。平台正是通过这个接口清单来判断一个部署能否以 Cohere 规范发布的。进入模型部署的详情页面，进入实例的终端。验证命令如下：
```
curl -s http://127.0.0.1:8000/openapi.json | grep -o '"/v2/rerank"'
```
  返回 "/v2/rerank" 表示正常。如果没有返回，说明该模型不具备重排序能力，或推理引擎未正确识别模型任务，此时后续步骤中不会出现 Cohere 选项。
创建 AI 服务提供者。
1. 进入《AI 服务提供者》，单击 创建，服务类型选择「内部」。
2. 先选择「API 规范」为 Cohere，再选择模型部署。
  
  说明：
  
  表单是「规范在前、部署在后」的顺序，选定规范后，下方的部署列表会自动过滤，只展示能够提供该规范的部署，并在提示中给出过滤前后的数量。这样可以避免选到一个无法提供重排序的部署。
  
  如果下拉框中没有 Cohere 选项且整个选择框为灰色，说明当前项目下没有任何一个部署注册了 /v2/rerank。请回到步骤 6 确认接口注册情况。另外，如果部署刚创建尚未完全就绪，接口探测可能超时（探测上限 6 秒），此时关闭对话框稍后重开会重新探测。
3. API 规范创建后不可修改。一个 AI 服务提供者只能是一种规范，Cohere 规范的提供者只能用于重排序，无法再用于对话或向量接口。如需同时提供多种接口，请创建多个 AI 服务提供者。
4. 单击 创建。
创建模型网关路由。
1. 进入《模型网关》，单击 创建路由。
2. 输入路由域名，后端选择步骤 7 中创建的 Cohere 规范 AI 服务提供者，单击 创建。
3. 如果为同一个模型配置了多个后端（主用 + 备用），这些后端必须全部是 Cohere 规范。同一模型下混用不同规范的后端，在主用后端正常时表现正常，一旦触发故障转移切到另一规范的后端，请求会直接失败。表单和接口都会对此进行校验并拒绝提交。
  
  说明：
  
  同一条路由下的不同模型之间可以使用不同规范。例如一条路由里同时挂载一个 Cohere 规范的重排序模型和一个 OpenAI 规范的向量模型，两者互不影响，这是推荐的组织方式——RAG 链路所需的向量和重排序两个能力，可以共用同一个域名和同一个 API Key。
创建套餐。

进入《套餐管理》，单击 创建套餐，「可访问路由」选择步骤 8 中创建的路由，按业务需要设置调用频率和 Token 限额后创建。
创建 API Key。

进入《API Key》，单击 创建，选择步骤 9 中创建的套餐，单击 创建并签发密钥。签发成功后复制密钥妥善保存，密钥只在此时完整展示一次。
查看 Token 用量。

进入《Token 用量》，在「请求类型」筛选器中选择「rerank」，即可查看重排序请求的调用次数和 Token 消耗。

结果验证

确认域名可解析到网关地址。路由是按域名匹配的，域名未解析时请求不会到达网关。可以配置 hosts 记录，也可以在 curl 命令中使用 --resolve 参数临时指定，后者不会修改本机配置。

执行重排序调用，确认返回结果按相关度排序。具体命令如下：

curl -s http://<路由域名>:<网关端口>/cohere/v2/rerank \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API Key>' \
  -d '{
    "model": "<模型名称>",
    "query": "什么是 EasyStack MaaS？",
    "documents": [
      "EasyStack MaaS 是一个模型即服务平台",
      "今天天气不错",
      "MaaS 平台提供模型部署与网关能力"
    ],
    "top_n": 2
  }'

正常返回示例如下，index 是候选文档在请求 documents 数组中的下标，relevance_score 是相关度分数，结果按分数从高到低排列：

{
  "results": [
    { "index": 0, "relevance_score": 0.9832 },
    { "index": 2, "relevance_score": 0.8107 }
  ],
  "meta": { "tokens": { "input_tokens": 48 } }
}

请求体的字段约束如下：

字段	是否必填	说明
`model`	是	路由中配置的模型名称
`query`	是	用于排序的查询语句
`documents`	是	必须是字符串数组。传入对象数组会被网关在转发前直接拒绝
`top_n`	否	只返回相关度最高的 N 条
`max_tokens_per_doc`	否	单条文档的截断长度，默认 4096

确认访问路径正确。网关注册的路径是 /cohere/v2/rerank，必须完全一致。访问 /v2/rerank、/cohere/v1/rerank 等其他路径会返回 404，提示路径不受支持。
确认限流与计量生效。
1. 连续调用超过套餐设置的频率上限，确认返回 429。
2. 回到《Token 用量》，确认出现请求类型为 rerank 的记录，且 Token 数量与请求内容规模相符。

约束与注意事项

规范互斥：Cohere 规范只提供重排序一个接口。用 Cohere 规范的提供者去调用对话、向量等接口会返回 500；反之用 OpenAI 规范的提供者去调用重排序接口同样返回 500。
规范不可变更：AI 服务提供者的 API 规范在创建后无法修改。若某个提供者已被模型网关路由引用，接口层面也会拒绝变更请求，需要先从路由中移除。
同一模型的后端规范必须一致：主用和备用后端必须是同一规范，否则故障转移时请求会失败。不同模型之间不受此限制。
请求超时：网关对单次请求的超时时间为 300 秒，该时长包含重试在内。候选文档数量极大时需要注意单次请求的耗时。
删除模型部署前先检查引用：若待删除的模型部署正被 AI 服务提供者引用，删除操作会弹出二次确认并列出引用方。删除后提供者会指向一个已不存在的服务，使用该提供者的网关路由将开始报错，且平台不会自动清理，需要手工处理。
推理引擎选型：如前所述，当前只有 vLLM 可用于 Cohere 规范的重排序服务。
效果预期：使用双塔向量模型提供重排序接口在功能上可行，但其分数与向量余弦相似度等价，不会带来排序质量的提升。追求 RAG 效果请选用交叉编码器模型。

Rerank模型通过 Cohere 规范对外提供服务

背景描述

前提条件

操作步骤

结果验证

约束与注意事项