Embeddings 与 RAG 检索示例

Embeddings 是把文本转换成向量的技术。向量不是回答本身，而是检索层的“坐标 系”：它让系统能判断两段文字是否语义相近，从而支持文档搜索、FAQ 匹配、相 似内容推荐、资料聚类和 RAG。

如果你正在用 OfApp.cn 接入 OpenAI-compatible API，要先确认当前账号、控制 台和官方文档是否开放 Embeddings。OfApp.cn 官方 API 示例页当前将 /v1/embeddings 标注为“暂不可用”；如果控制台或官方文档后续更新，请以当 前 OfApp.cn 控制台或官方文档为准。

先确认接口可用，再建设向量索引

Embeddings 适合语义搜索和 RAG，但向量索引一旦建成就和模型、维度、切块策略绑定。使用 OfApp.cn 时，请先确认当前控制台和官方文档是否开放对应 embedding 能力。

查看 API 示例

项目	说明
阅读时间	约 5 分钟
更新时间	2026-07-02
适合读者	开发者、知识库维护者、产品经理、研究者、正在做 RAG 的团队
适合任务	语义搜索、FAQ 匹配、文档切块、RAG 检索、向量索引设计

Embeddings 是什么

Embedding 是一组数字，表示文本在语义空间里的位置。两段文本含义相近时，它 们的向量距离通常也更近。应用系统会把文档、问题、标题、摘要或资料片段转成 向量，再用相似度检索找出最相关的内容。

它常被误解成“让模型记住知识”。更准确地说，Embeddings 负责把候选资料找出 来；真正生成回答的仍然是聊天、Responses 或其他生成接口。RAG 就是把这两段 流程接起来：先检索，再带着资料回答。

从文本到检索的流程图

什么时候应该用

场景	适合用 Embeddings 吗	原因
FAQ 自动匹配	适合	用户问法变化大，关键词搜索容易漏
内部知识库搜索	适合	文档标题和真实问题常常不一致
RAG 问答	适合	需要先召回资料，再让模型基于资料回答
文档聚类	适合	可按语义相似度分组
简单精确过滤	不一定	状态、日期、价格、ID 更适合结构化查询
法务或财务结论	谨慎	检索结果必须可追溯，不能只看相似度

调用前检查

检查项	怎么确认	为什么重要
端点是否可用	看服务商官方文档和控制台	OfApp.cn 当前示例页标注 Embeddings 暂不可用
模型是否是 embedding 模型	调用 Models API 或查看文档	聊天模型不能直接当作向量模型
维度是否固定	记录返回向量长度或 dimensions 参数	同一索引不能混用不同维度
输入是否过长	按模型限制切块	过长会失败，过短会丢上下文
数据是否敏感	脱敏、授权、最小化上传	向量化前仍然要保护原文
索引是否可重建	保存模型名、版本、维度、切块参数	换模型后通常需要重建索引

最小请求

下面是通用 OpenAI-compatible 写法。只有在你的 OfApp.cn 控制台或官方文档确 认 Embeddings 可用时，才应把它用于真实调用。示例 Key 和模型名都是占位符。

export OPENAI_BASE_URL="https://api.ofapp.cn/v1"
export OPENAI_API_KEY="sk-xxxx"
export OPENAI_EMBEDDING_MODEL="以控制台可用 embedding 模型为准"

curl -sS "$OPENAI_BASE_URL/embeddings" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$OPENAI_EMBEDDING_MODEL"'",
    "input": [
      "AI 办公适合整理会议纪要。",
      "向量可以用于语义搜索和 RAG。"
    ],
    "encoding_format": "float"
  }'

OpenAI API 文档中，Embeddings API 的核心参数是 model 和 input，返回结 果里包含 data[].embedding。部分 embedding 模型支持 dimensions 参数， 可以用较短向量适配向量数据库的维度限制；是否可用要看具体模型。

Python 示例

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ["OPENAI_BASE_URL"],
)

response = client.embeddings.create(
    model=os.environ["OPENAI_EMBEDDING_MODEL"],
    input=[
        "AI 办公适合整理会议纪要。",
        "向量可以用于语义搜索和 RAG。",
    ],
    encoding_format="float",
)

for item in response.data:
    print(item.index, len(item.embedding))

如果服务返回 model not found、404 或端点不可用，应先回到控制台和官方 文档确认 Embeddings 是否开放，而不是改用聊天模型名硬试。

JavaScript 示例

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL,
});

const response = await client.embeddings.create({
  model: process.env.OPENAI_EMBEDDING_MODEL,
  input: [
    "AI 办公适合整理会议纪要。",
    "向量可以用于语义搜索和 RAG。",
  ],
  encoding_format: "float",
});

console.log(response.data.map((item) => item.embedding.length));

服务端代码里不要把 API Key 下发到浏览器。前端搜索框应该请求你自己的后端， 再由后端调用 Embeddings、向量数据库和生成接口。

切块与元数据

RAG 效果很大程度取决于切块，而不是只取决于向量模型。一个可维护的 chunk 通常需要同时保存正文和元数据。

字段	示例	用途
id	doc-12#chunk-04	追踪来源和去重
text	当前片段正文	生成向量和拼接上下文
title	文档标题	给用户展示来源
url	/office/meeting-notes-ai/	回链和引用
section	行动项	让召回片段有语境
updatedAt	2026-07-02	判断资料新旧
embeddingModel	环境变量中的模型名	重建索引时比对
dimensions	返回向量长度	防止混用不同索引

