OpenAI Embeddings API 怎么用？

官方资料（2026-10-31 核对）：Vector embeddings guide · Create embeddings API Reference · text-embedding-3-small · text-embedding-3-large

Embeddings API 与 File Search 有什么区别？

Embeddings API 不会自动保存向量，也不会替你搜索。需要托管知识库时阅读 OpenAI File Search 指南；需要管理原始文件时查看 Files API 生命周期。不要因为向量“看不懂”就把它当成脱敏结果，授权仍必须在查询端执行。

第一步：选择模型和维度

两种第三代模型都支持 dimensions 参数缩短输出。降维会减少数据库存储、内存和相似度计算成本，但不能假设质量不变。为每个候选维度使用相同的语料、query 集、K 值和过滤条件评测，并把 model、dimensions、切分版本写入索引元数据。

价格为 2026-10-31 官方模型页显示的同步 Embeddings 输入价格，未来可能调整；批量离线任务应单独核对 Batch API 当时支持的端点、折扣和完成窗口。

第二步：调用 /v1/embeddings

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.embeddings.create({
  model: "text-embedding-3-small",
  input: [
    "退款申请应从原购买渠道提交。",
    "API Credits 与 ChatGPT Plus 分开计费。"
  ],
  encoding_format: "float"
});

for (const item of response.data) {
  console.log(item.index, item.embedding.length);
}
console.log(response.usage.total_tokens);

服务端 SDK 会从环境变量读取 API Key，浏览器页面不应直接持有密钥。返回的 data 数组包含 index 与 embedding，用 index 对齐原输入；usage 提供本次输入 Token。若网络或 5xx 失败，使用有限次数指数退避，并保留输入内容哈希作为幂等去重依据。

请求限制怎样拆分？

• 单个输入：当前所有 embedding 模型最大输入为 8192 tokens；空字符串不可提交。
• 批量数量：一次请求的输入数组最多 2048 项。
• 总 Token：一次请求内所有输入合计最多 300,000 tokens。
• 输出格式：encoding_format 可选 float 或 base64；数据库字段与解码流程要匹配。
• 维度参数：仅 text-embedding-3 及后续模型支持；切换 dimensions 后必须使用新的索引版本。

不要按字符数估算中文 Token。可使用官方指南推荐的 tiktoken 和 cl100k_base 在入队前计数；超长正文按语义边界分块，同时保留来源、标题、章节和偏移位置。

第三步：建立可迁移的向量索引

文档更新时先写入新版本索引，完成回填、质量评测和权限抽查后，再切换查询别名并延迟清理旧索引。不要在原索引中静默混入另一模型或另一维度；即使数据库允许写入，也会使距离不可比较或直接查询失败。

第四步：把查询向量化并进行相似度搜索

1. 使用与文档相同的模型、dimensions 和规范化规则处理 query。
2. 在向量数据库中先应用租户、权限、语言、有效期和内容版本过滤。
3. 按余弦相似度或等价点积查询 Top K；不要照搬固定阈值。
4. 把命中 chunk 的原文、来源和分数返回应用；需要生成回答时再交给模型。
5. 记录 query、候选集合、命中 ID、最终点击或人工相关性，用于后续评测。

OpenAI 指南推荐余弦相似度，并说明 embedding 已归一化为长度 1，因此点积可以更快地得到等价排序；欧氏距离也会得到相同排序。数据库的近似索引参数、过滤顺序和量化方式仍会改变召回，应在自己的部署上测量。

怎样评测向量检索，而不是只看“能搜到”？

• 建立带答案的 query 集：覆盖高频、长尾、同义词、多语言、否定和无答案问题。
• 离线指标：至少记录 Recall@K、MRR 或 NDCG，并分租户、语言、内容类型观察。
• 端到端指标：如果检索结果交给生成模型，还要评测答案正确性、引用匹配和拒答。
• 成本指标：区分首次文档回填、增量更新和实时查询 Token；与数据库存储及查询费用一起核算。
• 对照实验：一次只改变模型、维度、chunk 或 K 中的一项，防止错误归因。

常见错误与排查

• 400 / 输入过长：用 Token 计数而不是字符数，拆分单项并控制请求总 Token。
• 向量维度不一致：读取索引的 model 与 dimensions 元数据，确认查询请求未切换配置。
• 结果语义相近但业务无权访问：把租户和 ACL 作为数据库过滤条件，不要在取回结果后才隐藏。
• 批量响应和输入错位：使用响应 index 映射原数组，不依赖异步任务完成顺序。
• 成本突然上升：检查重复回填、内容哈希、chunk 数量、失败重试与所用模型；再到 API Usage 按 Project 对账。
• 换模型后召回下降：不能复用旧文档向量；新旧索引要并行评测并原子切换。

上线前检查清单

• API Key 仅存在服务端，使用独立 Project 与最小权限。
• 输入拒绝空字符串，并在入队前检查单项和请求总 Token。
• model、dimensions、切分版本和内容哈希写入每条向量记录。
• 查询和文档使用相同配置，数据库字段维度固定。
• 租户与 ACL 在相似度查询阶段强制过滤，并做越权回归测试。
• 批量结果用 index 对齐，失败项可单独重试且不会重复写入。
• 上线前有真实 query 集、Recall@K、下游质量、延迟与成本基线。
• 模型或维度变更走新索引、回填、灰度、切换和回滚流程。
• 监控 API 429/5xx、Token、数据库延迟、空结果率和索引版本。

常见问题

本文核对日期为 2026-10-31。模型、价格、请求限制、维度和 SDK 字段可能变化，生产调用前请再次读取官方 Embeddings guide、API Reference 与对应模型页。