Honcho混合搜索指南:BM25+向量检索如何让AI精准找到记忆
Honcho混合搜索指南:BM25+向量检索如何让AI精准找到记忆
你是否遇到过这样的场景:AI Agent 明明"记得"用户上周提到的项目代号,却在被追问时搜不到?这正是纯关键词搜索的软肋——Honcho 混合搜索(Hybrid Search) 通过 BM25 全文检索 + 向量语义检索双路召回,再经 RRF(Reciprocal Rank Fusion)融合排序,帮助有状态 AI Agent 精准找到所需记忆。
为什么单一搜索方式会"找不准记忆"?
给 AI 记忆建索引时,只有两条路走不通:
| 搜索方式 | 擅长 | 致命弱点 |
|---|---|---|
| 关键词匹配(BM25 类全文检索) | 精确词、人名、错误码 | "预算超支了"搜不到语义相近的"费用爆了" |
| 向量语义检索(Embedding) | 同义改写、模糊意图 | 专有名词、缩写、代码片段可能漏配 |
混合搜索的本质:让两种检索方式互为备份,谁找到的证据多,谁就排得更靠前。
深入原理:Honcho 混合搜索的三阶段流水线
Honcho 的混合搜索实现在 src/utils/search.py 中,核心流程分三步:
第 1 步:BM25 风格全文检索(即时可用)
消息写入数据库的瞬间,关键词匹配就已生效,无需等待任何后台任务。对于带特殊字符的查询走精确字符串匹配,自然语言查询则走全文检索并按相关性排序,同时用模糊匹配兜底,保证覆盖度(参见 _fulltext_search)。
第 2 步:向量语义检索(后台生成)
查询文本先经 Embedding 模型向量化,再在向量索引中按余弦距离找出语义最近的记忆。Honcho 的向量存储层是插件化设计(src/vector_store/),支持 pgvector、Turbopuffer、LanceDB、Qdrant 等后端,由 VECTOR_STORE.TYPE 配置项切换。
⏱️ 注意:语义结果依赖消息的 Embedding 向量,而向量是后台异步生成的。刚创建的消息可能在几秒后才出现在语义结果中;关键词结果则立即可查。
第 3 步:RRF 倒数排名融合(关键一步)
两路结果各自成榜后,Honcho 不直接拼接,而是用 RRF 算法融合(reciprocal_rank_fusion):
每条记忆的得分 = 它出现在的每一路榜单中
1 / (60 + 名次)之和
这个公式的巧妙之处在于:一条记忆若同时被关键词和语义两路命中且名次靠前,它的融合分将显著领先;只被单路命中的次之。无需对"词频分"和"余弦相似度"做归一化调参,天然公平。
3 步上手:让 Agent 精准召回记忆
1️⃣ 选择搜索范围(Scope)
Honcho 提供三级搜索范围,长尾场景按需选择:
- 工作区级:
honcho.search("budget planning")—— 全空间搜索 - 会话级:
session.search("action items")—— 只在某次对话内找 - 同级(Peer)级:
peer.search("programming")—— 只找某个用户/角色相关的内容
2️⃣ 用筛选器收窄结果
支持按时间范围、元数据、会话 ID 组合过滤,例如只在 1 月内、且元数据标记为 support 的消息中搜索,进一步提升召回精准度。
3️⃣ 控制返回数量
limit 参数默认返回 10 条、最多 100 条。建议生产环境设 20~50:给 LLM 上下文留足余量,又不挤爆 Token 预算。
官方文档中有完整参数说明与示例:docs/v3/documentation/features/advanced/search.mdx,筛选语法详见 docs/v3/documentation/features/advanced/using-filters.mdx。
4 个让命中率暴涨的实战技巧
- 专有名词 + 语义混合表达:查询写成
「Order-4022 发货失败」,数字/编号交给 BM25 锁定,语义部分交给向量,双路互补。 - 新消息别急着断言搜不到:语义索引有几秒延迟,集成测试中建议短暂轮询等待。
- 空结果时放宽查询:先去掉筛选条件、再缩短关键词,而不是直接判定"没这回事"。
- 配合上下文接口:搜索定位到关键消息后,用
session.context(...)拉取周边上下文喂给 LLM,比只喂搜索结果更连贯。
常见问题(FAQ)
Q1:为什么同一条记忆,换一种问法就搜不到了?
纯关键词检索受词汇限制,而混合搜索的语义一路能覆盖同义改写。若你的部署关闭了 EMBED_MESSAGES(默认为开启,见 src/config.py),搜索会退化为纯关键词模式,命中率自然下降。
Q2:RRF 中的 60 是什么? 是融合常数 k,用于平滑名次差异,让"第 1 名"与"第 10 名"的得分不至于悬殊过大,保证两路结果的平衡贡献。
Q3:混合搜索会增加多少延迟? 向量查询走的是预建 HNSW 索引,毫秒级完成;全文检索走 PostgreSQL 内置能力。融合排序为纯内存计算,整体开销很低。
小结
Honcho 混合搜索 = BM25 关键词即时命中 + 向量语义模糊召回 + RRF 公平融合。理解这条流水线后,你就能在构建有状态 Agent 时,从容应对"换一种说法也找得到、精确编号也搜得到"的记忆检索需求,让 AI 真正具备可靠、精准的长期记忆能力。



