Embeddings 接入

概览

OneLinkAI 提供 Embeddings 接口，用于将文本内容转换为向量表示，常用于语义检索、相似度计算、聚类、分类、推荐召回和 RAG 知识库构建等场景。

当前 Embeddings 接口尽量兼容 OpenAI Embeddings 协议，方便已经使用 OpenAI 风格客户端或 SDK 的业务快速迁移到 OneLinkAI 网关。

接入规则

鉴权方式

调用 OneLinkAI 的 Embeddings 接口时，统一使用 Bearer Token 鉴权：

路径规则

当前 Embeddings 能力主要使用以下路径：

POST /v1/embeddings

POST /v1/engines/{model}/embeddings（兼容旧式 OpenAI 路径）

示例：

Embeddings 路径：POST /v1/embeddings

旧式 Engine Embeddings 路径：POST /v1/engines/{model}/embeddings

通用调用方式

请求体使用 application/json。

请求体中的 model 用于指定向量模型。

input 用于传入需要向量化的文本内容。

OneLinkAI 保留统一网关路径与统一 Authorization: Bearer <ApiKey> 鉴权方式。

能力清单

以下内容用于快速说明当前 Embeddings 接口的支持范围。

能力名称	是否支持	说明
文本向量化	支持	将文本转换为稠密向量表示
OpenAI 兼容格式	支持	兼容 OpenAI 风格的 Embeddings 请求和响应结构
自定义向量维度	按模型支持	可通过 `dimensions` 指定输出向量维度，具体以模型能力为准
扩展参数	按通道支持	可通过 `extra` 传递供应商扩展参数

接口详情

以下请求示例统一以 https://api.onelinkai.cloud 作为示例网关地址，实际调用时请替换为你的真实接入地址和有效的 ApiKey。

Embeddings

兼容 OpenAI 官方 Embeddings 协议的文本向量化接口

请求路径：POST /v1/embeddings

请求格式：application/json

必填请求字段：model、input

常用请求字段：encoding_format、dimensions、extra

核心响应字段：object、model、data、usage

请求示例

响应示例

{
  "object": "list",
  "model": "<Model ID>",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.0123, -0.0456, 0.0789],
      "index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "total_tokens": 12
  }
}

使用建议

如果你正在构建 RAG 应用，建议将文档切分后调用 Embeddings 接口生成向量，再写入向量数据库。

如果你需要做语义搜索，建议对 query 和候选文本使用同一向量模型生成向量，避免不同模型向量空间不一致。

如果模型支持 dimensions，可以根据召回质量、存储成本和检索性能选择合适维度。

对长文本做向量化前，建议先按语义段落切分，避免单条输入过长影响检索效果。

具体模型可用性、向量维度、输入长度与计费规则，请以当前接口实际返回结果为准。

概览#

接入规则#

鉴权方式#

路径规则#

通用调用方式#

能力清单#

接口详情#

Embeddings#

请求示例#

响应示例#

使用建议#

概览