|
|
0365b08dc9
|
fix(knowledge): 改成词法路为主，RRF 方案实测无效
## 上一版（RRF）在生产上零收益
73bc3f9 用「稠密 1.0 / 词法 0.5 的 RRF」重启部署后，生产上 7 条查询
结果基本没变，目标条目一次都没进前三。原因是我在**本地退化路径**上验证，
而生产走稠密路径——两个分支的融合逻辑根本不同。
在真实 196 条库 + 真实 chineseclip 上测出两路的名次，问题一目了然：
查询 稠密名次 词法名次
PruneOldBackups 103 1
strip_path 164 1
minSceneEvidence 130 1
coldcontext_query 149 1
上下文裁剪的保护条数受什么约束 157 1
冷上下文取回为什么不能先删后灌 158 1
词法路全中，稠密路全在 100 名外。稠密权重 1.0 时它的 `1.0/61` 永远压过
词法的 `0.5/61`，所以词法路精确命中也没用。
## 为什么连 RRF 本身也不行
试过把权重翻成词法 1.0 / 稠密 0.5，仍然错。因为 RRF **丢掉分数差距**：
`strip_path` 的 top1 是 0.056、top2 是 0.055 —— 名次差 1，RRF 当它们等强，
稠密对 top2 的加分一叠就反超。
## 现在的做法：fuseLexPrimary
- 词法路给主序，**保留分数差距**（这是关键词）
- 稠密路用于：同分裁决、补位、以及词法无信号时接管
（`minLexSignal = 0.02`，低于此视为 jieba 泛滥词的微弱命中，让稠密接）
- 稠密结果仍然被使用，不是死代码
## 实测（真实库 + 真实模型）
top1 = 10/13 top3 = 11/13
改前生产表现：7/7 全错。剩下的 3 条未命中（仓颉关键字 rank2、鸿蒙、更新日志）
是既有的弱点，与本次改动无关。
## 判据
- `TestDensePathFeedsRanking`：钉「稠密结果必须喂进排序」（改了形状，意图不变）
- `TestSearchDocReflectsFusion`：钉文档写明 fuseLexPrimary + 词法为主
- 文档注释里记下两次翻转（2026-10-08 → 10-31）与 RRF 被否的实测原因，
避免下一个人再翻回去
|
2026-10-31 16:57:29 +08:00 |
|
|
|
0ca9e96290
|
fix(knowledge): 修复英文标识符检索不到（分词器 + RRF 融合）
## 故障
真实库 196 条里 154 条是 cangjie 文档（1.53MB / 88.6% 字节）。用户反馈
「语义检索命中偏弱，cangjie 霸榜」。实测三条带精确标识符的查询：
PruneOldBackups → top5 全是 cangjie，目标条目一次没出现
minSceneEvidence → 同上
strip_path → 同上
## 真因不是 cangjie，是分词器
cangjie 只是把问题放大的体量。真正的洞在 `memory.TokenizeWords`（jieba）
对英文标识符的处理 —— 实测：
PruneOldBackups → [P r u n e O l d B a c k p s] ← 切成单字符还去重
strip_path → [s t r i p _ a h]
于是任意两篇含英文字母的文档 token 重叠率都能到 50%，词法路彻底失效。
而稠密路（chineseclip）对「只在文中出现一次的专名」本就没有分辨力。
这解释了 2026-10-08 那次决策：当时把词法路从融合里去掉，理由是
「词法路对英文标识符失效」—— 观察对，**归因错**：失效的是分词器。
## 改法
1. `identtoken.go`（新）：知识库词法路专用分词器
- 补标识符**整词**：`PruneOldBackups` → `pruneoldbackups`
- 补**分隔符部件**：`strip_path` → `strip` / `path`（仅当下划线等存在时）
- **不拆 camelCase**：拆了会产出 `old`/`backups`，而 `old` 在
`cangjie/tools/cmd-tools/cjcompat_manual` 里是 CLI 参数名 `--old`，
出现 31 次 —— 实测评测中该文档得分 0.54 > 目标的 0.20，正好把无关文档顶上来
- 丢掉 jieba 切出来的单字母残渣
- 中文分词完全沿用 jieba，行为不变
- 只注入知识库的 veczer，**不动** memory 索引/关键词提取
2. `fusion.go`（新）：RRF 倒数排名融合
- `score = 1.0/(60+rank_dense) + 0.5/(60+rank_lex)`
- 不用当初那套「逐路按查询内最大值归一化」：那个做法把 0.02 的噪声抬到
与 1.0 等权，正是 2026-10-08 淘汰融合的真凶。RRF 只看名次，与量纲无关
- 稠密权重 1.0（语义主线）/ 词法 0.5（精确命名救助）
3. `Search` 文档注释重写：把两段历史都写清（2026-10-08 为何淘汰、2026-10-31
为何加回但换成 RRF），避免下一个人重复踩。
## 判据
- `TestIdentifierTokenFeedsLex`：钉分词结果（必须产出整词、不得拆出 old）
- `TestIdentifierQueryBeatsVolume`：60 篇英文词密集的噪声文档 + 一条只在
目标条目出现一次的标识符，top1 必须命中目标 —— 分词器一退化就红
- `TestSeparatorIdentifierNotBuried`：带 `_` 的标识符，整词要压过部件噪声
- `TestDensePathFeedsRanking`（原 `TestDensePathIsSoleRecall`）：保留它真正的
意图 —— 防「调用了 denseHits 却把结果丢掉」这个反模式，形状改为喂给 fuseRRF
- `TestSearchDocReflectsRRF`（原 `..DenseOnly`）：钉文档与实现不漂移
## 验证
go build ./... ✓
go vet ./internal/knowledge/ ✓
gofmt -l ✓
go test ./internal/knowledge/ ✓（含 -race）
go test ./... -count=1 全绿
⚠️ 生产实例需重启才能生效（lex 索引在启动时重建，无数据迁移）。
|
2026-10-31 16:42:36 +08:00 |
|
|
|
4e70b8d5d8
|
refactor(module): 核心仓 Go module 路径改为 github.com/JianFeeeee/HologramAgent
批 1，不含 SDK 仓与目录改名。
- go.mod 第 1 行 module 路径
- 366 个 .go 文件的完整前缀 github.com/JianFeeeee/HomeAgent 机械替换
（857 处，仅完整前缀；展示名/注释里的 HomeAgent 字样留给批 5）
- 未改：third_party 目录名、SDK 自身 go.mod module、go.mod replace 目标、
homed/waiter 可执行名、.hmap 后缀
|
2026-10-21 12:17:19 +08:00 |
|
|
|
5187a62f47
|
feat(knowledge)!: 检索改为纯稠密向量路，去掉三路融合
按「完全改用向量方案」的要求，SearchIn 现在只走多模态稠密路，
不再与稀疏语义路 / 词法路融合。
## 为什么必须去掉融合（实测，不是判断）
生产知识库（192 条）上，10 条带标注查询的命中率：
改前（三路融合） top1= 1/10 top3= 2/10
改后（纯稠密路） top1= 6/10 top3= 7/10
改前连条目**自己的全名**都搜不到：
`plugin_dev_sdk` 搜不到 `plugin_dev_sdk`、`homeagent_identity` 搜不到
`homeagent_identity`，用户看到的是「查什么都返回同样的几个无关条目」。
而稠密路单独打分时**全库排名 1/192**：
the_jet_engine → the_jet_engine_rolls-royce 0.769
plugin_dev_sdk → plugin_dev_sdk 0.852
homeagent_identity → homeagent_identity 0.823
### 根因：逐路归一化把噪声抬到与信号同权
`addPath` 把每路都按**查询内最大值**归一化到 1.0 再加权：
scores[h.id] += weight * h.score / max
于是词法路原始分只有 **0.027** 的弱信号归一化后也变成 1.0，与稠密路的
1.0 等权相加。叠加两个因素：
- jieba 把英文标识符切碎：`the_jet_engine_rolls-royce` →
`[t h e _ j n g i r o l s - y c]`，两条**无关**文档 token 重叠 50%
- `SetMinScore(0)` 导致 186/192 条都进候选，几乎全库打分
余弦分数**本身就可比**（同空间同维度），根本不需要逐路归一化 ——
那一步当初是为「量级不同的三路」服务的，现在只剩一路，它反而成了
破坏排序的东西。
## 历史结论为何在此翻转
旧注释引的实测（仅稠密路 top-1 15% / MRR 0.271；融合后 21% / 0.376）
建立在这两个**已不成立的前提**上：
- 33 条的小规模 KB（现 192 条，含大量英文标识符）
- 稀疏 fastText 词向量（现 chineseclip 512 维多模态空间）
那段结论我没删，而是在 Search 的注释里写明「前提已变、结论翻转」，
免得后来者看到旧数字又把它改回去。
## 退化路径有意保留
未注入多模态空间时（provider 留空）仍走稀疏两路。不保留的话，
那些部署的知识库会直接变成**完全不可用** —— 比排序差更严重。
该路径行为与接入稠密路之前逐字一致（TestNoDenseSpaceKeepsLegacyBehavior）。
## 判据（都可杀变异，逐个实测）
新增 `dense_recall_quality_test.go`：
- `TestDenseRecallQuality`——带标注 10 条查询，门槛 top1≥4 且 top3≥7。
把 denseEnabled 改成恒假 → FAIL「top1 仅 1/10」（正是退化态）
- `TestDensePathIsSoleRecall`——钉形状：稠密路必须在稀疏路之前且
**结果真的参与组装**。第一版只查「有没有调 denseHits」，把结果赋给 `_`
仍能骗过它；补上 `s.items[h.id]` 断言后，变异（结果不参与组装）才被杀
- `TestSearchDocReflectsDenseOnly`——防文档漂移。第一版简单搜「三路」
会误伤（新文档解释「为何不再融合」时正当地提到它），改为检查只在
*声称当前如此* 时才会出现的句子
## 顺带修的
- `TestDenseCrossModalRecall` 的桩把**所有未知文本**映射到同一向量，
导致 `other` 与 `cat-photo` 正文同向、「猫」查询下 `other` 以余弦 1.0
压过 `cat-photo` 的 0.707。那是**桩的假象不是产品缺陷**。给 other
一个真正正交的方向（且 key 必须是 denseFor 实际传入的
`Name + " " + Content`，写成纯 Content 会静默回落到默认向量）。
- 清掉随融合退场的死代码 `denseSpaceWeight` / `hasAnyDense`，
并把 `vec`/`lex` 字段注释改准（它们现在只服务退化路径）。
- `rankdiag_test.go` 现在测的是**退化路径**（它不注入多模态空间），
注释与门槛说明据此改准：实测 top-1 24% / MRR 0.358，
别拿它当知识库的检索水平。
全仓 `go test ./...` → 48 包 ok / 0 FAIL。
|
2026-10-08 21:34:30 +08:00 |
|
