# Embeddings

将文本或多模态内容转换为向量，供后续检索或相似度计算使用。

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

## 调用前准备

准备具有 Genesis 权限的访问凭据和支持 Embeddings 的模型 ID。

## 请求体

将 `$GENESIS_ACCESS_TOKEN` 替换为访问令牌或服务账号 API Key，将 `$MODEL_ID` 替换为要调用的模型 ID。

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 请求示例

```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"
  }'
```

:::::
:::::{tab-item} 参数说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 要调用的 Embeddings 模型 ID。 |
| `input` | string 或 array of string 或 array of object | 是 | 要转换成向量的文本。 |
| `encoding_format` | string | 否 | 向量编码格式。示例使用 `float`。 |
| `dimensions` | integer | 否 | 期望的向量维度，仅在所选模型支持时使用。 |

:::::
::::::
:::::::

## 成功响应

服务会为每段输入返回一条对应的向量结果。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

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

:::::
:::::{tab-item} 字段说明

::::{tab-set}
:::{tab-item} 通用字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `object` | string | 响应对象类型，示例为 `list`。 |
| `model` | string | 实际处理请求的模型 ID。 |
| `data` | array of object | 本次输入产生的向量结果列表；每一项对应一条输入文本。 |

:::
:::{tab-item} 结果项

下面表格展开示例中 `data` 数组的每一项；每一行是该数组项的一个字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `object` | string | 结果对象类型，示例为 `embedding`。 |
| `index` | integer | 这条结果对应 `input` 数组中的位置。 |
| `embedding` | array of number 或 string | 这条文本的向量；实际类型取决于请求的编码格式。 |

:::
::::

:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

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

:::::
:::::{tab-item} 字段说明

::::{tab-set}
:::{tab-item} 通用字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `error` | object | 错误对象。 |

:::
:::{tab-item} 错误对象

下面表格展开示例中 `error` 对象；每一行是该对象的一个字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `message` | string | 可读错误信息。 |
| `type` | string | 模型服务返回的错误类别，可能省略。 |
| `code` | string 或 null | 模型服务返回的错误代码，可能省略。 |

:::
::::

:::::
::::::
:::::::

## 后续操作

- [Rerank](../text-reranking/rerank.md)
- [查看模型列表](../models.md)