首页 / 嵌入与检索 API

嵌入与检索 API

苏姆卡皮 · OpenAI 兼容 AI API 网关 · Base URL https://sub.sumcapi.top/v1

嵌入（Embeddings）是把文本变成向量的一次调用——知识库召回、相似度去重、聚类与推荐都依赖它。苏姆卡皮通过 /v1/embeddings 提供统一的 OpenAI 兼容入口。

嵌入与检索 API

什么时候需要它

• RAG 召回：把文档切片向量化，提问时先召回 Top-K 片段，再交给对话模型生成。
• 语义去重与聚类：工单、评论、素材标题的近似判重，比关键词匹配更稳。
• 分类与相似度排序：用向量距离做粗筛，再用对话模型做精判，成本远低于全部交给大模型。

接口形状

curl https://sub.sumcapi.top/v1/embeddings \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-large",
    "input": ["幂等设计要点", "指数退避与抖动", "缓存命中与成本"]
  }'

from openai import OpenAI

client = OpenAI(base_url="https://sub.sumcapi.top/v1", api_key="sk-你的密钥")
r = client.embeddings.create(model="text-embedding-3-large",
                             input=["示例文本 A", "示例文本 B"])
print(len(r.data[0].embedding), r.usage.total_tokens)

要点：input 支持字符串与字符串数组，一次批量比逐条调用省往返；返回的 usage.total_tokens 是计费依据。

选型：维度不是越大越好

维度翻倍通常意味着向量存储与检索成本同步上涨。先用轻量档跑通链路，再按召回质量决定是否升档。

切片与索引实践

1. 按语义切片：以标题或段落为边界，300–800 token 一档，保留 10–15% 重叠，避免句子被切断。
2. 带上上下文头：切片前拼一小段"该内容来自 X 文档的 Y 章节"，召回质量提升明显。
3. 版本化索引：文档更新时写入新索引再切换别名，避免召回结果半新半旧。
4. 错峰批量：全量重建索引会产生大量 token 消耗，安排在业务低谷时段并分批提交。
5. 混合检索：向量与关键词双路召回再融合排序，对专有名词与型号更友好。

计费与限流

• 按 输入 token 计费，向量本身不额外收费；存储与检索由你自己的向量库承担。
• 批量提交建议控制在个位数并发，遇到 429 使用指数退避，口径见 模型定价。
• 可用模型名以模型广场为准，参数与示例见 嵌入模型指南。

下一步

• 生成阶段用什么模型：文本与对话 API
• 长文档是塞进上下文还是走 RAG：长上下文与缓存
• 全部能力入口：能力与场景

常见问题