# 创建 Embedding

将文本或多模态内容转换为向量，并从 `data[].embedding` 读取结果。文本和多模态输入使用同一接口，但 `input` 的结构不同；本页以文本输入说明最小请求。

```text
POST https://token.moi.matrixorigin.cn/v1/embeddings
```

## 调用前准备

请求地址为 `https://token.moi.matrixorigin.cn/v1/embeddings`。准备具有 Genesis 权限的访问凭据，以及支持 Embeddings 的模型 ID。

下方示例使用：

- `$GENESIS_ACCESS_TOKEN`：实际访问令牌或服务账号 API Key，通过 `Authorization` Header 传递。
- `$MODEL_ID`：要调用的模型 ID，填入请求体的 `model` 字段。

## 请求头

| 请求头 | 是否必填 | 说明 |
| --- | --- | --- |
| `Authorization` | 是 | 使用 `Bearer <GENESIS_ACCESS_TOKEN>` 传递访问凭据。 |
| `Content-Type` | 是 | 设置为 `application/json`。 |

## 请求体

请求体包含以下字段。

本文中，类型后的 `[]` 表示数组，例如 `string[]` 是字符串数组；字段路径中的 `[]` 表示数组中的每一项，例如 `data[].index` 表示 `data` 数组中每一项的 `index` 字段。

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 支持 Embeddings 的模型 ID。 |
| `input` | string、string[] 或 object[] | 是 | 待转换内容。文本输入可使用字符串或字符串数组；多模态输入使用对象数组。 |
| `encoding_format` | string | 否 | 向量编码格式。示例使用 `float`。 |
| `dimensions` | integer | 否 | 期望的向量维度，仅在所选模型支持时使用。 |

文本批量输入时，响应的 `data[].index` 对应请求数组下标。多模态输入、编码格式和维度的可用性以当前模型支持范围为准。

## 请求示例

```bash
curl -X POST "https://token.moi.matrixorigin.cn/v1/embeddings" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "'"$MODEL_ID"'",
    "input": [
      "MatrixOne 是面向智能时代的数据库。",
      "Genesis 提供模型调用接口。"
    ],
    "encoding_format": "float"
  }'
```

## 成功响应

```json
{
  "object": "list",
  "model": "<MODEL_ID>",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.018, -0.042, 0.337]
    }
  ]
}
```

响应中用于读取向量结果的字段如下。

本文中，类型后的 `[]` 表示数组，例如 `number[]` 是数值数组；字段路径中的 `[]` 表示数组中的每一项，例如 `data[].embedding` 表示 `data` 数组中每一项的 `embedding` 字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `object` | string | 响应对象类型，示例为 `list`。 |
| `model` | string | 实际处理请求的模型 ID。 |
| `data` | array | 本次输入产生的向量列表。 |
| `data[].object` | string | 向量对象类型，示例为 `embedding`。 |
| `data[].index` | integer | 对应文本输入数组的下标。 |
| `data[].embedding` | number[] 或 string | 向量结果。实际类型取决于请求的编码格式。 |

将 `data[].index` 映射回提交时保存的业务 ID。不要假定所有模型或编码格式都返回相同的向量维度。

## 错误响应

接口不使用 `code`、`msg`、`data` 包络。收到非成功 HTTP 状态时，不要从 `data[]` 读取向量。错误对象由兼容的模型服务返回；除 `error.message` 外的字段可能省略。

### 错误对象字段

```json
{
  "error": {
    "message": "<可读错误信息>",
    "type": "<错误类型，可能省略>",
    "code": "<错误代码，可能省略>"
  }
}
```

错误正文中可能出现的字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `error.message` | string | 可读错误信息。 |
| `error.type` | string，可选 | 上游错误类别。 |
| `error.code` | string 或 null，可选 | 上游错误代码。 |

### 常见 HTTP 错误

下表说明收到不同 HTTP 状态时应执行的操作。

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - —
  - 输入形态、向量编码或维度参数不符合当前模型要求。
  - 先使用单个文本和 `encoding_format: "float"` 验证。
* - `401`
  - —
  - 凭据无效，或当前凭据无权调用该模型。
  - 检查认证 Header 和模型范围。
* - `403`
  - —
  - 凭据无效，或当前凭据无权调用该模型。
  - 检查认证 Header 和模型范围。
* - `413`
  - —
  - 输入内容超过接口允许范围。
  - 拆分批次并记录未完成项。
* - `429`
  - —
  - 当前服务受到限制或暂时不可用。
  - 降低请求频率，或稍后再次提交请求。
* - `5xx`
  - —
  - 当前服务受到限制或暂时不可用。
  - 降低请求频率，或稍后再次提交请求。
```

## 后续操作

- [Rerank](rerank.md)
- [查询模型列表](models.md)