Embeddings

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

请求方式

POST

接口地址

$GENESIS_BASE_URL/embeddings

身份认证

使用 UC PAT 或 Genesis 服务账号 API Key：Authorization: Bearer <ACCESS_TOKEN>。详见接口地址与身份认证。

文本向量化

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

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

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

字段

含义

data[].embedding

浮点向量

data[].index

该向量对应的输入下标

usage.total_tokens

接口返回时用于核对的 Token 用量

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

OpenAI SDK 兼容性

控制台「使用」页的示例会显式请求浮点向量。使用官方 OpenAI SDK 时也传入 encoding_format="float"，避免依赖 SDK 或服务的默认编码：

response = client.embeddings.create(
    model="<embedding-model-id>",
    input=["MatrixOne 是面向智能时代的数据库。"],
    encoding_format="float",
)

data[].embedding 应为浮点数组。若环境支持其他编码形式，以控制台示例和实际响应为准。

如果所选模型支持指定维度，可以在请求中传入 dimensions。不要把该字段作为所有嵌入模型的通用参数；调用前先确认模型详情或「使用」页示例。

批处理建议

  • 在模型允许的输入长度和请求大小内合并小文本，减少请求开销。

  • 为每个输入保留稳定的业务 ID，并在写入向量库前把它与 data[].index 对齐。

  • 空字符串、超长文本和不同语言的处理方式可能因模型而异；入库前请清洗输入并记录失败项。

  • 同一索引应使用同一个模型和同一套预处理。更换模型后，向量维度或分布可能变化，需要重新生成索引。

多模态 Embedding

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

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

最后更新于