如何提升向量搜索召回率:Vectra BM25混合检索实战指南

原创2026-11-13 18:44:361,914 阅读

如何提升向量搜索召回率:Vectra BM25混合检索实战指南

Vectra 是一个面向 Node.js 的本地向量数据库,而它内置的 BM25 混合检索(语义搜索 + 关键词搜索)正是提升向量搜索召回率最省事的办法之一。本文用实战步骤带你开启混合检索、判断何时该用、以及如何避开最常见的坑。

为什么纯语义搜索会"漏"结果

语义搜索靠 embedding 向量的余弦相似度排序,擅长处理同义改写,但在这些场景下容易漏召回:

  • 精确标识符:函数名、错误码、包名、API 字段名
  • 短查询:用户只输入两三个关键词时,语义信号很弱
  • 冷僻技术词:模型语料里少见,embedding 向量分布不准

结果是:相关内容明明在索引里,但相似度差一点,就掉出了 topK 之外——这就是召回率下降的根源。

Vectra BM25 混合检索的工作原理 🔍

在 src/LocalIndex.ts 的 queryItems 中,混合检索分四步执行:

  1. 语义检索先行:按余弦相似度选出 topK 个 chunk(v0.15 起使用堆优化,复杂度 O(N log K))
  2. 补建关键词索引:对未被语义检索选中的 chunk 建立 BM25 索引,底层是 wink-bm25 引擎,带分词、词干提取和否定词处理
  3. 关键词检索追加:BM25 的 top 匹配结果追加到语义结果之后,避免重复
  4. 来源标记:每个 BM25 命中的 chunk 会在元数据里打上 isBm25 标记,方便区分结果来源

两种检索各自的优势:

检索方式 擅长 短板
语义搜索(余弦相似度) 同义改写、自然语言问句 精确术语、短关键词
BM25 关键词搜索 精确词、标识符、错误码 不理解语义,换词就查不到

混合检索 = 两者互补,这正是召回率提升的核心逻辑。

一行代码开启混合检索 ⚡

TypeScript 中只需在 queryDocuments 的选项里加一个布尔值:

const results = await docs.queryDocuments('error handling patterns', {
  maxDocuments: 5,
  maxChunks: 20,
  isBm25: true, // 一行开启混合检索:语义 + BM25 关键词
});

各接入方式对应的开关:

什么场景该开、什么场景不用开

✅ 建议开启(来自 docs/documents.md 的官方建议):

  • 查询包含精确词(函数名、错误码、标识符)
  • 希望捕获语义搜索可能漏掉的匹配
  • 用户搜索使用简短的、关键词密集的查询

🚫 可以不开:纯自然语言问答、你只想要单一风格的结果时,纯语义检索更干净。

验证效果:用 isBm25 标记检查结果来源

开启混合检索后,用 renderSections 渲染上下文时,每个 section 都会返回 isBm25 标志,让你确认哪些段落是关键词匹配进来的(实现见 src/LocalDocumentResult.ts):

const sections = await results[0].renderSections(2000, 1, true);
for (const s of sections) {
  console.log(s.isBm25 ? '关键词匹配' : '语义匹配', s.score.toFixed(4));
}

这是评估混合检索是否真正帮你捞回了缺失内容的最直接手段。

调优召回率:3 个值得检查的参数

参数 默认值 作用
maxChunks 50 每次查询评估的 chunk 上限,越大越全面但越慢
maxDocuments 10 返回的文档数上限
chunkSize 512 tokens 索引时的切块大小,建索引时设定
  • 召回率仍不理想时,优先调大 maxChunks,让更多 chunk 参与 BM25 评估
  • 切块太大(把多个主题切进一个 chunk)或太小(上下文断裂)都会伤召回,512 tokens 是官方推荐的起点,详见 docs/best-practices.md

常见坑:BM25 为什么没返回结果 ⚠️

官方排障指南里明确列出了三个原因:

  1. isBm25: true 必须在查询时传入——它不是索引配置,建索引时无法"预开启"
  2. 查询字符串不能为空,BM25 只处理非空 query
  3. 只有 topK 个 BM25 结果会被合并——如果语义检索已把热门 chunk 占满,BM25 补充的空间有限

另外注意:BM25 开销与未被语义选中的 chunk 数量成正比,中小规模索引下可忽略(官方给出的典型延迟:数百条 < 1ms,数千条 1–2ms)。

总结:召回率提升清单 📋

  • [ ] 查询含精确术语 / 短关键词 → 开启 isBm25: true
  • [ ] 用 renderSections 的 isBm25 标记验证补充效果
  • [ ] 仍不理想 → 调大 maxChunks
  • [ ] 检查切块参数 chunkSize / overlap
  • [ ] 无结果 → 确认查询时传参、query 非空

延伸阅读:

登录后查看全文
vectra