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

向量嵌入模型

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

本页目录：

概述

CMR 是 AI 网关。CMR Embedding API 通过统一的接口和鉴权方式，为不同上游 Embedding 模型提供模型访问、请求转发、协议适配、路由与限流等网关能力。CMR 本身不生成向量。向量由实际调用的上游模型生成；输入限制、向量维度、输出形式、向量质量和模型效果均以所选模型的能力为准。文本和多模态请求使用同一个入口：
POST /v1/embeddings
请求形式
input 填写方式
说明
单条文本
string
为一条文本生成向量
批量文本
string[]
一次为多条文本生成向量
单组图文内容
object
在一组输入中组合文本和图片

前提条件

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

接口地址与鉴权

请求地址

POST {CMR_BASE_URL}/v1/embeddings
CMR_BASE_URL 为 CMR 实例的访问地址，请以控制台展示为准。

请求头

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

快速开始

cURL

curl --request POST "${CMR_BASE_URL}/v1/embeddings" \\
  --header "Authorization: Bearer ${CMR_API_KEY}" \\
  --header "Content-Type: application/json" \\
  --data '{
    "model": "cmr-text-embedding",
    "input": "今天深圳的天气很好"
  }'

Python

import os
import requests

response = requests.post(
    f"{os.environ['CMR_BASE_URL']}/v1/embeddings",
    headers={
        "Authorization": f"Bearer {os.environ['CMR_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "cmr-text-embedding",
        "input": "今天深圳的天气很好",
    },
    timeout=30,
)
response.raise_for_status()
result = response.json()
print(result["data"][0]["embedding"])

请求参数

基本参数

参数
类型
必填
说明
model
string
是
CMR 逻辑模型名称或模型别名。可用值以控制台关联模型为准
input
string | string[] | object
是
需要生成向量的文本或图文内容
dimensions
integer
否
期望的 Dense 向量维度。仅在所选模型支持可变维度时生效
encoding_format
string
否
Dense 向量的返回编码，常用值为 float 或 base64，以所选模型支持情况为准
user
string
否
终端用户标识，可用于业务追踪或上游风控。请勿传入密码、Token 等敏感信息

文本输入

单条文本：
{
  "model": "cmr-text-embedding",
  "input": "查询文本"
}
批量文本：
{
  "model": "cmr-text-embedding",
  "input": ["Query: 如何重置密码？", "Document: 在账户安全页面选择重置密码。"]
}
批量请求时，可通过响应中的 data[].index 将向量与输入项对应。

多模态输入

支持在一组输入中组合文本和图片。input 按下表填写：
参数
类型
必填
说明
input.type
string
是
固定为 multimodal
input.content
object[]
是
同一组输入中的文本和图片内容
input.content[].type
string
是
文本内容填 text，图片内容填 image_url
input.content[].text
string
当 type=text 时必填
文本内容
input.content[].image_url
object
当 type=image_url 时必填
图片输入对象
input.content[].image_url.url
string
当 type=image_url 时必填
图片输入值。该值不限于 HTTP/HTTPS URL；可填写的格式（如公网 URL、Data URL 等）以所选上游模型的支持情况为准，CMR 按请求值透传
请求示例：
{
  "model": "cmr-multimodal-embedding",
  "input": {
    "type": "multimodal",
    "content": [
      {
        "type": "text",
        "text": "红色跑鞋"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/red-shoe.jpg"
        }
      }
    ]
  },
  "encoding_format": "float"
}
上例仅演示使用公网 URL 传入图片。其他图片格式是否可用，请查看所选上游模型的说明。当前标准请求不支持视频、多组多模态输入，也不支持在顶层直接混用文本和图片数组。

Provider 自定义请求参数

CMR Standard 字段包括 model、input、dimensions、encoding_format 和 user。如需传入 input_type、instruction 等 CMR Standard 之外的 Provider 参数，可配置自定义字段透传。
例如，已放通 input_type 时：
{
  "model": "cmr-text-embedding",
  "input": "如何重置密码？",
  "input_type": "query"
}
自定义参数的名称、类型和含义以当前 Provider 为准。更换模型或 Provider 前，请确认相同参数仍然适用。

响应参数

基本响应字段

