文本嵌入 API

文本嵌入（Embeddings）接口用于将文本转换为向量表示，广泛应用于语义搜索、文本分类、相似度计算等场景。

请求端点

POST https://star.zhxyclaw.cn/v1/embeddings

请求参数

参数	类型	必填	说明
model	string	是	嵌入模型名称，如 text-embedding-3-small、text-embedding-3-large
input	string/array	是	要嵌入的文本，可以是单个字符串或字符串数组
encoding_format	string	否	返回格式：float（默认）或 base64
user	string	否	用户标识

请求示例

curl

curl https://star.zhxyclaw.cn/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "Star API 是一个统一的大模型接口网关"
  }'

Python

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://star.zhxyclaw.cn/v1"
)

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Star API 是一个统一的大模型接口网关"
)

embedding = response.data[0].embedding
print(f"向量维度：{len(embedding)}")
print(f"前5个值：{embedding[:5]}")

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-your-api-key",
  baseURL: "https://star.zhxyclaw.cn/v1",
});

const response = await client.embeddings.create({
  model: "text-embedding-3-small",
  input: "Star API 是一个统一的大模型接口网关",
});

const embedding = response.data[0].embedding;
console.log(`向量维度：${embedding.length}`);
console.log(`前5个值：${embedding.slice(0, 5)}`);

批量嵌入

您可以一次性提交多个文本进行嵌入计算：

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://star.zhxyclaw.cn/v1"
)

texts = [
    "Star API 是一个统一的大模型接口网关",
    "支持 OpenAI、Anthropic、Google 等主流模型",
    "兼容 OpenAI API 格式，无需修改代码"
]

response = client.embeddings.create(
    model="text-embedding-3-small",
    input=texts
)

for i, data in enumerate(response.data):
    print(f"文本 {i+1} 的向量维度：{len(data.embedding)}")

响应格式

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.0023064255, -0.009327292, ...],
      "index": 0
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

响应字段说明

字段	类型	说明
object	string	对象类型，固定为 list
data	array	嵌入结果列表
data[].object	string	固定为 embedding
data[].embedding	array	浮点数向量，即文本的嵌入表示
data[].index	integer	对应输入文本的索引
model	string	使用的模型名称
usage	object	Token 使用量
usage.prompt_tokens	integer	输入 Token 数
usage.total_tokens	integer	总 Token 数

应用场景

语义搜索

import numpy as np
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://star.zhxyclaw.cn/v1"
)

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

# 文档库
documents = [
    "Python 是一种广泛使用的编程语言",
    "机器学习是人工智能的分支",
    "Star API 支持多种大模型"
]

# 获取文档嵌入
doc_response = client.embeddings.create(
    model="text-embedding-3-small",
    input=documents
)
doc_embeddings = [d.embedding for d in doc_response.data]

# 查询
query = "什么是 Star API？"
query_response = client.embeddings.create(
    model="text-embedding-3-small",
    input=query
)
query_embedding = query_response.data[0].embedding

# 计算相似度并排序
similarities = [
    cosine_similarity(query_embedding, doc_emb)
    for doc_emb in doc_embeddings
]

ranked = sorted(enumerate(similarities), key=lambda x: x[1], reverse=True)
for idx, score in ranked:
    print(f"相似度: {score:.4f} | {documents[idx]}")

支持的嵌入模型

模型	向量维度	说明
text-embedding-3-small	1536	轻量高效，适合大多数场景
text-embedding-3-large	3072	高精度，适合对准确度要求高的场景
text-embedding-ada-002	1536	上一代模型，兼容性好

提示

推荐使用 text-embedding-3-small 模型，它在性能和成本之间取得了良好的平衡。