deja-vu 可选语义召回:本地嵌入与混合重排序的完整入门指南
deja-vu 可选语义召回:本地嵌入与混合重排序的完整入门指南
deja-vu 是一款为 Claude Code、Codex、Cursor 等 40 多种编码代理(coding agents)提供记忆的开源工具:它读取代理已经写在你磁盘上的会话历史,构建本地索引,再通过 MCP 和 hooks 把这段"过去"还给代理。全文搜索、零依赖单 Go 二进制是它的基座,而**可选语义召回(semantic recall)**则是它最让人惊喜的进阶能力——用本地嵌入(embedding)向量解决"换了个说法就搜不到"的痛点。
本文将带你搞懂三件事:🔍 语义召回为什么是可选的、deja embed 如何构建本地向量、以及**混合重排序(hybrid rerank)**如何把词法分数与余弦相似度合二为一。
一、为什么需要"可选"的语义召回?
deja-vu 的默认搜索是纯词法的:倒排索引 + 停用词 + 词形折叠 + 拼写容错。快(中位数约 15ms),但纯词法检索天然怕" paraphrase(改写)"——你输入 ran out of db connections,历史会话里写的却是 connection pool exhausted,一个词都不共享,词法检索就失灵了。
语义召回补的正是这块短板:把每条记录编码成向量,用余弦相似度衡量语义距离。但注意——deja-vu 刻意把它设计为可选项:
- 没有配置嵌入端点时,词法搜索和 MCP 召回完全不变,零副作用;
- 不想把任何文本送出本机时,直接不启用即可(privacy 文档 对每次网络行为都有交代);
- 启用后,每次搜索只把"查询句"发给嵌入端点,历史正文不会外泄。
二、deja embed:向量侧车是怎么建出来的
2.1 端点解析:本地优先,自动探测
deja embed 没有参数,一切靠环境变量决定,解析逻辑在 internal/embed/client.go:
DEJA_EMBED_URL显式指定端点(OpenAI 兼容协议),DEJA_EMBED_MODEL指定模型(默认nomic-embed-text);- 未指定时,自动探测
localhost:11434(Ollama)和localhost:1234(LM Studio)——机器上已跑着本地运行时就直接接上,嵌入全程本地、无需任何 API key; DEJA_EMBED_OFF=1或DEJA_EMBED_URL=off可关闭探测。
对接 OpenAI 时会自动读取 OPENAI_API_KEY(仅限 https://api.openai.com),其他鉴权端点用 DEJA_EMBED_KEY 显式指定,密钥永远不会被隐式发给第三方。配置方式见 README 的 Semantic recall 章节。
2.2 侧车文件:.vectors.bin 而不是索引本体
向量不写进 index.db,而是作为旁挂的"侧车"文件 .vectors.bin 存放在索引旁边(internal/embed/sidecar.go)。这个设计有几个精妙之处:
- 按字节偏移寻址:每条向量只存它在
records.bin中的偏移量,索引本体保持无向量状态; - 增量嵌入:再次运行
deja embed时,只嵌入新增记录,旧向量被复用; - 断点续传:每 50 个批次落盘一次检查点(sidecar.go),中途被杀掉也不丢已嵌入的部分;
- 体积可控:float32 向量大约 4 MB / 千条消息(1024 维模型),且每条记录截断到约 2000 字符再发送。
2.3 过时效能:为什么索引一变,向量就"作废"
向量靠偏移量指向记录,而 deja forget 删掉一个会话后,后面所有偏移都会移动——旧向量会指向别的会话的记录。所以侧车里记有一个"generation 戳 + 文件尺寸"(Stale 判定):戳相同且文件只增不减才算同一布局;否则侧车整体判为 stale,语义搜索自动下线并打印一行提示"re-run deja embed",绝不会引用错乱。
2.4 出站闸门:信任策略决定什么能离开机器
嵌入是唯一会把会话文本放到第三方面前的操作,因此它取三条信任策略(search / MCP / sync)的交集(embedPolicyKeep):任何一条路径都不允许外发的记录,都留在本地不入向量,并打印提示。清单文件不可读时,闸门失败关闭——宁可不嵌入,也不放行。
三、混合重排序:0.5 × 词法 + 0.5 × 余弦
3.1 两次搜索的时机
看 cmd/deja/embed.go 与 main.go 的调度,每次查询实际走两条路径:
| 场景 | 走什么 | 效果 |
|---|---|---|
| 词法检索有命中 | maybeRerank:混合重排序 |
用向量相似度给已有结果重新排队 |
| 词法检索零命中 | maybeSemantic:独立语义层 |
直接对全库向量做近邻匹配兜底 |
也就是说,嵌入向量不只是"没搜到时的备胎",只要侧车存在,它一直在参与排序——这就是**混合(hybrid)**的含义。
3.2 重排序的公式
Rerank 的逻辑非常克制:
- 只处理结果页(最多 64 条),不碰全库,成本与结果页数成正比;
- 把词法分数做 min-max 归一化,记为
bm; - 计算该会话最优向量与查询向量的余弦相似度
cos; - 新分数 =
0.5 × bm + 0.5 × cos,按新分数稳定重排。
各占 50% 权重意味着:纯向量分再高,也压不过一个词法上强相关、只是表达不同的会话;反之,语义接近但词不沾边的结果也能被救回前排。
3.3 语义兜底层:0.55 的相似度地板
当词法完全无果时,SemanticSearch 对侧车全库计算余弦相似度,但设了一道 semanticFloor = 0.55 的地板——低于它的向量一律丢弃,避免把"不太相关的向量"硬说成搜索结果。结果按分数排序、每个会话只保留最高分的一条,最多返回 10 条,并打上 semantic 层级标签(带具体余弦值),CLI、JSON、MCP 输出里都能看到结果是怎么被找到的。
一个细腻的细节:被你 promote 成笔记的记录,哪怕分数低于地板,只要它的原始会话被命中,也会作为 held note 跟随一起出现(withHeldNotes)——蒸馏笔记的措辞往往和查询离得更远,硬地板会误伤。
3.4 每一层都留了后路
- 端点连不上 → 打印
semantic rerank unavailable; using lexical order,按词法原序返回; - 侧车损坏 / stale → 语义层下线,提示重跑
deja embed; --no-embed或DEJA_EMBED=off→ 本次搜索完全跳过嵌入路径。
召回不应因自己的账本而失败——这句源码注释(embed.go)就是这个模块的设计哲学。
四、上手三步与体检
# 1. 配置端点(本地 Ollama 可跳过,自动探测)
export DEJA_EMBED_URL='https://api.openai.com/v1/embeddings'
export DEJA_EMBED_MODEL='text-embedding-3-small'
# 2. 构建向量侧车(增量、可断点续传)
deja embed
# 3. 正常搜索,改写过的问法也能命中
deja "ran out of db connections" # 可匹配 "connection pool exhausted"
装好之后跑一次 deja doctor,它的 Embedding 区块会报告端点状态、模型名、向量维度和侧车覆盖率,语义召回是否"在正常工作"一目了然。搜索语法与层级标签的完整说明见官方文档 Search,项目整体架构可参考 docs/ARCHITECTURE.md。
五、小结:为什么这套设计值得借鉴
- 可选但不二等公民:语义层缺位时词法检索照常,就位时它既重排又兜底;
- 本地优先的嵌入:Ollama / LM Studio 自动探测,向量侧车
.vectors.bin与索引解耦、可增量更新; - 诚实的降级:stale、损坏、断网——每一种失败都有一句人话提示,而不是静默变差;
- 隐私闸门最严格:三条信任策略取交集 + 2k 字符截断 + 构建期脱敏,外发的永远是红线内的文本。
词法检索管"字面找得到",嵌入向量管"意思对得上",0.5×0.5 的混合公式让两者互相制衡。对新手来说,理解 deja-vu 的语义召回,也就理解了现代 RAG 系统里"索引—向量—重排"三层结构最精简的样子。


