API 参考/Embeddings

使用支持的嵌入模型为文本生成向量嵌入。

Embeddings

通过 UniGateway 为文本生成向量嵌入。

接口说明

项目值
方法POST
路径/v1/embeddings
Base URLhttps://api.unigateway.ai/v1
鉴权Authorization: Bearer $UNIGATEWAY_API_KEY
Content-Typeapplication/json

最小请求

Example request

Run it in your stack

Pick the SDK style that matches your app and copy the snippet directly into your project.

from openai import OpenAI

client = OpenAI(api_key="<YOUR_UNIGATEWAY_API_KEY>", base_url="https://api.unigateway.ai/v1")
resp = client.embeddings.create(model="text-embedding-3-small", input=["Test"])
print(len(resp.data[0].embedding))
curl https://api.unigateway.ai/v1/embeddings \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "AI 网关统一了多个模型提供商的访问入口。"
  }'

Python

from openai import OpenAI

client = OpenAI(
    api_key="<YOUR_UNIGATEWAY_API_KEY>",
    base_url="https://api.unigateway.ai/v1",
)

resp = client.embeddings.create(
    model="text-embedding-3-small",
    input=["AI 网关统一了多个模型提供商的访问入口。"],
)

print(f"维度: {len(resp.data[0].embedding)}")

TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.UNIGATEWAY_API_KEY,
  baseURL: "https://api.unigateway.ai/v1",
});

const resp = await client.embeddings.create({
  model: "text-embedding-3-small",
  input: ["AI 网关统一了多个模型提供商的访问入口。"],
});

console.log(`维度: ${resp.data[0].embedding.length}`);

参数说明

字段类型必填说明
modelstring是从 GET /v1/models 获取的嵌入模型 ID
inputstring/array是待嵌入文本；单个用字符串，批量用数组
dimensionsnumber否请求的输出维度（取决于模型）
encoding_formatstring否float（默认）或 base64

响应格式

{
  "object": "list",
  "model": "text-embedding-3-small",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0123, -0.0456, ...]
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "total_tokens": 12
  }
}
响应字段说明
data[].embedding浮点数数组（向量）
data[].index输入批次中的位置
usage.prompt_tokens输入 token 数

查找嵌入模型

使用 GET /v1/models 并按 supported_endpoint_types 过滤包含 embeddings 相关提示的模型。示例：text-embedding-3-small。

正式使用前，请用真实请求确认模型存在并返回嵌入向量。

LangChain 集成

from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings(
    model="text-embedding-3-small",
    base_url="https://api.unigateway.ai/v1",
    api_key="<YOUR_UNIGATEWAY_API_KEY>",
)

result = embeddings.embed_query("测试文本")
print(f"维度: {len(result)}")

常见错误

状态码原因处理方式
400模型或输入无效检查 model ID 和 input 类型
401API Key 无效检查 Authorization 请求头
404模型不在套餐内通过 GET /v1/models 确认模型
413输入过长减少文本长度或批次大小
429触发限流增加退避并重试