背景描述

向量检索是检索增强生成（RAG）链路里的第一道筛选。向量模型把查询和文档分别转换为数值向量，再按相似度从海量文档里粗筛出候选；如果还需要提升排序精度，可以把候选交给重排序模型再次打分。把向量模型接入模型网关，意味着它和对话模型一样纳入统一的域名、鉴权、套餐限流和 Token 计量体系，业务侧不需要再为它单独维护一套地址和密钥。

本文以部署一个向量模型并通过 OpenAI 规范对外提供服务为例，介绍从上传推理镜像到验证调用、查看用量的完整流程。示例模型为 BAAI/bge-m3，其他支持向量任务的模型也可按相同步骤部署；验证时应以实际模型的向量维度为准。

前提条件

已具备项目管理员权限，可以初始化命名空间和设置配额。
环境中有可用的 AI 加速卡资源（英伟达 GPU、海光 HCU 或昇腾 NPU）。
已准备好用于上传镜像的客户端环境（安装有 ctr 或 docker 命令）。
已准备好向量模型文件，或环境能够访问 ModelScope 在线导入模型。

操作步骤

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

在《容器镜像服务》中创建一个共享空间（建议命名为 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 加速卡数量；向量模型通常远小于对话模型，可以按模型大小设置资源，但需要为并发预留余量。
新建模型。
1. 进入《模型广场》，单击 新建模型。
2. 选择模型来源。可以从 ModelScope 在线导入，也可以先在《模型仓库》创建上传任务手动上传模型文件，再在此处选择「绑定已有模型文件」。
3. 选择适用于向量任务的模型。本文以 [BAAI/bge-m3] 为例。它支持多语言文本向量，稠密向量维度为 1024。
创建推理引擎。
1. 进入《推理引擎》，单击 创建推理引擎。
2. 选择 AI 加速卡型号，镜像会根据步骤 1 中打的标签自动带出，选择对应的 vLLM 镜像。
3. 其余参数保持默认即可，按需修改。
部署模型。
1. 回到《模型广场》，选择步骤 4 中新建的模型，编辑设置推理引擎，或直接单击 部署。
2. 选择步骤 5 中创建的推理引擎，单击 创建，等待模型部署状态变为就绪。
3. 部署就绪后，确认该服务已注册向量接口，再进行下一步。进入模型部署的详情页面，进入实例的终端，执行命令比如：
```
curl -s http://127.0.0.1:8000/openapi.json | grep -o '"/v1/embeddings"'
```
  返回 "/v1/embeddings" 表示接口已注册。如果没有返回，检查模型是否支持向量任务以及推理引擎的启动日志。
创建 AI 服务提供者。
1. 进入《AI 服务提供者》，单击 创建，服务类型选择「内部」。
2. 先选择「API 规范」为 OpenAI，再选择步骤 6 中的模型部署，向量接口使用 OpenAI 规范。
3. 单击 创建。
创建模型网关路由。
1. 进入《模型网关》，单击 创建路由。
2. 输入路由域名，后端选择步骤 7 中创建的 OpenAI 规范 AI 服务提供者，单击 创建。
3. 如果为同一个模型配置了多个后端（主用 + 备用），这些后端必须全部是 OpenAI 规范。同一模型下混用不同规范的后端，在故障转移时请求会失败。不同模型之间可以使用不同规范，例如在同一条路由下同时挂载 OpenAI 规范的向量模型和 Cohere 规范的重排序模型。
创建套餐。

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

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

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

结果验证

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

执行向量调用，确认返回结果包含与输入文本一一对应的向量。具体命令如下：

curl -s http://<路由域名>:<网关端口>/v1/embeddings \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API Key>' \
  -d '{
    "model": "<模型名称>",
    "input": [
      "EasyStack MaaS 是一个模型即服务平台",
      "今天天气不错"
    ],
    "encoding_format": "float"
  }'

正常返回的 data 数组包含两个元素；每个元素的 embedding 是一个数值数组，index 与输入文本的下标对应。响应还应包含 usage.prompt_tokens。使用 BAAI/bge-m3 时，稠密向量的维度应为 1024。请求体的主要字段如下：

字段	是否必填	说明
`model`	是	路由中配置的模型名称
`input`	是	待转换的文本或文本数组
`encoding_format`	否	设置为 `float` 时返回数值数组，便于检查向量维度

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