文本嵌入接口

创建文本嵌入向量，用于语义搜索、文本相似度计算等任务。

接口信息

  • 接口地址: POST /v1/embeddings
  • 认证方式: Bearer Token
  • Content-Type: application/json

请求参数

必填参数

参数类型说明
modelstring嵌入模型名称
inputstring/array输入文本

可选参数

参数类型默认值说明
encoding_formatstring"float"编码格式，可选 "float" 或 "base64"
userstringnull用户标识

支持的模型

模型维度最大 Token说明
text-embedding-ada-00215368,191OpenAI 第二代嵌入模型
text-embedding-3-small15368,191高性价比小模型
text-embedding-3-large30728,191高精度大模型

请求示例

单文本嵌入

curl https://aigc.aochengcloud.com/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "model": "text-embedding-ada-002",
    "input": "你好，世界"
  }'

批量文本嵌入

curl https://aigc.aochengcloud.com/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "model": "text-embedding-ada-002",
    "input": [
      "你好",
      "世界",
      "人工智能"
    ]
  }'

使用 text-embedding-3 模型

curl https://aigc.aochengcloud.com/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "你好，世界",
    "encoding_format": "float"
  }'

响应格式

单文本响应

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [
        0.0023064255,
        -0.009327292,
        0.015797345,
        ...
      ],
      "index": 0
    }
  ],
  "model": "text-embedding-ada-002",
  "usage": {
    "prompt_tokens": 5,
    "total_tokens": 5
  }
}

批量响应

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.0023064255, ...],
      "index": 0
    },
    {
      "object": "embedding",
      "embedding": [0.0012345678, ...],
      "index": 1
    },
    {
      "object": "embedding",
      "embedding": [0.0034567890, ...],
      "index": 2
    }
  ],
  "model": "text-embedding-ada-002",
  "usage": {
    "prompt_tokens": 15,
    "total_tokens": 15
  }
}

响应字段说明

字段类型说明
objectstring对象类型
dataarray嵌入向量列表
modelstring使用的模型
usageobjecttoken 用量统计

data 字段

字段类型说明
objectstring对象类型
embeddingarray嵌入向量
indexinteger文本索引

SDK 示例

Python

import openai

client = openai.OpenAI(
    api_key="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    base_url="https://aigc.aochengcloud.com/v1"
)

# 单文本嵌入
response = client.embeddings.create(
    model="text-embedding-ada-002",
    input="你好，世界"
)
embedding = response.data[0].embedding
print(f"向量维度: {len(embedding)}")

# 批量文本嵌入
response = client.embeddings.create(
    model="text-embedding-ada-002",
    input=[
        "你好",
        "世界",
        "人工智能"
    ]
)
for item in response.data:
    print(f"文本 {item.index}: 向量维度 {len(item.embedding)}")

Node.js

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: 'sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  baseURL: 'https://aigc.aochengcloud.com/v1'
});

// 单文本嵌入
const response = await openai.embeddings.create({
  model: 'text-embedding-ada-002',
  input: '你好，世界'
});
console.log(`向量维度: ${response.data[0].embedding.length}`);

NumPy 处理

import numpy as np

# 获取嵌入向量
response = client.embeddings.create(
    model="text-embedding-ada-002",
    input="你好，世界"
)
embedding = np.array(response.data[0].embedding)

# 计算余弦相似度
def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

# 获取两个文本的嵌入
text1_embedding = client.embeddings.create(
    model="text-embedding-ada-002",
    input="你好"
).data[0].embedding

text2_embedding = client.embeddings.create(
    model="text-embedding-ada-002",
    input="世界"
).data[0].embedding

similarity = cosine_similarity(text1_embedding, text2_embedding)
print(f"相似度: {similarity}")

使用场景

语义搜索

import numpy as np
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    base_url="https://aigc.aochengcloud.com/v1"
)

# 知识库
documents = [
    "人工智能是计算机科学的一个分支",
    "机器学习是人工智能的一个子领域",
    "深度学习是机器学习的一个分支"
]

# 获取知识库的嵌入向量
doc_embeddings = []
for doc in documents:
    response = client.embeddings.create(
        model="text-embedding-ada-002",
        input=doc
    )
    doc_embeddings.append(response.data[0].embedding)

# 搜索函数
def search(query, top_k=3):
    # 获取查询的嵌入向量
    query_embedding = client.embeddings.create(
        model="text-embedding-ada-002",
        input=query
    ).data[0].embedding
    
    # 计算相似度
    similarities = []
    for i, doc_embedding in enumerate(doc_embeddings):
        similarity = np.dot(query_embedding, doc_embedding) / (
            np.linalg.norm(query_embedding) * np.linalg.norm(doc_embedding)
        )
        similarities.append((similarity, i))
    
    # 返回最相似的结果
    similarities.sort(reverse=True)
    return [(documents[idx], score) for score, idx in similarities[:top_k]]

# 使用
results = search("什么是深度学习？")
for doc, score in results:
    print(f"相似度: {score:.4f} - {doc}")

文本聚类

from sklearn.cluster import KMeans
import numpy as np

# 获取所有文本的嵌入向量
texts = ["文本1", "文本2", "文本3", ...]
embeddings = []
for text in texts:
    response = client.embeddings.create(
        model="text-embedding-ada-002",
        input=text
    )
    embeddings.append(response.data[0].embedding)

# 聚类
kmeans = KMeans(n_clusters=3)
clusters = kmeans.fit_predict(embeddings)

# 输出聚类结果
for i, text in enumerate(texts):
    print(f"文本: {text} -> 簇: {clusters[i]}")

推荐系统

def get_recommendations(user_input, candidate_items, top_k=5):
    # 获取用户输入的嵌入
    user_embedding = client.embeddings.create(
        model="text-embedding-ada-002",
        input=user_input
    ).data[0].embedding
    
    # 获取候选项目的嵌入
    item_embeddings = []
    for item in candidate_items:
        response = client.embeddings.create(
            model="text-embedding-ada-002",
            input=item
        )
        item_embeddings.append(response.data[0].embedding)
    
    # 计算相似度并排序
    similarities = []
    for i, item_embedding in enumerate(item_embeddings):
        similarity = np.dot(user_embedding, item_embedding) / (
            np.linalg.norm(user_embedding) * np.linalg.norm(item_embedding)
        )
        similarities.append((similarity, i))
    
    similarities.sort(reverse=True)
    return [(candidate_items[idx], score) for score, idx in similarities[:top_k]]

最佳实践

输入长度

  • 单次请求最大输入：8,191 tokens
  • 建议批量处理：每次请求 100-1000 条文本
  • 超长文本：先分句再嵌入

维度选择

  • text-embedding-ada-002: 1536 维，通用场景
  • text-embedding-3-small: 1536 维，高性价比
  • text-embedding-3-large: 3072 维，高精度场景

性能优化

# 批量处理提高效率
batch_size = 100
for i in range(0, len(texts), batch_size):
    batch = texts[i:i+batch_size]
    response = client.embeddings.create(
        model="text-embedding-ada-002",
        input=batch
    )
    # 处理结果

错误处理

错误码说明处理方式
400请求参数错误检查输入格式
401认证失败检查 API Key
429请求频率超限降低请求频率
500服务器错误稍后重试
最后更新: