# 文本与多模态 Embeddings

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

## 前提条件

- 已从[获取可用模型](../getting-started/available-models.md)取得 Embeddings 模型 ID。图文输入需要支持多模态 Embeddings 的模型。
- 已按[身份认证](../getting-started/authentication.md)配置访问令牌。
- 图文输入已准备可访问的图片 URL，或图片的 Base64 内容。

## 请求地址

```text
POST <GENESIS_BASE_URL>/embeddings
```

## 将文本转换为向量

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

```bash
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`，将一组图文内容融合为一个向量：

```bash
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 内容，可将图像片段改为以下形式：

```json
{
  "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`、编码格式和维度的可用性以当前模型与接口说明为准。

## 成功响应

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

```json
{
  "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 | 按[身份认证](../getting-started/authentication.md)重新配置当前环境的凭据。 |

## 下一步

- [对文本或图文候选内容重新排序](rerank.md)
- [查看当前凭证可用的模型](../getting-started/available-models.md)
- [选择模型与能力](../getting-started/choose-model-capabilities.md)