From db6ab564dcd9fdef4307a90f18dc16d7e79ba860 Mon Sep 17 00:00:00 2001 From: xiaowei Date: Wed, 14 Oct 2026 13:02:37 +0800 Subject: [PATCH] =?UTF-8?q?feat(recall):=20t=5F2afae95e=20FTS=20=E8=AF=8D?= =?UTF-8?q?=E9=9D=A2=E6=A3=80=E7=B4=A2=E9=80=9A=E9=81=93=EF=BC=88TF-IDF=20?= =?UTF-8?q?=E5=80=92=E6=8E=92=EF=BC=8CGo=20=E5=86=85=E5=AD=98=E7=B4=A2?= =?UTF-8?q?=E5=BC=95=EF=BC=8Cenv-gate=20=E9=BB=98=E8=AE=A4=E5=85=B3?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 根因:金标 MMR 条目的关键词只在向量 rank #126/12094 的记忆里 ⇒ 调权重救不回来, embedding 主导的链路没有真正的词面检索通道(卡内 2026-10-14 实测定位 4 处)。 - 新 internal/storage/fts_index.go:TF-IDF 倒排(ASCII 词+CJK bigram,与 tokenizeQueryV2 同口径;IDF=log2(N/df+1),TF=1+log(tf))。数据源=ScanAll (Rust IPC lancedb_scan_all 只读);索引落 Go 内存,不建 LanceDB tantivy 索引文件/不碰 LanceDB 版本链(_versions 膨胀历史教训)。 - 生命周期:启动 3s 首建(同步)+ 6h 周期 + 写路径 FtsInvalidate 标脏后 异步重建(代际号防双重建互踩;30min 节流防 loader 缺失时疯狂起 goroutine)。 重建异步 ⇒ 在线召回 P95 不受建索引影响。 - recall.go Step 2.2:词面命中不进主候选池(无向量,混入会让 rerank 回退 文本重编码路径);Step 3.8 rerank+MMR **之后**尾部保证位追加(诊断第 3 条: 融合必须在 rerank 之后才算数;头部 topK-1 相对顺序不动 ⇒ AC4 零回归)。 - models.RecallResult 加 FtsBoosted(omitempty,展示侧可辨来源); QualityScore 保持 DB 原值(词面分只进排序不进展示分,对齐『响应值==库值』铁律)。 - server.go:FtsProvider 挂 ScanAll + 蒸馏落库后 FtsInvalidate + /api/v1/cache/stats 加 fts_index 段 + /api/v1/fts/rebuild 手工刷。 - 门控 ZHIYI_RECALL_FTS=1 或标志文件 /var/lib/memoryweave/recall-fts.on, 默认关 ⇒ 零行为变化;回滚 = 删标志文件/置 0,一条命令。 - 单测(双向验证):稀有词取回/TF-IDF 排序/门控关零变化/尾部去重/raw 剔除/ IDF 形状/空库边界。go test ./internal/storage ./internal/models 全绿。 --- go/internal/api/server.go | 22 ++ go/internal/models/memory.go | 12 +- go/internal/storage/fts_index.go | 358 ++++++++++++++++++++++++++ go/internal/storage/fts_index_test.go | 327 +++++++++++++++++++++++ go/internal/storage/recall.go | 105 +++++++- 5 files changed, 819 insertions(+), 5 deletions(-) create mode 100644 go/internal/storage/fts_index.go create mode 100644 go/internal/storage/fts_index_test.go diff --git a/go/internal/api/server.go b/go/internal/api/server.go index 8286dcc..87f3ae2 100644 --- a/go/internal/api/server.go +++ b/go/internal/api/server.go @@ -66,6 +66,18 @@ func NewServer() http.Handler { // 改为窗口内合并 + 单事务批量提交(每批 1 个版本)。 storage.InitRecallWriteBuffer(ldb) + // 2026-10-14 (t_2afae95e) FTS 词面通道:给 TF-IDF 索引挂全量数据源(ScanAll, + // 只读 IPC lancedb_scan_all;不建 LanceDB tantivy 索引文件 ⇒ 零写 LanceDB)。 + // 索引本体在 storage 包内后台建(启动 3s 首建 + 6h 周期 + 写路径标脏)。 + // 门控 ZHIYI_RECALL_FTS 默认关 ⇒ 接线了也不改召回行为(AC4 零变化)。 + if rc, ok := ldb.(*storage.RustLanceDBClient); ok { + storage.FtsProvider.FtsLdb = rc.ScanAll + log.Printf("[fts] 词面通道数据源已挂(ScanAll);门控 ZHIYI_RECALL_FTS=%s(默认关)", + os.Getenv("ZHIYI_RECALL_FTS")) + } else { + log.Printf("[fts] 后端非 RustLanceDBClient(%T)⇒ 词面通道数据源未挂(关态无影响)", ldb) + } + // 软删除累积延迟更新缓冲(2026-09-12 优化C) // 软删除操作不再逐条写 LanceDB(每写一行一个版本 → _versions 膨胀), // 改为窗口内合并 + 单事务批量提交(每批 1 个版本)。 @@ -338,6 +350,9 @@ func NewServer() http.Handler { storage.SearchCacheInstance.Invalidate(input.Namespace) log.Printf("[cache] 蒸馏落库后失效 namespace=%s(%d 条 facts,episode=%s)", input.Namespace, len(result.Facts), input.EpisodeID) + // 2026-10-14 (t_2afae95e):FTS 词面索引同步标脏(惰性重建, + // 下次词面查询时后台刷;关态下只是置一个 bool,零成本) + storage.FtsInvalidate() } // 冲突检测:加载已有记忆进行比较 // 必须用**新内容的真实向量**做语义检索取近邻;用零向量在语义索引上 @@ -473,8 +488,15 @@ func NewServer() http.Handler { if storage.SearchCacheInstance != nil { resp["search_cache"] = storage.SearchCacheInstance.Stats() } + // 2026-10-14 (t_2afae95e):FTS 词面索引状态(docs/tokens/built_at/dirty/门控) + resp["fts_index"] = storage.FtsIndexStats() respondJSON(w, 200, resp) }) + // 2026-10-14 (t_2afae95e):FTS 手工刷索引(admin;异步重建不阻塞) + mux.HandleFunc("/api/v1/fts/rebuild", func(w http.ResponseWriter, r *http.Request) { + storage.FtsRebuildNow() + respondJSON(w, 200, map[string]interface{}{"status": "rebuild_started"}) + }) // ─── Prometheus /metrics ───────────────────── mux.Handle("/metrics", metrics.Handler()) diff --git a/go/internal/models/memory.go b/go/internal/models/memory.go index f745be3..7531ce8 100644 --- a/go/internal/models/memory.go +++ b/go/internal/models/memory.go @@ -129,9 +129,9 @@ type MemoryRecord struct { type HitEvent struct { ID int64 `json:"id"` MemoryID string `json:"memory_id"` - Outcome string `json:"outcome"` // pos | neg(HitOutcome 枚举) - Reason string `json:"reason"` // HitReason 枚举:human_feedback|contradiction|replacement|downstream_use - Source string `json:"source,omitempty"` // 记录方标识(如端点名) + Outcome string `json:"outcome"` // pos | neg(HitOutcome 枚举) + Reason string `json:"reason"` // HitReason 枚举:human_feedback|contradiction|replacement|downstream_use + Source string `json:"source,omitempty"` // 记录方标识(如端点名) CreatedAt time.Time `json:"created_at"` } @@ -166,6 +166,12 @@ type RecallResult struct { Namespace string `json:"namespace,omitempty"` AgentID string `json:"agent_id,omitempty"` Source string `json:"source,omitempty"` + // 2026-10-14 (t_2afae95e FTS 词面通道):本条是否由词面检索通道补入 + // (rerank+MMR 之后尾部保证位)。true ⇒ 该内容命中了查询的词面特征 + // (稀有 ASCII 词/标识符/数字/中文二元组,TF-IDF 分 0..1 在 QualityScore 里), + // 但向量相似度不足以进主候选池。调用方可据此展示「词面命中」来源标注。 + // 门控关(ZHIYI_RECALL_FTS 默认)⇒ 恒 false 不输出(omitempty)。 + FtsBoosted bool `json:"fts_boosted,omitempty"` // 2026-10-08 (Gap#2):把信任等级直通给调用方。此前加列但不动本结构 ⇒ // confidence 对排序/调用方零影响(「字段加了没接线」的经典静默 no-op)。 // Confidence=nil 表示该条未声明(存量),调用方按 1.0 处理。 diff --git a/go/internal/storage/fts_index.go b/go/internal/storage/fts_index.go new file mode 100644 index 0000000..64e47a1 --- /dev/null +++ b/go/internal/storage/fts_index.go @@ -0,0 +1,358 @@ +// 织忆 MemoryWeave — 词面检索通道(TF-IDF,IDF 感知) +// +// t_2afae95e:金标条目「织忆如何通过 E1 提取和 MMR 实现多样去重」的 +// must_include 关键词 MMR 只在向量 rank #126/12094 的记忆里出现, +// per-ns top-50 候选池永远捞不到 ⇒ 靠调权重救不回来(卡内实测)。 +// 本通道给召回链路补一条**按内容检索**的路: +// +// - 索引:Go 侧内存 TF-IDF(ASCII 词 + CJK bigram,token 口径与 +// tokenizeQueryV2 一致——V2 实测验证过),全量来自 LanceDB ScanAll +// (Rust IPC lancedb_scan_all,只读;不建 LanceDB tantivy 索引文件, +// 不碰 LanceDB 版本链 —— _versions 17.7G 膨胀的历史教训 ⇒ 索引落内存)。 +// - 建索引:启动 3s 后首建 + 6h 后台周期 + 写路径 Invalidate 标脏后 +// 下次查询惰性重建。全程离线,不阻塞在线召回(召回路径零建索引成本, +// 只有脏/过期时才花一次 ScanAll 的几百 ms,且后台做)。 +// - 查询:命中词 IDF 加权(log2(N/df+1),BM25 同款形态)⇒ 稀有词主导; +// TF 用 1+log(tf) 平滑。这就是「等价的 IDF 感知词面检索」。 +// - 融合:检索命中并入候选池 + rerank **之后**按尾部保证位补入(诊断第 3 条: +// 融合在 rerank 之前会被 cosine 重排整段覆盖 ⇒ 放 MMR 之后、按 top-k 尾部 +// 追加保证「词面命中的稀有条目」不被挤掉;头部排序仍归 rerank+MMR 管, +// 不动主路径相对顺序 ⇒ AC4 零回归)。 +// +// 门控(默认关,回滚一条命令): +// - env ZHIYI_RECALL_FTS=1 或 标志文件 /var/lib/memoryweave/recall-fts.on +// - 关闭 ⇒ recallUncached 的 FTS 分支整块跳过 ⇒ 行为零变化(AC4/AC6) +// +// 注:本索引是 TF-IDF **数据结构**(倒排+文档表),不是结果缓存—— +// 项目现有 5 个缓存件(SearchCache L1/L2、RedisCache、CachedGraphStore、memCache) +// 管的是「查询结果复用」,本件管的是「内容倒排」,职责不同,不替代任何一个。 +// 生命周期靠 Invalidate/后台周期/惰性重建保鲜,不写任何新缓存键。 + +package storage + +import ( + "fmt" + "log" + "math" + "os" + "strings" + "sync" + "time" + + "github.com/xiaoxue/memoryweave/internal/models" +) + +// FtsProvider 词面通道数据源注入点(生产在 server 启动时挂 ScanAll;测试注入固定行)。 +// 写路径经 FtsInvalidate 标脏(同时失效搜索缓存的既有钩子处一起调)。 +var FtsProvider struct { + mu sync.RWMutex + FtsLdb func() ([]models.MemoryRecord, error) // 全量只读扫描 +} + +type ftsIndex struct { + mu sync.RWMutex + records map[string]models.MemoryRecord // id → 记录(Vector 置空瘦身) + postings map[string][]string // token → doc id(df = len) + docTokens map[string]map[string]int // doc id → token → tf + idf map[string]float64 // token → log2(N/df+1) + nDocs int + builtAt time.Time + lastAttempt time.Time // 最近一次重建触发尝试(节流 30min) + dirty bool // 写路径标脏;查询时异步重建 + rebuilding bool // 异步重建进行中(防惊群) + gen int // 代际号:重建提交时推进;旧扫描发现代际被推进 ⇒ 让位 + buildErr error +} + +var ftsInstance = &ftsIndex{} + +// ftsEnabled 门控(与 recallV2 同款 env + 标志文件,A/B 可不重启切)。 +func ftsEnabled() bool { + if os.Getenv("ZHIYI_RECALL_FTS") == "1" { + return true + } + flag := os.Getenv("ZHIYI_RECALL_FTS_FLAG") + if flag == "" { + flag = "/var/lib/memoryweave/recall-fts.on" + } + _, err := os.Stat(flag) + return err == nil +} + +// ftsIndexMaxAge:索引最长保鲜期(写路径 Invalidate 会提前标脏,这是兜底)。 +const ftsIndexMaxAge = 6 * time.Hour + +// ftsTokenize 文档侧分词:ASCII 小写词(≥2 字符,含标识符/缩写/数字)+ CJK bigram。 +// 与 tokenizeQueryV2 的查询侧口径一致(那边也 ToLower),保证查询词能在倒排里查到。 +func ftsTokenize(doc string) map[string]int { + tf := map[string]int{} + runes := []rune(strings.ToLower(doc)) + var cur []rune + flush := func() { + if len(cur) >= 2 { + tf[string(cur)]++ + } + cur = cur[:0] + } + for i := 0; i < len(runes); i++ { + r := runes[i] + if (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == '_' || r == '-' || r == '.' { + cur = append(cur, r) + continue + } + flush() + if r >= 0x4E00 && r <= 0x9FFF && i+1 < len(runes) { + nx := runes[i+1] + if nx >= 0x4E00 && nx <= 0x9FFF { + tf[string([]rune{r, nx})]++ + } + } + } + flush() + return tf +} + +// rebuild 全量重建(只读扫描,不碰 LanceDB 版本链)。 +// 代际保护:重建前先取 loader 引用 + 代际号,提交时校验代际未变 —— +// 并发重建(init 后台 + ensureFresh 异步 + FtsRebuildNow)只会让**最后一次** +// 提交生效,旧重建不会覆盖新数据(双重建竞态:B 扫得慢但 A 先提交时, +// B 的 gen 已被 A 推进 ⇒ B 丢弃自己的结果,A 是较新的数据源状态)。 +func (idx *ftsIndex) rebuild() { + idx.mu.RLock() + loader := FtsProvider.FtsLdb + idx.mu.RUnlock() + if loader == nil { + // 未注入(后端非 RustLanceDBClient):置脏避免每次查询都重试触发, + // 记 buildErr 可观测;6h 后台周期会再试(注入恢复后自动起效)。 + idx.mu.Lock() + idx.buildErr = fmt.Errorf("fts: FtsProvider.FtsLdb 未注入") + idx.dirty = false + idx.mu.Unlock() + return + } + // 扫数据前先占代际号:若别人在我们扫的过程中完成了重建,我们提交时让位 + idx.mu.Lock() + gen := idx.gen + idx.mu.Unlock() + + records, err := loader() + if err != nil { + // 失败保留旧索引继续服务(stale 但有效);清 dirty 避免每次查询都重试触发 + idx.mu.Lock() + idx.rebuilding = false + idx.dirty = false + idx.buildErr = err + idx.mu.Unlock() + log.Printf("[fts] 词面索引重建失败(保留旧索引继续服务): %v", err) + return + } + + lean := make(map[string]models.MemoryRecord, len(records)) + docTokens := make(map[string]map[string]int, len(records)) + postings := make(map[string][]string) + for i := range records { + rec := records[i] + if rec.IsDeleted || rec.ID == "" || rec.Content == "" { + continue + } + tf := ftsTokenize(rec.Content) + if len(tf) == 0 { + continue + } + docTokens[rec.ID] = tf + rec.Vector = nil // 融合通道只需内容/元数据;向量由向量通道提供(4KB/条 × 2.6 万不常驻) + lean[rec.ID] = rec + for tok := range tf { + postings[tok] = append(postings[tok], rec.ID) + } + } + n := len(lean) + idf := make(map[string]float64, len(postings)) + for tok, docIDs := range postings { + idf[tok] = math.Log2(float64(n)/float64(len(docIDs)) + 1.0) + } + + idx.mu.Lock() + // 代际校验:扫描期间若别人推进了 gen(更晚的提交)⇒ 我们这份是旧的,让位不覆盖 + if idx.gen != gen { + idx.rebuilding = false + idx.mu.Unlock() + log.Printf("[fts] 词面索引重建让位:扫描期间已有更新代际提交(gen %d → %d)", gen, idx.gen) + return + } + idx.rebuilding = false + idx.gen = gen + 1 + idx.records = lean + idx.docTokens = docTokens + idx.postings = postings + idx.idf = idf + idx.nDocs = n + idx.builtAt = time.Now() + idx.dirty = false + idx.buildErr = nil + idx.mu.Unlock() + log.Printf("[fts] 词面索引重建完成:docs=%d tokens=%d(源 %d 行,剔空/删/无 token)", n, len(postings), len(records)) +} + +// ensureFresh 脏或超龄 ⇒ 触发**异步**重建(保在线召回 P95:重建含一次 +// ScanAll ≈ 数百 ms~秒级,绝不进查询路径同步跑)。查询期间沿用旧索引 +// (stale 但有效),重建完成后下次查询即新索引。 +// 并发/节流保护:rebuilding 标志防惊群;lastAttempt 节流 30min —— +// loader 未注入 / 重建失败时每次查询都 stale,不设节流会疯狂起 goroutine。 +// 首建例外:builtAt=零(从未建成过索引)⇒ **同步**重建一次(首次开销可接受, +// 保证首条查询不拿空索引);建成后所有后续重建都走异步。 +func (idx *ftsIndex) ensureFresh() { + idx.mu.Lock() + neverBuilt := idx.builtAt.IsZero() + stale := neverBuilt || idx.dirty || time.Since(idx.builtAt) > ftsIndexMaxAge + alreadyRunning := idx.rebuilding + throttled := !idx.lastAttempt.IsZero() && time.Since(idx.lastAttempt) < 30*time.Minute + idx.lastAttempt = time.Now() + idx.mu.Unlock() + if !stale { + return + } + if neverBuilt { + idx.rebuild() // 首建同步(测试与冷启动路径) + return + } + if alreadyRunning || throttled { + return + } + go func() { + idx.mu.Lock() + idx.rebuilding = true + idx.mu.Unlock() + idx.rebuild() + }() +} + +// FtsSearch 词面检索通道:query → doc id → 归一化 TF-IDF 分(0..1)。 +// 分母 = 查询词命中库的 IDF 之和(库没有的词不计分母,避免无谓稀释)。 +func (idx *ftsIndex) FtsSearch(query string, topN int) map[string]float64 { + idx.ensureFresh() + ascii, bigrams := tokenizeQueryV2(query) + if len(ascii) == 0 && len(bigrams) == 0 { + return nil + } + idx.mu.RLock() + defer idx.mu.RUnlock() + if idx.nDocs == 0 { + return nil + } + scores := map[string]float64{} + total := 0.0 + addTerm := func(tok string) { + idf, ok := idx.idf[tok] + if !ok { + return + } + total += idf + for _, docID := range idx.postings[tok] { + tfv := float64(idx.docTokens[docID][tok]) + scores[docID] += idf * (1 + math.Log(tfv+1)) + } + } + for _, a := range ascii { + addTerm(a) + } + for _, b := range bigrams { + addTerm(b) + } + if total == 0 { + return nil // 查询词全不在库 ⇒ 零结果(调用方保持原行为) + } + // 全词命中且 tf=1 上界 = total*2.0;取 1.5 系数让满分文档略超 1 后钳制 + out := make(map[string]float64, len(scores)) + for id, s := range scores { + v := s / (total * 1.5) + if v > 1.0 { + v = 1.0 + } + out[id] = v + } + if topN <= 0 || len(out) <= topN { + return out + } + type kv struct { + k string + v float64 + } + ks := make([]kv, 0, len(out)) + for k, v := range out { + ks = append(ks, kv{k, v}) + } + for i := 0; i < topN; i++ { + best := i + for j := i + 1; j < len(ks); j++ { + if ks[j].v > ks[best].v { + best = j + } + } + ks[i], ks[best] = ks[best], ks[i] + } + top := make(map[string]float64, topN) + for i := 0; i < topN; i++ { + top[ks[i].k] = ks[i].v + } + return top +} + +// FtsRecord 取索引里的记录(供候选池合并用;索引未建/无 ⇒ ok=false 走原路径)。 +func FtsRecord(id string) (models.MemoryRecord, bool) { + ftsInstance.mu.RLock() + defer ftsInstance.mu.RUnlock() + rec, ok := ftsInstance.records[id] + return rec, ok +} + +// FtsInvalidate 写路径钩子:commit 落库后调(在 server 的 SearchCache Invalidate 同处), +// 标脏让下次查询惰性重建。关不关都零成本(一次原子写)。 +func FtsInvalidate() { + ftsInstance.mu.Lock() + ftsInstance.dirty = true + ftsInstance.mu.Unlock() +} + +// FtsRebuildNow 手工触发(admin 端点;异步重建不阻塞调用方)。 +func FtsRebuildNow() { + go ftsInstance.rebuild() +} + +// FtsIndexStats 观测端点(/api/v1/fts/stats):索引状态可核。 +func FtsIndexStats() map[string]interface{} { + ftsInstance.mu.RLock() + providerWired := false + ftsInstance.mu.RUnlock() + FtsProvider.mu.RLock() + providerWired = FtsProvider.FtsLdb != nil + FtsProvider.mu.RUnlock() + return map[string]interface{}{ + "enabled": ftsEnabled(), + "docs": ftsInstance.nDocs, + "tokens": len(ftsInstance.postings), + "built_at": ftsInstance.builtAt.Format(time.RFC3339), + "dirty": ftsInstance.dirty, + "build_error": ftsInstance.buildErr, + "provider_wired": providerWired, + "max_age_hours": int(ftsIndexMaxAge.Hours()), + "gate_env": "ZHIYI_RECALL_FTS=1", + "gate_flag_file": "/var/lib/memoryweave/recall-fts.on", + } +} + +func init() { + // 启动 3s 后首建(sidecar 就绪窗口;provider 未注入则跳过,靠后台周期兜底) + go func() { + time.Sleep(3 * time.Second) + ftsInstance.ensureFresh() + }() + // 6h 后台兜底重建(防只读环境写路径不触发 Invalidate) + go func() { + tick := time.NewTicker(ftsIndexMaxAge) + defer tick.Stop() + for range tick.C { + ftsInstance.rebuild() + } + }() +} diff --git a/go/internal/storage/fts_index_test.go b/go/internal/storage/fts_index_test.go new file mode 100644 index 0000000..d5ce9ca --- /dev/null +++ b/go/internal/storage/fts_index_test.go @@ -0,0 +1,327 @@ +package storage + +import ( + "fmt" + "math" + "sort" + "testing" + "time" + + "github.com/xiaoxue/memoryweave/internal/models" +) + +// resetFTSIndex 清索引数据字段但**不动 mutex**。 +// 注意:不能写 `*ftsInstance = ftsIndex{}` —— 持锁期间把整个 struct(含 mu) +// 清零 ⇒ 解锁时对未持有的 RWMutex 调 Unlock ⇒ sync fatal(实测踩过)。 +func resetFTSIndex() { + ftsInstance.mu.Lock() + ftsInstance.records = nil + ftsInstance.postings = nil + ftsInstance.docTokens = nil + ftsInstance.idf = nil + ftsInstance.nDocs = 0 + ftsInstance.builtAt = time.Time{} + ftsInstance.lastAttempt = time.Time{} + ftsInstance.dirty = false + ftsInstance.rebuilding = false + ftsInstance.gen = 0 + ftsInstance.buildErr = nil + ftsInstance.mu.Unlock() +} + +// waitForFTSIndex 轮询等到索引非空(init 的后台 3s 首建可能还没跑完)。 +// 测试里 resetFTSIndex 把 builtAt 清零后,下一次 FtsSearch 会同步首建; +// 但若 init goroutine 正在重建,需等它让出锁。给 2s 上限防死等。 +func waitForFTSIndex(t *testing.T, wantDocs int) { + t.Helper() + deadline := time.Now().Add(2 * time.Second) + for time.Now().Before(deadline) { + ftsInstance.mu.RLock() + n := ftsInstance.nDocs + ftsInstance.mu.RUnlock() + if n >= wantDocs { + return + } + time.Sleep(20 * time.Millisecond) + } + t.Fatalf("等待 FTS 索引 %d docs 超时(实际 %d)", wantDocs, ftsInstance.nDocs) +} + +// ─── t_2afae95e FTS 词面通道(TF-IDF 索引 + 召回尾部保证位)单测 ─── +// 双向验证口径(AC1 判据): +// - 修前:向量 top-N 池外、含稀有 ASCII 词(MMR)的文档捞不回来 +// (ftsTail 机制不存在 ⇒ golden query 结果里无该 id) +// - 修后:FTS 通道命中该 id 且按 TF-IDF 分进入结果(尾部保证位) +// 全部测试只跑纯内存 fake 数据源,不触网、不碰 LanceDB。 + +// ftsTestLance 固定数据源(ScanAll 语义:全量记录) +func ftsTestRows() []models.MemoryRecord { + return []models.MemoryRecord{ + {ID: "mmr_doc", Namespace: "hermes-main", Category: "distilled", + Content: "recall.go MMR 前插入门控接线。"}, + {ID: "generic_doc", Namespace: "hermes-main", Category: "distilled", + Content: "织忆(MemoryWeave)是一个系统。"}, + {ID: "zhiyi_doc", Namespace: "hermes-main", Category: "distilled", + Content: "织忆的图谱扩展机制是 1 跳 ExpandFromResults。"}, + {ID: "zhiyi2_doc", Namespace: "hermes-main", Category: "distilled", + Content: "织忆记忆系统每日 03:00 自动蒸馏。"}, + {ID: "llama_doc", Namespace: "shared", Category: "distilled", + Content: "本地 llama 服务 8080 端口,OpenAI 兼容,key 任意"}, + {ID: "session_doc", Namespace: "hermes-main", Category: "distilled", + Content: "过滤器在 session-to-zhiyi.py 消息读取层被调用。"}, + {ID: "raw_doc", Namespace: "hermes-main", Category: "episodes", + Content: "原始对话里也提到 MMR 去重。"}, + {ID: "deleted_doc", Namespace: "hermes-main", Category: "distilled", IsDeleted: true, + Content: "已删除的记忆也提到 MMR。"}, + } +} + +func newFTSPipeline(t *testing.T) *RecallPipeline { + t.Helper() + saved := SearchCacheInstance + SearchCacheInstance = nil + t.Cleanup(func() { SearchCacheInstance = saved }) + + savedVVP := VValueProvider + t.Cleanup(func() { VValueProvider = savedVVP }) + + savedFTS := FtsProvider.FtsLdb + FtsProvider.FtsLdb = func() ([]models.MemoryRecord, error) { return ftsTestRows(), nil } + t.Cleanup(func() { FtsProvider.FtsLdb = savedFTS }) + + // 干净起步:清索引(防止其他测试的脏索引串味) + resetFTSIndex() + + vec := make([]float32, 8) + for i := range vec { + vec[i] = 0.5 + } + emb := &Embedder{endpoint: "http://127.0.0.1:1/never", dim: 8} + emb.cache.Store("fts 测试查询 MMR 去重", vec) + emb.cache.Store("fts 8080 端口", vec) + p := NewRecallPipeline(emb, &ftsSearchOnly{dim: 8}, &Reranker{}) + return p +} + +// ftsSearchOnly:向量搜索恒返回空(模拟「目标文档在向量 top-N 池外」), +// 且对 Update 空实现 —— 这样通道有没有接通完全由 FTS 侧证明。 +type ftsSearchOnly struct { + LanceDB + dim int +} + +func (f *ftsSearchOnly) Search(table string, vector []float32, topK int, namespaceFilter string) ([]models.MemoryRecord, error) { + return nil, nil +} +func (f *ftsSearchOnly) Update(table, id string, fields map[string]any) error { return nil } + +// AC1(索引层):稀有 ASCII 词 MMR 能按内容检索取回 mmr_doc, +// 且 TF-IDF 排序把它压在泛泛文档之上;raw/deleted 被剔除。 +func TestFTSIndex_RareASCIITerm(t *testing.T) { + _ = newFTSPipeline(t) + ftsInstance.rebuild() + + got := ftsInstance.FtsSearch("织忆如何通过 E1 提取和 MMR 实现多样去重", 10) + if len(got) == 0 { + t.Fatalf("FTS 通道零命中 ⇒ 索引没接通(docs=%d)", ftsInstance.nDocs) + } + mmr, ok := got["mmr_doc"] + if !ok { + t.Fatalf("含 MMR 的 mmr_doc 未被词面通道取回(判据 AC1 失败);命中集=%v", idsOf(got)) + } + if gen, ok2 := got["generic_doc"]; ok2 && mmr <= gen { + t.Fatalf("TF-IDF 未把稀有词文档顶在泛泛文档之上: mmr=%.4f generic=%.4f", mmr, gen) + } + // 索引层口径:raw/deleted 的剔除分两层 —— 索引只剔 is_deleted(内容全收, + // 建索引=纯数据搬运),原始对话类别在召回 Step 2.2 合并时剔(同 Step 2.5 口径)。 + // 因此这里只断言 deleted 不入库;raw 断言移到召回层测试。 + if _, ok := got["deleted_doc"]; ok { + t.Fatalf("is_deleted 记录进了词面索引 ⇒ 建索引没剔软删行") + } + t.Logf("AC1 OK: MMR=%.4f generic=%.4f(docs=%d tokens=%d)", + mmr, got["generic_doc"], ftsInstance.nDocs, len(ftsInstance.postings)) +} + +// AC1 同源判据:8080 / session-to-zhiyi 两个稀有词同样可取回(AC3 的索引层前置)。 +func TestFTSIndex_OtherRareTerms(t *testing.T) { + _ = newFTSPipeline(t) + ftsInstance.rebuild() + got8080 := ftsInstance.FtsSearch("本地 llama 服务 8080 端口", 10) + if _, ok := got8080["llama_doc"]; !ok { + t.Fatalf("8080 数字词未取回 llama_doc;命中=%v", idsOf(got8080)) + } + gotSess := ftsInstance.FtsSearch("session-to-zhiyi.py 脚本名", 10) + if _, ok := gotSess["session_doc"]; !ok { + t.Fatalf("session-to-zhiyi 标识符未取回 session_doc;命中=%v", idsOf(gotSess)) + } +} + +// AC4(门控关 = 零行为变化):ZHIYI_RECALL_FTS 未设时整条通道不参与, +// 固定 query 的召回结果 id 序列与无通道时完全一致。 +func TestFTS_RecallGateOff(t *testing.T) { + t.Setenv("ZHIYI_RECALL_FTS", "") + t.Setenv("ZHIYI_RECALL_FTS_FLAG", "/nonexistent-fts-flag") + p := newFTSPipeline(t) + + res, err := p.Recall("fts 8080 端口", "hermes-main", 5, 0.5) + if err != nil { + t.Fatalf("recall 报错(门控关时不应有通道参与): %v", err) + } + for _, r := range res { + if r.FtsBoosted { + t.Fatalf("门控关时出现了 fts_boosted 结果 ⇒ AC4 零行为变化被破坏: %v", r.ID) + } + } +} + +// AC2/AC3(通道开 = 稀有词文档进最终结果):门控开时 +// 「池外」目标经尾部保证位进入结果,且头部相对顺序由主路径管。 +func TestFTS_RecallGateOnTailMerge(t *testing.T) { + t.Setenv("ZHIYI_RECALL_FTS", "1") + p := newFTSPipeline(t) + + // 向量池给 1 条(generic),MMR 目标是池外 ⇒ 必须靠 FTS 尾部位补进来 + res, err := p.Recall("fts 测试查询 MMR 去重", "hermes-main", 5, 0.5) + if err != nil { + t.Fatalf("recall 报错: %v", err) + } + ids := idsRes(res) + pos := map[string]int{} + for i, id := range ids { + pos[id] = i + } + if _, ok := pos["mmr_doc"]; !ok { + t.Fatalf("门控开但 mmr_doc 未进结果 ⇒ 尾部保证位没接通;结果=%v", ids) + } + boosted := 0 + for _, r := range res { + if r.FtsBoosted { + boosted++ + } + if r.Category == "episodes" { + t.Fatalf("原始对话(category=episodes)经词面通道进了结果 ⇒ Step 2.2 合并没剔 raw 类别: %v", r.ID) + } + } + if boosted == 0 { + t.Fatalf("结果里没有 fts_boosted 标记条目 ⇒ 无法审计来源") + } + t.Logf("门控开:结果=%v boosted=%d", ids, boosted) +} + +// 数字词同型验证(AC3 的召回层):8080 经通道进结果。 +func TestFTS_RecallDigitTerm(t *testing.T) { + t.Setenv("ZHIYI_RECALL_FTS", "1") + p := newFTSPipeline(t) + res, err := p.Recall("fts 8080 端口", "hermes-main", 5, 0.5) + if err != nil { + t.Fatalf("recall 报错: %v", err) + } + found := false + for _, r := range res { + if r.ID == "llama_doc" { + found = r.FtsBoosted // 应在尾部位(向量池恒空) + } + } + if !found { + t.Fatalf("llama_doc(8080)未由词面通道进入结果;结果=%v", idsRes(res)) + } +} + +// 去重:向量池与 FTS 池都有的 id 不重复出现。 +func TestFTS_RecallNoDup(t *testing.T) { + t.Setenv("ZHIYI_RECALL_FTS", "1") + t.Setenv("ZHIYI_RECALL_FTS_FLAG", "/nonexistent") + saved := SearchCacheInstance + SearchCacheInstance = nil + t.Cleanup(func() { SearchCacheInstance = saved }) + + vec := make([]float32, 8) + for i := range vec { + vec[i] = 0.5 + } + emb := &Embedder{endpoint: "http://127.0.0.1:1/never", dim: 8} + emb.cache.Store("fts 测试查询 MMR 去重", vec) + // 直接构造:向量池 fake 返回两条(含 MMR 文档)⇒ 与 FTS 尾部位重叠,验证去重 + savedFts := FtsProvider.FtsLdb + FtsProvider.FtsLdb = func() ([]models.MemoryRecord, error) { return ftsTestRows(), nil } + t.Cleanup(func() { FtsProvider.FtsLdb = savedFts }) + resetFTSIndex() + both := &ftsLanceBoth{dim: 8} + p := NewRecallPipeline(emb, both, &Reranker{}) + res, _ := p.Recall("fts 测试查询 MMR 去重", "hermes-main", 5, 0.5) + seen := map[string]int{} + for _, r := range res { + seen[r.ID]++ + } + for id, n := range seen { + if n > 1 { + t.Fatalf("id %s 出现 %d 次 ⇒ 尾部位没做去重", id, n) + } + } +} + +// ftsLanceBoth:向量池也返回 MMR 文档(去重判据) +type ftsLanceBoth struct { + LanceDB + dim int +} + +func (f *ftsLanceBoth) Search(table string, vector []float32, topK int, namespaceFilter string) ([]models.MemoryRecord, error) { + vec := make([]float32, 8) + for i := range vec { + vec[i] = 0.5 + } + return []models.MemoryRecord{ + {ID: "generic_doc", Namespace: "hermes-main", Category: "distilled", Content: "织忆(MemoryWeave)是一个系统。", Vector: vec}, + {ID: "mmr_doc", Namespace: "hermes-main", Category: "distilled", Content: "recall.go MMR 前插入门控接线。", Vector: vec}, + }, nil +} +func (f *ftsLanceBoth) Update(table, id string, fields map[string]any) error { return nil } + +// 索引层单测:IDF 形状 —— 全库词(df=N)idf 低,独占词 idf 高。 +func TestFTS_IDFShape(t *testing.T) { + _ = newFTSPipeline(t) + ftsInstance.rebuild() + ftsInstance.mu.RLock() + defer ftsInstance.mu.RUnlock() + // "系统" 只在 generic_doc 出现;"织忆" 也在 generic_doc(同 1 条) + // 构造:mmr 类独占词 vs 泛词 + idfMmr := ftsInstance.idf["mmr"] + if idfMmr <= 0.5 { + t.Fatalf("独占词 MMR 的 IDF 应显著高于 0.5(log2(N/1+1)),实测 %.3f(N=%d)", idfMmr, ftsInstance.nDocs) + } + t.Logf("idf[mmr]=%.3f N=%d", idfMmr, ftsInstance.nDocs) +} + +// FtsSearch 空库 / 全 miss 边界 +func TestFTS_EmptyAndAllMiss(t *testing.T) { + _ = newFTSPipeline(t) + resetFTSIndex() + if got := ftsInstance.FtsSearch("任何词", 5); len(got) != 0 { + t.Fatalf("空索引应返回 0 命中,实际 %d", len(got)) + } + ftsInstance.rebuild() + // 库里没有这个词 + if got := ftsInstance.FtsSearch("quantumflux", 5); len(got) != 0 { + t.Fatalf("全 miss 查询应 0 命中,实际 %d", len(got)) + } + _ = math.Log + _ = fmt.Sprint + _ = sort.Slice +} + +func idsOf(m map[string]float64) []string { + out := make([]string, 0, len(m)) + for k := range m { + out = append(out, k) + } + sort.Strings(out) + return out +} +func idsRes(res []models.RecallResult) []string { + out := make([]string, 0, len(res)) + for _, r := range res { + out = append(out, r.ID) + } + return out +} diff --git a/go/internal/storage/recall.go b/go/internal/storage/recall.go index 5f00426..a1832e8 100644 --- a/go/internal/storage/recall.go +++ b/go/internal/storage/recall.go @@ -7,6 +7,7 @@ import ( "log" "math" "os" + "sort" "strconv" "strings" "sync/atomic" @@ -340,6 +341,51 @@ func (p *RecallPipeline) recallUncached(query, namespace string, topK int, diver } candidates = unique + // Step 2.2 (t_2afae95e FTS 词面通道, env-gate ZHIYI_RECALL_FTS 默认关): + // 词面检索命中单独留位 —— 稀有 ASCII 词/标识符/数字(MMR、8080、 + // session-to-zhiyi 这类)在 embedding 主导的向量 top-N 里进不了池 + // (实测相关记忆向量排 #126/12094),这里按内容检索(TF-IDF 倒排) + // 把它们捞回来。 + // 为什么不并入主候选池:主池候选带 1024 维向量喂 RerankWithVectors, + // FTS 命中记录只有内容(Vector 置空)⇒ 混入会让整段 rerank 回退 + // 文本重编码路径(2000 字 3.9s)⇒ 融合改走「rerank+MMR 之后按分尾部 + // 追加」(诊断第 3 条:融合必须在 rerank 之后才算数;尾部追加不挤头部 + // 相对顺序 ⇒ AC4 主路径零回归)。 + // 门控关 ⇒ 本块不执行(零行为变化)。 + var ftsTail []models.MemoryRecord + ftsScoreOf := map[string]float64{} // id → 词面分(只用于尾部排序) + if ftsEnabled() { + ftsScores := ftsInstance.FtsSearch(query, 30) + for id, s := range ftsScores { + if seen[id] { + continue // 向量池已有 ⇒ 头部排序归主路径,不重复 + } + rec, ok := FtsRecord(id) + if !ok { + continue + } + switch rec.Category { + case "episodes", "对话", "对话记录", "raw", "episodic": + continue // 与 Step 2.5 同口径:原始对话不进结果 + } + if namespace != "" && rec.Namespace != namespace && rec.Namespace != "shared" { + continue // 带 ns 时 §1.3 作用域同口径(本 ns + shared) + } + ftsScoreOf[rec.ID] = s // 词面分只进排序;展示分保持 DB 原值(rec.QualityScore 不动) + ftsTail = append(ftsTail, rec) + } + // 词面分降序(同分按 id 稳定) + sort.SliceStable(ftsTail, func(i, j int) bool { + if ftsScoreOf[ftsTail[i].ID] != ftsScoreOf[ftsTail[j].ID] { + return ftsScoreOf[ftsTail[i].ID] > ftsScoreOf[ftsTail[j].ID] + } + return ftsTail[i].ID < ftsTail[j].ID + }) + if len(ftsTail) > 0 { + log.Printf("[recall] FTS 词面通道命中 %d 条(候选池 %d)", len(ftsTail), len(candidates)) + } + } + // Step 2.5: 过滤原始对话内容(category=episodes/对话/对话记录) // 原因:原始对话未蒸馏,不应出现在 recall 结果中 // 蒸馏产物通过 OnDistillComplete callback 写入 memories(category=distilled) @@ -446,12 +492,15 @@ func (p *RecallPipeline) recallUncached(query, namespace string, topK int, diver } } - if len(candidates) == 0 { + if len(candidates) == 0 && len(ftsTail) == 0 { // 自动记录召回缺口(gap_scan 触发器会在 30min 冷却后分类) + // t_2afae95e:FTS 尾部位命中也算有结果 ⇒ 不记 miss、不走空返回 if p.recordMiss != nil { p.recordMiss(query, namespace) } - return []models.RecallResult{}, RecallMeta{CandidatesScanned: poolSize}, nil + if len(ftsTail) == 0 { + return []models.RecallResult{}, RecallMeta{CandidatesScanned: poolSize}, nil + } } // Step 3: Rerank to top_k (graceful fallback) @@ -628,6 +677,58 @@ func (p *RecallPipeline) recallUncached(query, namespace string, topK int, diver } } + // Step 3.8 (t_2afae95e FTS 词面通道尾部保证位, 门控同 Step 2.2): + // 词面命中在 **rerank+MMR 之后**才并入最终结果(诊断第 3 条:rerank 之前 + // 融合会被 cosine 重排整段覆盖)。规则(只动尾部、不挤头部相对顺序): + // - 结果不足 topK ⇒ 追加到 topK 封顶; + // - 结果已满 topK ⇒ 顶掉最后一位(尾部 1 位让给 FTS 最高分命中, + // 头部 topK-1 条逐条不变 ⇒ AC4 关态零变化 / 开态回归面收敛在 1 个槽位)。 + // 去重:已在结果里的 ID 不重复追加(向量池已捞到的由主路径排序管)。 + // 门控关 ⇒ ftsTail 恒 nil ⇒ 整块零行为变化。 + if len(ftsTail) > 0 { + inResult := map[string]bool{} + for _, r := range results { + inResult[r.ID] = true + } + fresh := ftsTail[:0] + for _, rec := range ftsTail { + if !inResult[rec.ID] { + fresh = append(fresh, rec) + } + } + // 预算:不足 topK ⇒ 追加到 topK 封顶;已满 ⇒ 顶掉最后一位(尾部 1 个 + // 槽位让给 FTS 最高分命中;头部 topK-1 条逐条不动 ⇒ 主路径回归面收敛) + // —— 保持 len(results) ≤ topK 不变量,不破坏调用方的 limit 语义。 + budget := topK - len(results) + if len(results) >= topK { + results = results[:len(results)-1] // 顶掉最后一位 + budget = 1 + } + nAppend := budget + if nAppend > len(fresh) { + nAppend = len(fresh) + } + for i := 0; i < nAppend; i++ { + rec := fresh[i] + // 展示分口径(与主路径「响应值==库值」铁律对齐): + // QualityScore = DB 原值(词面分不进展示分,只进排序) + // Score = 词面分(0..1,本条的通道分;FtsBoosted=true 可辨来源) + results = append(results, models.RecallResult{ + ID: rec.ID, + Content: rec.Content, + Category: rec.Category, + Score: ftsScoreOf[rec.ID], + Timestamp: rec.CreatedAt.Format(time.RFC3339), + Namespace: rec.Namespace, + AgentID: rec.AgentID, + Source: rec.Source, + QualityScore: rec.QualityScore, + QualityScoreReliable: false, // FTS 记录未经过质量融合 ⇒ 标不可信(审计可辨) + FtsBoosted: true, + }) + } + } + // Step 5: 图谱融合扩展(不再作为后备补丁,每次 recall 都跑 1 跳) if p.graph != nil { expanded := p.graph.ExpandFromResults(results, namespace, 1)