Skip to Content
简体中文嵌入接口

嵌入接口 (Embeddings)

嵌入接口可将文本转换为高维向量表示,用于语义搜索、文本相似度计算、聚类分析等应用场景。

接口地址

POST https://aiapi.services/v1/embeddings

鉴权方式

所有请求需要在HTTP头中包含您的API密钥:

Authorization: Bearer YOUR_API_KEY

支持的模型

向量嵌入模型

  • text-embedding-004 - 第4代文本嵌入模型,用于语义搜索和向量化表示

完整模型列表请查看 可用模型

请求参数

必需参数

参数类型说明
modelstring要使用的模型ID,例如 text-embedding-3-small
inputstring/array要转换为向量的文本,可以是单个字符串或字符串数组

可选参数

参数类型默认值说明
encoding_formatstringfloat返回格式:floatbase64
dimensionsinteger-输出向量的维度(仅部分模型支持)
userstring-终端用户的唯一标识符

代码示例

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 } }

响应字段说明

字段类型说明
objectstring对象类型,固定为 "list"
dataarray嵌入向量数组,每个元素对应一个输入文本
data[].objectstring固定值 "embedding"
data[].indexinteger输入文本在批量请求中的索引(从0开始)
data[].embeddingarray[float]浮点数向量,维度取决于模型:
• text-embedding-3-small: 1536维
• text-embedding-3-large: 3072维
• text-embedding-004: 768维
modelstring实际使用的模型名称
usage.prompt_tokensinteger输入文本消耗的token数量
usage.total_tokensinteger总消耗token数(对于embedding API,等于prompt_tokens)

向量维度说明

不同模型返回不同维度的向量:

模型维度用途
text-embedding-3-small1536通用嵌入,性价比高
text-embedding-3-large3072高精度嵌入,准确度更高
text-embedding-004768Google的文本嵌入模型
text-embedding-ada-0021536经典模型,向后兼容

错误响应

当请求失败时,返回标准错误格式。详见错误处理文档

{ "code": "invalid_request_error", "message": "Invalid parameter: input text too long", "data": null }

批量处理

一次请求可以处理多个文本,提高效率:

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-small1536★★★☆★★★★★通用、大规模应用
text-embedding-3-large3072★★★★★★★★☆高精度需求
text-embedding-ada-0021536★★★☆★★★★稳定性优先
textembedding-gecko768★★★☆★★★★多语言场景

相关资源

Last updated on