文本与多模态 Embeddings¶

使用 Embeddings API 将文本或图文内容转换为向量。文本和多模态请求使用同一个接口，但 input 的结构不同；完成本页后，你可以选择相应模型和输入形态，并从 data[].embedding 读取向量。

前提条件¶

已从获取可用模型取得 Embeddings 模型 ID。图文输入需要支持多模态 Embeddings 的模型。
已按身份认证配置访问令牌。
图文输入已准备可访问的图片 URL，或图片的 Base64 内容。

请求地址¶

POST <GENESIS_BASE_URL>/embeddings

将文本转换为向量¶

文本输入可以是单个字符串或字符串数组。批量输入时，响应中的 data[].index 对应输入数组的下标：

curl -X POST "$GENESIS_BASE_URL/embeddings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -d '{
    "model": "<TEXT_EMBEDDING_MODEL_ID>",
    "input": [
      "MatrixOne 是面向智能时代的数据库。",
      "Genesis 提供统一模型 API。"
    ],
    "encoding_format": "float"
  }'

在写入向量库前，使用 index 将每个文本向量与原始文本或业务 ID 对齐。不要依赖响应数组之外的隐含顺序。

将图文内容转换为向量¶

多模态请求的 input 是对象数组，每个对象包含一个 content 数组。下面的示例显式使用 fusion 和 one_per_input，将一组图文内容融合为一个向量：

curl -X POST "$GENESIS_BASE_URL/embeddings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -d '{
    "model": "<MULTIMODAL_EMBEDDING_MODEL_ID>",
    "type": "embedding_multimodal",
    "input": [
      {
        "content": [
          {
            "type": "text",
            "text": "产品包装上的文字和图案"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://<IMAGE_HOST>/<IMAGE_PATH>"
            }
          }
        ]
      }
    ],
    "embedding_mode": "fusion",
    "output_cardinality": "one_per_input",
    "encoding_format": "float"
  }'

图片 URL 必须能被当前模型服务读取。https://<IMAGE_HOST>/<IMAGE_PATH> 是占位值，不能直接作为真实图片使用。

如果已持有 Base64 内容，可将图像片段改为以下形式：

{
  "type": "image_base64",
  "image_base64": "<BASE64_ENCODED_IMAGE>"
}

不要将 Chat Completions 的 messages 结构用于 /embeddings。文本输入与多模态输入具有不同的 input 形态，必须分别构造。

请求参数¶

字段	类型	必需	说明
`model`	string	是	Embeddings 模型 ID。文本与多模态输入需要选择对应能力的模型。
`type`	string	视模型而定	多模态 Embeddings 的模型类型标识。当前控制台 cURL 示例使用 `embedding_multimodal`；调用时以所选模型的当前示例为准。
`input`	string、string[] 或 object[]	是	待转换的内容。文本使用字符串或字符串数组；多模态使用对象数组。
`input[].content`	array	多模态输入时	一条多模态输入的内容片段数组，可组合文本和图像。
`input[].content[].type`	string	多模态输入时	内容片段类型：`text`、`image_url` 或 `image_base64`。
`input[].content[].text`	string	`type` 为 `text` 时	需要转换为向量的文本内容。
`input[].content[].image_url.url`	string	`type` 为 `image_url` 时	可访问的图片 URL，或当前接口支持的 Data URL。
`input[].content[].image_base64`	string	`type` 为 `image_base64` 时	图片的 Base64 内容。
`embedding_mode`	string	否	多模态内容的组合方式。当前控制台提供 `fusion` 和 `separate`；选择后同时确认输出向量数量。
`output_cardinality`	string	否	多模态请求的输出数量形态。当前控制台提供 `one_per_input` 和 `per_content`。
`encoding_format`	string	否	向量编码格式。当前控制台提供 `float` 和 `base64`；示例使用 `float`。
`dimensions`	integer	否	期望的向量维度，仅在所选模型支持时使用。

不要从示例推断默认值。embedding_mode、output_cardinality、编码格式和维度的可用性以当前模型与接口说明为准。

成功响应¶

文本和多模态请求都返回向量列表。下面示例省略了向量中的大部分数值：

{
  "object": "list",
  "model": "<EMBEDDING_MODEL_ID>",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.018, -0.042, 0.337]
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "total_tokens": 0
  }
}

字段	类型	返回条件	说明
`object`	string	成功响应返回	列表响应的对象类型。
`model`	string	成功响应返回	实际处理本次请求的模型 ID。
`data`	array	成功响应返回	本次输入产生的向量列表。
`data[].index`	integer	每个向量项返回	文本批量请求以及多模态 `fusion` + `one_per_input` 请求中，对应输入数组的下标。其他输出组合按实际返回的 `data` 处理。
`data[].embedding`	number[] 或 string	每个向量项返回	向量结果。实际类型取决于请求的编码格式。
`usage`	object	当前响应包含时	本次请求的 Token 用量信息。只读取实际返回的字段。

批量响应是本次请求的结果，不是分页列表。输入超过当前模型或请求允许范围时，由调用方拆分批次并记录失败项。

常见问题¶

现象	先检查	下一步
模型不接受当前输入	`model` 的能力、输入形态和 `GET /models` 结果	文本与图文输入分别选择相应 Embeddings 模型，并发送最小请求验证。
向量与原始数据错位	`data[].index` 与提交的输入数组	写入向量库前按 `index` 关联业务 ID。
图像无法读取	图片 URL 可访问性，或 `image_base64` 是否包含有效内容	使用可访问 URL 或重新生成图片的 Base64 内容后重试。
返回的向量数量不符合预期	`embedding_mode`、`output_cardinality` 和实际响应的 `data`	显式指定需要的组合与输出形态，并按实际返回的 `data` 处理。
认证失败	请求地址、令牌和 `Authorization` Header	按身份认证重新配置当前环境的凭据。

下一步¶

最后更新于 2026 年 8 月 14 日