feat(recall): t_2afae95e FTS 词面检索通道(TF-IDF 倒排,Go 内存索引,env-gate 默认关)

根因:金标 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 全绿。
This commit is contained in:
xiaowei
2026-10-14 13:02:37 +08:00
parent 339642b2c8
commit db6ab564dc
5 changed files with 819 additions and 5 deletions
+22
View File
@@ -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())
+9 -3
View File
@@ -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 处理。
+358
View File
@@ -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()
}
}()
}
+327
View File
@@ -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
}
+103 -2
View File
@@ -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)