参数
类型
是否一定返回
说明
id
string
是
本次 Embedding 请求的标识
created
integer
是
响应创建时间，为 Unix 时间戳，单位为秒
object
string
是
固定为 list
data
object[]
是
向量结果列表
model
string
是
请求中使用的 CMR 逻辑模型名称
usage
object
否
上游模型返回的用量信息。上游未提供时，响应中可能没有该字段

响应向量结果

参数
类型
是否一定返回
说明
data[].object
string
是
固定为 embedding
data[].index
integer
是
结果对应的输入序号，从 0 开始
data[].embedding
number[] | string
否
Dense 向量。使用编码输出时可能为字符串
data[].sparse_embedding
object[]
否
Sparse 向量，只列出非零位置及其权重
data[].multi_embedding
number[][] | string | object
否
Multi-vector 结果。具体形式以所选模型的返回值为准
每个 data[] 结果至少包含 Dense、Sparse 或 Multi-vector 中的一种。所选模型支持时，同一个结果可同时包含多种向量。
sparse_embedding 中每个元素的含义如下：
参数
类型
是否一定返回
说明
index
integer
是
非零维度的下标
value
number
是
该维度的权重
token
string
否
上游模型返回的对应 Token

Provider 自定义响应参数

除上述字段外，响应中可能保留上游 Provider 返回的额外信息。例如：
响应顶层的 request_id；
data[] 中表示向量类型的 type。
这些字段以实际响应为准，更换模型或 Provider 后可能不再返回或含义发生变化。

响应示例

以下示例仅展示字段形式，向量值、向量维度和 Token 用量以实际返回为准。

Dense 向量

{
  "id": "emb-7f3a2c10",
  "created": 1787385661,
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.012, -0.034, 0.021]
    }
  ],
  "model": "cmr-text-embedding",
  "usage": {
    "prompt_tokens": 4,
    "total_tokens": 4
  }
}

Dense + Sparse 向量

{
  "id": "emb-a1b2c3d4",
  "created": 1787385661,
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.018, -0.041, 0.007],
      "sparse_embedding": [
        {
          "index": 18452,
          "value": 0.73,
          "token": "数据库"
        }
      ]
    }
  ],
  "model": "cmr-hybrid-embedding",
  "usage": {
    "total_tokens": 9
  },
  "request_id": "provider-request-id"
}

Dense + Multi-vector

{
  "id": "emb-9e8d7c6b",
  "created": 1787385661,
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.016, -0.028, 0.031],
      "multi_embedding": [
        [0.021, -0.013, 0.009],
        [0.008, 0.034, -0.017]
      ]
    }
  ],
  "model": "cmr-multimodal-embedding"
}

错误响应

CMR Embedding API 使用统一的错误响应形式：
{
  "error": {
    "message": "Invalid input: input is required.",
    "type": "invalid_request_error",
    "param": "input",
    "code": "400"
  }
}
参数
说明
error.message
错误说明
error.type
错误类型；具体值可能随错误来源而不同
error.param
与错误相关的请求参数；无明确参数时可能为空
error.code
错误码。当前常见为字符串形式的 HTTP 状态码
CMR 可能在错误中保留已安全处理的上游附加信息。客户端应优先根据 HTTP 状态码处理失败，不要依赖上游错误文案始终不变。
常见 HTTP 状态码：
HTTP 状态码
常见场景
建议
400
JSON 或参数格式错误、输入类型不支持、CMR 逻辑模型名称无效，或上游模型拒绝当前参数
修正请求，不要盲目重试
401
API Key 无效或已失效，或上游鉴权失败
检查 API Key 和相关凭证
403
API Key 缺失、鉴权头格式错误，或无权访问当前 CMR 实例、模型或上游资源
检查 Authorization Header 和权限配置
404
上游模型、资源或接口路径不存在
检查所选模型及 Provider 配置
408
请求或上游调用超时
在业务允许时重试
429
CMR 限流、上游配额超限，或当前暂无可用部署
参考 Retry-After（如存在）并使用退避策略重试
500
CMR 内部错误，或 CMR 连接上游失败
记录请求标识并联系支持人员
502
上游响应无效，或响应与当前协议配置不匹配
使用退避策略重试；持续出现时联系支持人员
503
上游服务或当前协议配置暂不可用
使用退避策略重试
504
上游网关超时
使用退避策略重试
中国站