Skip to main content

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 基于 OpenAI 兼容的 POST /embeddings 接口。它可以把文本转换为向量表示，方便你在检索、聚类、推荐、RAG 和相似度计算中使用。
Embedding 模型、向量维度、计费方式和上下文限制可能变化。请以控制台和开发者指南显示的信息为准。

​
功能概述

文本向量可以捕捉文本的语义信息。常见用途包括：
  • 语义搜索：按含义检索内容，而不是只匹配关键词
  • RAG 检索：为知识库、文档库和客服资料建立向量索引
  • 相似度计算：判断两段文本的语义接近程度
  • 文本分类：用最近邻或聚类方式做粗分类
  • 内容推荐：根据文本相似度推荐文章、商品或问题
  • 去重聚类：发现相近标题、相似问法和重复内容
常用基础地址： 
https://api.aiearth.dev/v1
https://api.aiearth.vip/v1
请求路径： 
POST /embeddings

​
快速开始

1

准备 API Key

在 AIOAGI 控制台创建 API Key，并确认 Token 组额度和 Embedding 模型权限可用。
2

选择 Embedding 模型

在控制台或开发者指南中查看可用模型 ID。示例中的 text-embedding-3-large 仅用于演示。
3

发送输入文本

input 可以是一段字符串，也可以是字符串数组。批量输入时，请控制单次请求的文本数量和总长度。
4

保存向量

将返回的 embedding 写入数据库、向量库或缓存，并保留原文 ID，方便后续召回。

​
基础示例

使用 OpenAI Python SDK 创建单条文本向量： 
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 请求： 
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 与输入数组顺序对应。 
texts = [
    "机器学习是人工智能的一个分支。",
    "深度学习使用神经网络进行表示学习。",
    "自然语言处理让机器理解和生成语言。",
]

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

embeddings = [item.embedding for item in response.data]
print("处理文本数量:", len(embeddings))

​
核心参数

​
model
string
required
Embedding 模型 ID。请填写控制台当前可用的模型名称，例如 text-embedding-3-small、text-embedding-3-large 或其他平台支持的向量模型。
​
input
string | string[]
required
要向量化的文本。可以传入单条字符串，也可以传入字符串数组进行批量处理。
​
dimensions
integer
可选参数。部分模型支持指定输出维度。是否支持、取值范围和计费方式请以控制台和开发者指南为准。

​
响应结构

成功响应通常包含 data 和 usage。 
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.0023, -0.0093],
      "index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

​
实用示例

​
计算文本相似度

使用余弦相似度比较两段文本： 
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))

​
语义搜索

先离线为文档生成向量，再对用户查询生成向量并排序。 
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])

​
简单文本分类

你可以为每个类别准备描述文本，并把输入文本归到最相似的类别。 
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 做回答
示例数据结构： 
{
  "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]
}

​
最佳实践

​
批量处理

批量请求能减少网络开销，但不要把过多文本塞进单次请求。建议按文本长度和业务延迟要求分批。 
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 标签和重复内容
  • 对超长文档先切块，再分别生成向量
  • 保留标题、路径、来源等元数据
  • 让同一索引内的文本粒度尽量一致

​
缓存向量

相同文本可以复用向量。建议用文本哈希作为缓存键，避免重复计费和重复索引。 
import hashlib

def cache_key(text, model):
    digest = hashlib.sha256(text.encode("utf-8")).hexdigest()
    return f"{model}:{digest}"

​
常见问题

维度由模型决定，部分模型也可能支持 dimensions 参数。请以控制台和开发者指南中该模型的说明为准。
可以。input 支持字符串数组。批量请求时请控制总长度，并按返回结果中的 index 对齐原始输入。
常见原因包括文本切块过长、噪声太多、类别描述不清晰、查询与文档语言不一致，或选择的模型不适合当前场景。
请按控制台、开发者指南和服务协议确认当前数据处理策略。生产环境不要上传不必要的敏感信息。

​
相关文档

文本生成 API

可在导航中的 文本 API 分组查看文本生成指南，并使用召回片段生成最终回答。

快速开始

完成 API Key、端点和第一次模型调用。

OpenAI 兼容接口

可在导航中的 OpenAI 兼容接口 分组查看 POST /embeddings 的 OpenAPI 参数参考。

开发者指南

核对当前模型、端点和参数支持情况。