切块太长会让召回结果含噪声；切块太短会丢上下文。常见做法是按标题、段落、 列表和代码块边界切分，再保留相邻片段或章节标题作为上下文。

相似度计算

多数向量数据库会内置相似度检索。理解余弦相似度有助于调试召回结果：

function cosineSimilarity(a, b) {
  if (a.length !== b.length) {
    throw new Error("Embedding dimensions must match");
  }

  let dot = 0;
  let normA = 0;
  let normB = 0;

  for (let index = 0; index < a.length; index += 1) {
    dot += a[index] * b[index];
    normA += a[index] * a[index];
    normB += b[index] * b[index];
  }

  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
}

如果相似度结果很怪，常见原因不是公式，而是切块不稳、查询没有改写、索引里 混了不同模型或维度，或者召回后没有用元数据过滤。

索引一致性

向量索引一旦上线，要把这些信息记录下来：

项目	记录方式	换了会怎样
embedding 模型	环境变量和索引元数据	通常需要重建向量
向量维度	表结构或索引配置	维度不一致会写入失败
切块规则	代码和迁移说明	召回质量会变化
文档版本	updatedAt 或内容 hash	需要增量更新
过滤字段	标签、栏目、权限、语言	影响用户看到哪些结果
权限边界	用户、团队、项目	防止跨权限检索

不要把所有资料都放进一个无边界索引。企业资料、公开文档、用户私有文件和内 部运营材料应有不同的权限和过滤策略。

常见错误

现象	常见原因	修复方向
model not found	模型不是 embedding 模型或当前账号不可用	从控制台或 Models API 复制可用模型
404	端点不开放、路径错误或 Base URL 拼接错误	确认 /v1/embeddings 是否可用
维度不一致	同一索引混用不同模型或参数	固定模型、维度和索引 schema
检索效果差	切块过长、元数据不足、Top K 不合适	调整 chunk、过滤和重排
回答编造	只召回不复核，或片段没放进上下文	要求模型基于片段回答并列出来源
隐私风险	上传了未授权原文	脱敏、权限过滤、最小化索引内容

隐私与安全边界

Embeddings 不是脱敏工具。生成向量前，原文仍会被发送到 API 服务或你选择的 计算环境中。敏感场景要先回答几个问题：

问题	建议
是否包含个人信息、合同、财务或医疗内容？	做脱敏和权限确认
是否需要用户级隔离？	索引中保存用户或租户字段
是否允许跨项目搜索？	默认不允许，除非有明确授权
是否需要删除权？	保留原文与向量的映射，支持删除和重建
是否会把片段交给生成模型？	在回答中显示来源，避免隐藏引用

常见问题

Embeddings 是否等于 RAG？

不是。Embeddings 只负责把文本变成向量并支持相似度检索。RAG 还需要切块、 索引、查询改写、召回、重排、上下文拼接、回答生成和来源复核。

OfApp.cn 现在可以直接调用 Embeddings 吗？

请以 OfApp.cn 控制台或官方文档为准。当前 OfApp.cn API 示例页将 /v1/embeddings 标注为“暂不可用”，因此真实项目接入前要先确认可用性。

可以混用不同 embedding 模型吗？

不建议在同一个向量索引中混用。不同模型可能有不同维度和语义空间，会让相似 度比较失真。换模型时通常要重建索引。

dimensions 参数一定要设置吗？

不一定。OpenAI 文档说明部分 embedding 模型支持 dimensions，可缩短返回向 量以适配向量库限制。是否支持取决于具体模型；如果不确定，先使用默认维度并 记录返回长度。

语义搜索为什么召回不准？

常见原因是切块过长、标题和正文分离、缺少元数据过滤、Top K 太小或太大、查 询没有改写，或者索引里混入了不同模型生成的向量。

可以把用户私有文档直接向量化吗？

只有在用户授权、权限隔离和删除机制都清楚时才应该做。向量化不是匿名化，原 文上传、索引存储和回答引用都需要遵守隐私边界。

参考依据

• OpenAI Embeddings API Reference：说明 /v1/embeddings、input、model、encoding_format 和返回向量结构。
• OpenAI Embeddings Guide：说明获取向量、维度缩短和向量后处理思路。
• OfApp.cn API 直转文档：当前 API 示例页将 Embeddings API 标注为暂不可用；实际可用性以控制台或官方文档为准。

相关文章

• OpenAI 兼容 API 快速调用：先验证 Base URL、Key 和模型名。
• Python SDK 示例：用 Python 接入 OpenAI-compatible API。
• JavaScript SDK 示例：用 Node.js 写服务端调用。
• model not found：排查模型名和账号可用范围。
• context length exceeded：理解文本切块和上下文压力。
• 研究 Prompt：把检索资料整理成可复核输出。
• AI 整理资料：把多段资料变成可检索知识结构。

带走什么

Embeddings 的价值在于让资料能被语义检索，但它不是 RAG 的全部。真正可靠的 系统需要确认端点可用、固定模型和维度、设计切块与元数据、保护隐私、记录索 引版本，并在生成回答时保留来源和人工复核空间。