如何提升向量搜索召回率:Vectra BM25混合检索实战指南
如何提升向量搜索召回率:Vectra BM25混合检索实战指南
Vectra 是一个面向 Node.js 的本地向量数据库,而它内置的 BM25 混合检索(语义搜索 + 关键词搜索)正是提升向量搜索召回率最省事的办法之一。本文用实战步骤带你开启混合检索、判断何时该用、以及如何避开最常见的坑。
为什么纯语义搜索会"漏"结果
语义搜索靠 embedding 向量的余弦相似度排序,擅长处理同义改写,但在这些场景下容易漏召回:
- 精确标识符:函数名、错误码、包名、API 字段名
- 短查询:用户只输入两三个关键词时,语义信号很弱
- 冷僻技术词:模型语料里少见,embedding 向量分布不准
结果是:相关内容明明在索引里,但相似度差一点,就掉出了 topK 之外——这就是召回率下降的根源。
Vectra BM25 混合检索的工作原理 🔍
在 src/LocalIndex.ts 的 queryItems 中,混合检索分四步执行:
- 语义检索先行:按余弦相似度选出 topK 个 chunk(v0.15 起使用堆优化,复杂度 O(N log K))
- 补建关键词索引:对未被语义检索选中的 chunk 建立 BM25 索引,底层是 wink-bm25 引擎,带分词、词干提取和否定词处理
- 关键词检索追加:BM25 的 top 匹配结果追加到语义结果之后,避免重复
- 来源标记:每个 BM25 命中的 chunk 会在元数据里打上
isBm25标记,方便区分结果来源
两种检索各自的优势:
| 检索方式 | 擅长 | 短板 |
|---|---|---|
| 语义搜索(余弦相似度) | 同义改写、自然语言问句 | 精确术语、短关键词 |
| BM25 关键词搜索 | 精确词、标识符、错误码 | 不理解语义,换词就查不到 |
混合检索 = 两者互补,这正是召回率提升的核心逻辑。
一行代码开启混合检索 ⚡
TypeScript 中只需在 queryDocuments 的选项里加一个布尔值:
const results = await docs.queryDocuments('error handling patterns', {
maxDocuments: 5,
maxChunks: 20,
isBm25: true, // 一行开启混合检索:语义 + BM25 关键词
});
各接入方式对应的开关:
- CLI:
vectra query "你的查询" --bm25(BM25 命中的内容在终端中以蓝色显示),实现见 src/vectra-cli.ts - gRPC:查询请求里传
use_bm25: true,字段定义见 proto/vectra_service.proto
什么场景该开、什么场景不用开
✅ 建议开启(来自 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 为什么没返回结果 ⚠️
官方排障指南里明确列出了三个原因:
isBm25: true必须在查询时传入——它不是索引配置,建索引时无法"预开启"- 查询字符串不能为空,BM25 只处理非空 query
- 只有 topK 个 BM25 结果会被合并——如果语义检索已把热门 chunk 占满,BM25 补充的空间有限
另外注意:BM25 开销与未被语义选中的 chunk 数量成正比,中小规模索引下可忽略(官方给出的典型延迟:数百条 < 1ms,数千条 1–2ms)。
总结:召回率提升清单 📋
- [ ] 查询含精确术语 / 短关键词 → 开启
isBm25: true - [ ] 用
renderSections的isBm25标记验证补充效果 - [ ] 仍不理想 → 调大
maxChunks - [ ] 检查切块参数
chunkSize/ overlap - [ ] 无结果 → 确认查询时传参、query 非空
延伸阅读:
- 混合检索完整说明:docs/documents.md
- RAG 实战教程:docs/tutorials/rag-pipeline.md
- 最佳实践与调优:docs/best-practices.md
- 可运行示例:samples/rag/
登录后查看全文