AI Agent Guide 交互式章节
模块二 · RAG 检索与证据链路 Qdrant + TypeScript 3 个实验台

Embedding 与向量检索基础

文档已经切成一批 DocumentChunk,但机器还不知道“猫和狗很近,猫和量子力学很远”。这一步要把文字变成坐标,存进向量库,再按距离找邻居。

30 秒版 · 只记这 3 句 实验台数字均标明来源或“示意”
  1. 01 余弦相似度只看方向,不看长度。
  2. 02 选模型别看 MTEB 总分,看 Retrieval 分,最后用自己的问题集实测。
  3. 03 分数上不去先查 Chunk;只设 limit 不设阈值,噪音会直接喂给模型。

Embedding 的本质:把语义编码成坐标

Embedding 模型不生成文字,只输出一串定长数字,也就是文本在语义空间里的坐标。检索就是在这个空间里找离问题最近的点。

坐标的维度由模型决定:OpenAI text-embedding-3-small 输出 1536 维,text-embedding-3-large 输出 3072 维,阿里云百炼 text-embedding-v3 和开源的 BGE-M3 默认输出 1024 维。

“距离最近”在文本场景下通常用余弦相似度衡量,理论值域 -1 到 1。下面的二维示意图里拖动橙色箭头,或者直接 ,看排名会不会变。

实验台 01 · 向量空间直觉
2D 语义空间与余弦相似度探针
拖动橙色查询箭头,观察夹角 θ 如何决定排序,以及 score_threshold = 0.65 会过滤掉谁。示意:真实向量是 1024 维,这里投影到二维
语义维度 X 语义维度 Y
当前阈值:0.65
Top-K 相似度排序(余弦公式:cos θ = (A · B) / (‖A‖ ‖B‖))

模型怎么选:MTEB 是起点,不是终点

MTEB 总分混合了分类、聚类等和 RAG 无关的任务。选检索模型先看 Retrieval 分,最后以自己业务问题集上的 Recall@5 为准。

MTEB(项目主页)覆盖上百个数据集,Hugging Face 的实时排行榜通常是选型第一站。问题是,按总分挑模型很容易挑错。

先猜一下 据 2026 年 3 月英文 MTEB 榜单,NV-Embed-v2 总分 72.31,Gemini Embedding 001 总分 68.32。做企业知识库检索,哪个更值得先测?
拆开看:NV-Embed-v2 的 Retrieval 只有 62.65,Gemini Embedding 001 是 67.71。总分高的那个,检索反而更弱。
实验台 02 · 选型决策模拟
三种选型策略,三种后果
选一种你最可能用的策略,看它会把你带到哪里。
任务:给公司内部中文技术文档搭 RAG,约 20,000 个 chunk。
现状:Qdrant collection 已按 text-embedding-v3 建好,size: 1024。
英文 MTEB 公开分数 来源 · 2026-03 榜单
只列原稿中有出处的两个模型。维度来自各模型官方文档。
先在上面选一种策略
右侧会给出:选中谁、检索能力如何、要不要重建 collection,以及下一步该做什么。

为什么榜单高分到了私有语料上会失灵?主要有三点(参考 Pinecone 选型指南):MTEB 用的是新闻、维基等通用文本,和内部文档的词汇分布不同;部分模型的训练数据可能和公开基准有重叠;均分还掩盖了单项差异。

小模型反超大模型在 Embedding 领域很常见。BAAI 的 BGE-M3(arXiv:2402.03216、模型页)只有 568M 参数,支持 100 多种语言和 8192 token 上下文。决定效果的是训练任务和检索场景有多接近,而不是参数量。中文场景还可以测阿里开源的 Qwen3-Embedding(0.6B / 4B / 8B,官方博客)。

用 Qdrant 跑通从入库到检索的完整流程

入库必须批量请求并把原文放进 payload,检索必须同时设 limit 和 score_threshold,空结果直接拒答。

Qdrant 入库与检索双链路 结构示意
离线入库链路 DocumentChunk 按 BATCH_SIZE=50 分批 Batch Embedding 一次请求多条,降 RPM vector + payload 原文 / source / section 同存 Qdrant Collection Cosine · 1024 维锁定 在线检索链路 用户 Query 同一 Embedding 模型 Filter + Cosine 先按 metadata 缩小范围 limit + threshold 低于 score_threshold 丢弃 有结果 → 交还 LLM 空数组 → 安全拒答

在诸多向量数据库中,Qdrant 用 Rust 编写,Docker 一条命令即可启动,自带 Web Dashboard(http://localhost:6333/dashboard),且 TypeScript SDK(@qdrant/js-client-rest)类型完善,适合从本地原型一路用到生产。

API 定价与维度参考(本书示例默认配置)
本章代码默认复用阿里云百炼的 text-embedding-v3(¥0.5 / 1M token,1024 维,8192 上下文;计费文档)。其他常见选项:OpenAI text-embedding-3-small($0.02 / 1M,1536 维;官方文档)、text-embedding-3-large($0.13 / 1M,3072 维)、Voyage AI voyage-4-lite($0.02 / 1M,1024 维;定价页)、Google Gemini Embedding 001($0.15 / 1M,3072 维;Vertex AI 定价)。

入库时有两个工程细节最容易忽略:一是把多条文本合并成 input 数组做批量请求(Batch Upsert),避免触发速率限制;二是每个 point 除了存 vector,必须把原文和 source、section 放进 payload,否则检索命中后无法把文字内容交还给 LLM。

完整 TypeScript 实现:Qdrant 批量入库与过滤检索(embed-and-store.ts)
examples/rag/embedding-vector-search/embed-and-store.ts
import { QdrantClient } from "@qdrant/js-client-rest";
import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.ANTHROPIC_API_KEY, // 复用 DashScope 密钥
  baseURL: process.env.EMBEDDING_BASE_URL,
});
const qdrant = new QdrantClient({ host: "localhost", port: 6333 });

