deja-vu 可选语义召回:本地嵌入与混合重排序的完整入门指南

原创2026-10-14 04:58:551,391 阅读

deja-vu 可选语义召回:本地嵌入与混合重排序的完整入门指南

deja-vu 宣传图:You are about to fix this twice,编码代理的本地记忆

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-vu 终端 TUI 搜索演示:跨 Claude Code、Codex、Cursor 检索全部会话历史

二、deja embed:向量侧车是怎么建出来的

2.1 端点解析:本地优先,自动探测

deja embed 没有参数,一切靠环境变量决定,解析逻辑在 internal/embed/client.go:

  1. DEJA_EMBED_URL 显式指定端点(OpenAI 兼容协议),DEJA_EMBED_MODEL 指定模型(默认 nomic-embed-text);
  2. 未指定时,自动探测 localhost:11434(Ollama)和 localhost:1234(LM Studio)——机器上已跑着本地运行时就直接接上,嵌入全程本地、无需任何 API key;
  3. 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 字符再发送。

deja-vu 演示 GIF:在终端中检索编码代理的会话记忆

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 的逻辑非常克制:

  1. 只处理结果页(最多 64 条),不碰全库,成本与结果页数成正比;
  2. 把词法分数做 min-max 归一化,记为 bm;
  3. 计算该会话最优向量与查询向量的余弦相似度 cos;
  4. 新分数 = 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 系统里"索引—向量—重排"三层结构最精简的样子。

登录后查看全文
deja-vu