嵌入接口 (Embeddings)
嵌入接口可将文本转换为高维向量表示,用于语义搜索、文本相似度计算、聚类分析等应用场景。
接口地址
POST https://aiapi.services/v1/embeddings鉴权方式
所有请求需要在HTTP头中包含您的API密钥:
Authorization: Bearer YOUR_API_KEY支持的模型
向量嵌入模型
text-embedding-004- 第4代文本嵌入模型,用于语义搜索和向量化表示
完整模型列表请查看 可用模型。
请求参数
必需参数
| 参数 | 类型 | 说明 |
|---|---|---|
model | string | 要使用的模型ID,例如 text-embedding-3-small |
input | string/array | 要转换为向量的文本,可以是单个字符串或字符串数组 |
可选参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
encoding_format | string | float | 返回格式:float 或 base64 |
dimensions | integer | - | 输出向量的维度(仅部分模型支持) |
user | string | - | 终端用户的唯一标识符 |
代码示例
cURL
curl https://aiapi.services/v1/embeddings \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "text-embedding-3-small",
"input": "人工智能正在改变世界"
}'响应格式
标准响应
{
"object": "list",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [
-0.008906792,
-0.013267784,
0.0234567,
// ... 1536个浮点数
]
}
],
"model": "text-embedding-3-small",
"usage": {
"prompt_tokens": 8,
"total_tokens": 8
}
}响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
object | string | 对象类型,固定为 "list" |
data | array | 嵌入向量数组,每个元素对应一个输入文本 |
data[].object | string | 固定值 "embedding" |
data[].index | integer | 输入文本在批量请求中的索引(从0开始) |
data[].embedding | array[float] | 浮点数向量,维度取决于模型: • text-embedding-3-small: 1536维 • text-embedding-3-large: 3072维 • text-embedding-004: 768维 |
model | string | 实际使用的模型名称 |
usage.prompt_tokens | integer | 输入文本消耗的token数量 |
usage.total_tokens | integer | 总消耗token数(对于embedding API,等于prompt_tokens) |
向量维度说明
不同模型返回不同维度的向量:
| 模型 | 维度 | 用途 |
|---|---|---|
| text-embedding-3-small | 1536 | 通用嵌入,性价比高 |
| text-embedding-3-large | 3072 | 高精度嵌入,准确度更高 |
| text-embedding-004 | 768 | Google的文本嵌入模型 |
| text-embedding-ada-002 | 1536 | 经典模型,向后兼容 |
错误响应
当请求失败时,返回标准错误格式。详见错误处理文档。
{
"code": "invalid_request_error",
"message": "Invalid parameter: input text too long",
"data": null
}批量处理
一次请求可以处理多个文本,提高效率:
JavaScript
const response = await fetch('https://aiapi.services/v1/embeddings', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'text-embedding-3-small',
input: [
'人工智能正在改变世界',
'机器学习是AI的重要分支',
'深度学习推动了AI的发展'
]
})
});
const data = await response.json();
data.data.forEach((item, index) => {
console.log(`文本${index + 1}的向量维度: ${item.embedding.length}`);
});💡 批量处理提示: 批量请求可以显著降低API调用次数,建议每批最多包含2048个输入文本。
应用场景
1. 语义搜索
计算查询与文档之间的相似度:
import numpy as np
from numpy.linalg import norm
def cosine_similarity(a, b):
return np.dot(a, b) / (norm(a) * norm(b))
# 计算文档向量
documents = [
"人工智能的发展历程",
"机器学习算法详解",
"深度学习框架对比"
]
doc_embeddings = []
for doc in documents:
response = requests.post(
'https://aiapi.services/v1/embeddings',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
json={'model': 'text-embedding-3-small', 'input': doc}
)
doc_embeddings.append(response.json()['data'][0]['embedding'])
# 计算查询向量
query = "什么是AI?"
query_response = requests.post(
'https://aiapi.services/v1/embeddings',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
json={'model': 'text-embedding-3-small', 'input': query}
)
query_embedding = query_response.json()['data'][0]['embedding']
# 计算相似度
similarities = [cosine_similarity(query_embedding, doc_emb) for doc_emb in doc_embeddings]
# 按相似度排序
ranked_docs = sorted(zip(documents, similarities), key=lambda x: x[1], reverse=True)
for doc, score in ranked_docs:
print(f'{doc}: {score:.4f}')2. 文本聚类
将相似文本分组:
from sklearn.cluster import KMeans
import numpy as np
# 获取文本向量
texts = ['文本1', '文本2', '文本3', ...] # 您的文本列表
embeddings = []
for text in texts:
response = requests.post(
'https://aiapi.services/v1/embeddings',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
json={'model': 'text-embedding-3-small', 'input': text}
)
embeddings.append(response.json()['data'][0]['embedding'])
# K-means聚类
embeddings_array = np.array(embeddings)
kmeans = KMeans(n_clusters=3, random_state=42)
clusters = kmeans.fit_predict(embeddings_array)
# 输出聚类结果
for i, cluster in enumerate(clusters):
print(f'{texts[i]} → 分组 {cluster}')3. 推荐系统
基于内容的相似度推荐:
def recommend_similar_items(target_item, all_items, top_n=5):
# 获取目标项的向量
target_response = requests.post(
'https://aiapi.services/v1/embeddings',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
json={'model': 'text-embedding-3-small', 'input': target_item}
)
target_embedding = target_response.json()['data'][0]['embedding']
# 计算与所有项的相似度
similarities = []
for item in all_items:
if item == target_item:
continue
item_response = requests.post(
'https://aiapi.services/v1/embeddings',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
json={'model': 'text-embedding-3-small', 'input': item}
)
item_embedding = item_response.json()['data'][0]['embedding']
similarity = cosine_similarity(target_embedding, item_embedding)
similarities.append((item, similarity))
# 返回最相似的top_n项
return sorted(similarities, key=lambda x: x[1], reverse=True)[:top_n]维度缩减
部分模型支持自定义输出维度,可以在不显著降低质量的情况下减少向量大小:
# 使用较小的维度
response = requests.post(
'https://aiapi.services/v1/embeddings',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
json={
'model': 'text-embedding-3-large',
'input': '人工智能正在改变世界',
'dimensions': 256 # 从3072缩减到256
}
)⚠️ 注意: 维度缩减会略微降低向量质量,建议在存储空间有限时使用。
最佳实践
1. 选择合适的模型
- text-embedding-3-small: 性价比高,适合大规模应用
- text-embedding-3-large: 精度更高,适合对质量要求高的场景
- text-embedding-ada-002: 经典稳定,适合已有集成的系统
2. 文本预处理
在生成嵌入之前,建议:
- 去除多余的空格和换行符
- 统一文本格式(如转小写)
- 限制文本长度(建议不超过8192 tokens)
3. 批量处理优化
// 分批处理大量文本
async function batchEmbeddings(texts, batchSize = 100) {
const results = [];
for (let i = 0; i < texts.length; i += batchSize) {
const batch = texts.slice(i, i + batchSize);
const response = await fetch('https://aiapi.services/v1/embeddings', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'text-embedding-3-small',
input: batch
})
});
const data = await response.json();
results.push(...data.data);
}
return results;
}4. 缓存向量结果
对于不经常变化的文本,缓存其向量可以显著降低成本:
import hashlib
import redis
redis_client = redis.Redis(host='localhost', port=6379, db=0)
def get_embedding_with_cache(text, model='text-embedding-3-small'):
# 生成缓存键
cache_key = f'embedding:{model}:{hashlib.md5(text.encode()).hexdigest()}'
# 检查缓存
cached = redis_client.get(cache_key)
if cached:
return json.loads(cached)
# 调用API
response = requests.post(
'https://aiapi.services/v1/embeddings',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
json={'model': model, 'input': text}
)
embedding = response.json()['data'][0]['embedding']
# 存入缓存(30天过期)
redis_client.setex(cache_key, 30 * 24 * 3600, json.dumps(embedding))
return embedding错误处理
常见错误码
| 状态码 | 说明 | 解决方案 |
|---|---|---|
| 401 | 未授权 | 检查API密钥是否正确 |
| 400 | 请求参数错误 | 检查输入文本和模型名称 |
| 413 | 输入文本过长 | 分割文本或减少批量大小 |
| 429 | 请求过于频繁 | 降低请求频率或升级配额 |
| 500 | 服务器错误 | 稍后重试 |
错误处理示例
import requests
from requests.exceptions import RequestException
import time
def get_embedding_with_retry(text, max_retries=3):
for attempt in range(max_retries):
try:
response = requests.post(
'https://aiapi.services/v1/embeddings',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
json={
'model': 'text-embedding-3-small',
'input': text
},
timeout=30
)
if response.status_code == 429:
# 请求过于频繁,等待后重试
wait_time = 2 ** attempt
time.sleep(wait_time)
continue
response.raise_for_status()
return response.json()['data'][0]['embedding']
except RequestException as e:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt)
raise Exception(f'Failed after {max_retries} retries')性能对比
| 模型 | 维度 | 性能 | 成本 | 适用场景 |
|---|---|---|---|---|
| text-embedding-3-small | 1536 | ★★★☆ | ★★★★★ | 通用、大规模应用 |
| text-embedding-3-large | 3072 | ★★★★★ | ★★★☆ | 高精度需求 |
| text-embedding-ada-002 | 1536 | ★★★☆ | ★★★★ | 稳定性优先 |
| textembedding-gecko | 768 | ★★★☆ | ★★★★ | 多语言场景 |
相关资源
Last updated on