const COLLECTION = "knowledge_base";
const EMBEDDING_MODEL = process.env.EMBEDDING_MODEL ?? "text-embedding-v3";
const VECTOR_SIZE = 1024; // 必须与模型输出维度一致
const BATCH_SIZE = 50;

async function ensureCollection() {
  const { collections } = await qdrant.getCollections();
  if (!collections.some((c) => c.name === COLLECTION)) {
    await qdrant.createCollection(COLLECTION, {
      vectors: { size: VECTOR_SIZE, distance: "Cosine" },
    });
  }
}

async function ingestChunks(chunks: Array<{ text: string; metadata: { source: string; section?: string; chunkIndex: number } }>) {
  for (let i = 0; i < chunks.length; i += BATCH_SIZE) {
    const batch = chunks.slice(i, i + BATCH_SIZE);
    const response = await openai.embeddings.create({
      model: EMBEDDING_MODEL,
      input: batch.map((c) => c.text), // 批量请求,降低 RPM 压力
    });

    const points = batch.map((chunk, j) => ({
      id: i + j,
      vector: response.data[j].embedding,
      payload: {
        text: chunk.text,
        source: chunk.metadata.source,
        section: chunk.metadata.section ?? "",
        chunkIndex: chunk.metadata.chunkIndex,
      },
    }));

    await qdrant.upsert(COLLECTION, { points });
  }
}

async function search(query: string, limit = 5, scoreThreshold = 0.65, sourceFilter?: string) {
  const res = await openai.embeddings.create({ model: EMBEDDING_MODEL, input: query });
  const queryVector = res.data[0].embedding;

  const results = await qdrant.search(COLLECTION, {
    vector: queryVector,
    limit,
    score_threshold: scoreThreshold, // 低于此分数直接过滤
    with_payload: true,
    ...(sourceFilter ? { filter: { must: [{ key: "source", match: { value: sourceFilter } }] } } : {}),
  });

  if (results.length === 0) {
    return "没有找到相关内容,无法回答这个问题。"; // 宁可拒答,不用噪音误导 LLM
  }
  return results;
}

Top-K、相似度分数与 Chunk 质量

真实 RAG 检索拿到 0.70–0.80 就已可用。如果分数普遍偏低,先查 Chunk 是否混入太多概念,而不是急着换模型。

使用 Cosine 度量时,Qdrant 返回的 score 越高代表越相似(Qdrant Search 文档)。因为用户口语化提问和书面文档措辞不同,超过 0.85 反而少见。

如果精准提问的分数连 0.70 都上不去,往往不是模型不够强,而是 Chunk 内容太杂。一个 Chunk 里混入十几个概念,向量就变成了一锅“平均语义”,任何单一问题的相似度都会被拉低。

先猜一下 在同一份向量数据库资料上做实测:把 4 个主题塞进一个大 Chunk 时,查询“余弦相似度的值域是多少?”的分数是 0.53。按“每个 Chunk 只讲一个概念”拆细后,同一模型的检索分数会变成多少?
真实实验输出(chunk-quality-experiment.ts):从 0.53 直接跳到 0.85。聚焦的 Chunk 里只有一句话讲余弦相似度,向量完整捕捉了这个语义;大 Chunk 里这句话被其余三个话题稀释了。

在下面的实验台里,你可以切换真实实验的 3 个查询对比“大而杂”与“小而聚焦”的分数落差,也可以联动调整 limit、score_threshold 和 source 过滤,观察越界问题如何触发安全拒答。试试 。

实验台 03 · 切片实验与参数联调
Chunk 语义稀释对比 & Top-K / 阈值拦截器
上半部分为 实测 · chunk-quality-experiment.ts 真实分数;下半部分为 模拟 · Qdrant 过滤逻辑,参数实时同步上方代码。
Qdrant 检索参数联调(实时同步上方 TS 代码)
返回数量 limit 5
质量下限 score_threshold 0.65

选型与工程决策矩阵

把前面所有判断收敛成一张可按场景筛选的速查表。点击场景标签即可高亮对应策略。

起点首选
先用 text-embedding-v3 跑通

复用现有 DashScope 密钥,1024 维中英文均衡,先把入库、payload、检索整条链路跑通,比前期纠结榜单更划算。

中文与本地化
BGE-M3 或 Qwen3-Embedding

568M 的 BGE-M3 同样是 1024 维,与 text-embedding-v3 切换无需重建 Qdrant collection;需要更高精度可测 Qwen3-Embedding-4B。

榜单误区
只看 Retrieval 分 + 业务实测

不要看 MTEB 总分。收集 100 到 200 个真实业务问题测 Recall@5 和 MRR,私有数据上的得分才是最终依据。

低分排查
分数普遍 < 0.70 先查切片

大而杂的 chunk 会稀释向量语义。把一个大块拆成单一概念小块,同一模型的相似度就能从 0.53 跃升到 0.85。

防幻觉兜底
limit 与 score_threshold 并用

无重排时先设 limit=5、threshold=0.65。当返回空数组时直接拒答,不要把 0.5 分的噪音塞给大模型。

能力边界
纯向量搞不定精确专有名词

问“GDPR 第 17 条”而文档写“被遗忘权”时,向量距离可能不够近。这正是下一章“混合检索与重排”要补上的缺口。

到这里,离线入库和在线向量检索的骨架已经立住了。不过纯向量检索有一个天然短板:对精确词汇、报错码、条款编号不敏感。下一章会引入 BM25 关键词检索、RRF 排名融合以及 Cross-Encoder 重排,把召回率和准确率再推高一个台阶。