Embeddings¶

接口用途¶

将文本或模型支持的多模态内容转换为向量，常用于语义检索、聚类和相似度计算。向量维度和可接受的输入类型由所选模型决定。

请求方式¶

POST

接口地址¶

$GENESIS_BASE_URL/embeddings

身份认证¶

使用 Genesis API Key：Authorization: Bearer <API_KEY>。详见接口地址与身份认证。

文本向量化¶

单条文本与文本数组都通过 input 提交：

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

响应中的 data 与输入顺序对应：

字段	含义
`data[].embedding`	浮点向量
`data[].index`	该向量对应的输入下标
`usage.total_tokens`	接口返回时用于核对的 Token 用量

按 index 关联批量输入，不要依赖网络返回顺序之外的隐含关系。

批处理建议¶

在模型允许的输入长度和请求大小内合并小文本，减少请求开销。
为每个输入保留稳定的业务 ID，并在写入向量库前把它与 data[].index 对齐。
空字符串、超长文本和不同语言的行为可能因模型而异；入库前应清洗并记录失败项。
同一索引应使用同一个模型和同一套预处理。更换模型后，向量维度或分布可能变化，需要重新生成索引。

多模态 Embedding¶

Genesis 控制台也可展示多模态 Embedding。只有带 embedding_multimodal 能力的模型才可接受图文内容，其内容分段格式应直接从「使用」页代码生成器复制，并在调试页验证。不要把 Chat Completions 的 messages 结构直接用于 /embeddings。

模型发现方法见模型与 Provider。接口没有统一的分页语义；超出单次输入限制时，应由调用方分批并控制并发。认证失败或 429 的处理见Endpoint 与身份认证。