API

Embeddings

将文本转换为向量，适用于检索、聚类、推荐和语义搜索。

概述

Embeddings 接口接收字符串或字符串数组，返回浮点向量或 base64 编码向量。它兼容 OpenAI Embeddings 请求结构，并会在控制台记录 token 用量。

请求

`POST https://api.example.com/v1/embeddings`

Headers

Header必需说明
Authorization✓`Bearer $UOUODUO_API_KEY`
Content-Type✓`application/json`

Body 参数

参数类型必需默认说明
modelstring✓-embedding 模型 ID
inputstring 或 array<string>✓-需要向量化的文本
encoding_formatstring否float`float` 或 `base64`
dimensionsinteger否-输出维度，需模型支持
userstring否-终端用户标识

示例

curl https://api.example.com/v1/embeddings \
  -H "Authorization: Bearer $UOUODUO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": [
      "UOUODUO Gateway 提供统一模型路由。",
      "Embedding 可用于语义检索。"
    ],
    "encoding_format": "float"
  }'

响应

字段类型说明
objectstring`list`
dataarray<object>embedding 结果数组
data[].objectstring`embedding`
data[].indexinteger对应输入数组索引
data[].embeddingarray<number> 或 string向量内容
modelstring实际执行模型
usageobjectprompt / total token 统计
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0123, -0.0456, 0.0789]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 18,
    "total_tokens": 18
  }
}

错误

HTTP说明处理建议
400input 为空、超出上下文或 dimensions 不被支持分批、截断或换模型
401API key 无效重新创建 key
429请求或 token 限流做批处理队列和指数退避
500上游异常记录 request id 后重试

注意事项

  • 批量 embedding 会提高吞吐，但单次 input 数量和总 token 仍受模型限制。
  • 如果向量库存储 float 数组，保持 `encoding_format=float`；如果走网络或日志链路，base64 可以降低体积。
  • 建议把 ingestion job 和在线请求使用不同 API key，方便分别设置预算和排查。