> ## Documentation Index > Fetch the complete documentation index at: https://docs.aioagi.tech/llms.txt > Use this file to discover all available pages before exploring further. # Embedding API > 通过 AIOAGI 的 OpenAI 兼容接口将文本转换为向量，用于语义搜索、RAG、相似度计算和文本分类。 Embedding API 基于 OpenAI 兼容的 `POST /embeddings` 接口。它可以把文本转换为向量表示，方便你在检索、聚类、推荐、RAG 和相似度计算中使用。 Embedding 模型、向量维度、计费方式和上下文限制可能变化。请以控制台和开发者指南显示的信息为准。 ## 功能概述文本向量可以捕捉文本的语义信息。常见用途包括： * 语义搜索：按含义检索内容，而不是只匹配关键词 * RAG 检索：为知识库、文档库和客服资料建立向量索引 * 相似度计算：判断两段文本的语义接近程度 * 文本分类：用最近邻或聚类方式做粗分类 * 内容推荐：根据文本相似度推荐文章、商品或问题 * 去重聚类：发现相近标题、相似问法和重复内容常用基础地址： ```text theme={null} https://api.aiearth.dev/v1 https://api.aiearth.vip/v1 ``` 请求路径： ```text theme={null} POST /embeddings ``` ## 快速开始在 AIOAGI 控制台创建 API Key，并确认 Token 组额度和 Embedding 模型权限可用。在控制台或开发者指南中查看可用模型 ID。示例中的 `text-embedding-3-large` 仅用于演示。 `input` 可以是一段字符串，也可以是字符串数组。批量输入时，请控制单次请求的文本数量和总长度。将返回的 `embedding` 写入数据库、向量库或缓存，并保留原文 ID，方便后续召回。 ## 基础示例使用 OpenAI Python SDK 创建单条文本向量： ```python theme={null} import os from openai import OpenAI client = OpenAI( api_key=os.environ["AIO_API_KEY"], base_url=os.environ.get("AIO_BASE_URL", "https://api.aiearth.dev/v1"), ) response = client.embeddings.create( model="text-embedding-3-large", input="人工智能正在改变世界。", ) embedding = response.data[0].embedding print("向量维度:", len(embedding)) print("前 5 个值:", embedding[:5]) ``` 等价的 `curl` 请求： ```bash theme={null} curl "https://api.aiearth.dev/v1/embeddings" \ -H "Authorization: Bearer $AIO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "text-embedding-3-large", "input": "人工智能正在改变世界。" }' ``` ## 批量处理一次请求可以传入多段文本。返回结果中的 `index` 与输入数组顺序对应。 ```python theme={null} texts = [ "机器学习是人工智能的一个分支。", "深度学习使用神经网络进行表示学习。", "自然语言处理让机器理解和生成语言。", ] response = client.embeddings.create( model="text-embedding-3-large", input=texts, ) embeddings = [item.embedding for item in response.data] print("处理文本数量:", len(embeddings)) ``` ## 核心参数 Embedding 模型 ID。请填写控制台当前可用的模型名称，例如 `text-embedding-3-small`、`text-embedding-3-large` 或其他平台支持的向量模型。要向量化的文本。可以传入单条字符串，也可以传入字符串数组进行批量处理。可选参数。部分模型支持指定输出维度。是否支持、取值范围和计费方式请以控制台和开发者指南为准。 ## 响应结构成功响应通常包含 `data` 和 `usage`。 ```json theme={null} { "object": "list", "data": [ { "object": "embedding", "embedding": [0.0023, -0.0093], "index": 0 } ], "usage": { "prompt_tokens": 8, "total_tokens": 8 } } ``` ## 实用示例 ### 计算文本相似度使用余弦相似度比较两段文本： ```python theme={null} import math def cosine_similarity(a, b): dot = sum(x * y for x, y in zip(a, b)) norm_a = math.sqrt(sum(x * x for x in a)) norm_b = math.sqrt(sum(y * y for y in b)) return dot / (norm_a * norm_b) response = client.embeddings.create( model="text-embedding-3-large", input=[ "我想了解 API 计费方式。", "请问接口费用怎么计算？", ], ) vec1 = response.data[0].embedding vec2 = response.data[1].embedding print(cosine_similarity(vec1, vec2)) ``` ### 语义搜索先离线为文档生成向量，再对用户查询生成向量并排序。 ```python theme={null} documents = [ {"id": "doc-1", "text": "AIOAGI 支持 OpenAI 兼容接口。"}, {"id": "doc-2", "text": "Token 组可用于额度管理。"}, {"id": "doc-3", "text": "图像生成接口支持多种模型。"}, ] doc_vectors = client.embeddings.create( model="text-embedding-3-large", input=[doc["text"] for doc in documents], ).data query_vector = client.embeddings.create( model="text-embedding-3-large", input="如何管理不同应用的额度？", ).data[0].embedding ranked = sorted( zip(documents, doc_vectors), key=lambda item: cosine_similarity(query_vector, item[1].embedding), reverse=True, ) print(ranked[0][0]) ``` ### 简单文本分类你可以为每个类别准备描述文本，并把输入文本归到最相似的类别。 ```python theme={null} labels = { "billing": "充值、计费、余额、价格、发票、额度", "technical": "接口调用、报错、模型参数、SDK、网络", "account": "登录、账号、API Key、权限、控制台", } label_response = client.embeddings.create( model="text-embedding-3-large", input=list(labels.values()), ) text_response = client.embeddings.create( model="text-embedding-3-large", input="我的 API Key 返回 401，应该怎么办？", ) text_vector = text_response.data[0].embedding label_vectors = [item.embedding for item in label_response.data] label_names = list(labels.keys()) best_index = max( range(len(label_vectors)), key=lambda i: cosine_similarity(text_vector, label_vectors[i]), ) print(label_names[best_index]) ``` ## 与向量数据库集成 Embedding API 只负责生成向量。向量的存储、索引、过滤和召回由你的应用或向量数据库完成。常见做法： * 保存 `id`、原文、元数据和向量 * 使用余弦相似度或内积建立索引 * 召回前先按业务字段过滤，例如项目、用户、时间或权限 * 召回后把原文片段传入文本生成 API 做回答示例数据结构： ```json theme={null} { "id": "doc-2026-001", "text": "AIOAGI 的 OpenAI 兼容接口基础地址为 https://api.aiearth.dev/v1。", "metadata": { "product": "aioagi", "source": "docs", "updated_at": "2026-05-15" }, "embedding": [0.0023, -0.0093] } ``` ## 最佳实践 ### 批量处理批量请求能减少网络开销，但不要把过多文本塞进单次请求。建议按文本长度和业务延迟要求分批。 ```python theme={null} def batches(items, size=64): for i in range(0, len(items), size): yield items[i:i + size] all_vectors = [] for batch in batches(texts): response = client.embeddings.create( model="text-embedding-3-large", input=batch, ) all_vectors.extend(item.embedding for item in response.data) ``` ### 文本预处理 * 去除无意义空白、HTML 标签和重复内容 * 对超长文档先切块，再分别生成向量 * 保留标题、路径、来源等元数据 * 让同一索引内的文本粒度尽量一致 ### 缓存向量相同文本可以复用向量。建议用文本哈希作为缓存键，避免重复计费和重复索引。 ```python theme={null} import hashlib def cache_key(text, model): digest = hashlib.sha256(text.encode("utf-8")).hexdigest() return f"{model}:{digest}" ``` ## 常见问题维度由模型决定，部分模型也可能支持 `dimensions` 参数。请以控制台和开发者指南中该模型的说明为准。可以。`input` 支持字符串数组。批量请求时请控制总长度，并按返回结果中的 `index` 对齐原始输入。常见原因包括文本切块过长、噪声太多、类别描述不清晰、查询与文档语言不一致，或选择的模型不适合当前场景。请按控制台、开发者指南和服务协议确认当前数据处理策略。生产环境不要上传不必要的敏感信息。 ## 相关文档可在导航中的 **文本 API** 分组查看文本生成指南，并使用召回片段生成最终回答。完成 API Key、端点和第一次模型调用。可在导航中的 **OpenAI 兼容接口** 分组查看 `POST /embeddings` 的 OpenAPI 参数参考。核对当前模型、端点和参数支持情况。