Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -154,3 +154,6 @@ query_memory(user_id, query, session_id=None) -> Dict
3. **`SimpleConnectionPool` 非线程安全**——生产并发需 `ThreadedConnectionPool`
4. **`unified_search` 未把 `memory_embedding`(向量语义)纳入检索优先级**——向量层是独立查询
5. 程序性记忆自动触发机制(当前靠手动调用触发/生成流程)
6. **`rerank_with_llm`(LLM 重排序)未启用** —— 实现了但不在检索链上(真检索在 `rrf_fusion` 后直接截断)。
⚠️ 这是**已裁决的「不启用」**,不是遗漏:当前 `DEEPSEEK_API_KEY` 默认为空 ⇒ 收益为零、代价确定(每次 RAG 多一次秒级往返)。
裁决与启用办法见 `docs/decisions决策/DEC-004-重排序是否接线-20260921.md`。
18 changes: 18 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,24 @@
- job `test-embedding`:装 Ollama + 拉 `bge-m3` → `pytest -m requires_ollama`(13 用例)
- 为什么分两个 job → **`docs/decisions决策/DEC-002-CI的embedding边界-20260921.md`**

### 第 3 轮 · A1 处置 + E 断言补齐 · 🚧 进行中

- **A1 · `rerank_with_llm` 重排序** —— ✅ **裁决:不接,明确标注「未启用」**
docstring 写明「⛔ 未启用」+ 为什么(外部 LLM 依赖 / 每次 RAG 多一次秒级往返 /
`DEEPSEEK_API_KEY` 默认为空 ⇒ **收益为零、代价确定**)+ 将来怎么启用(含降级路径与性能断言)。
`ARCHITECTURE.md §11` 同步登记。裁决见 **`DEC-004`**
- **E · 性能排序断言** —— ✅ 处置,**但结论与 audit 的预设不同**:
| 关系 | 结果 |
|---|---|
| `KV < Ledger`、`Vector/RAG > KV × 20` | ✅ 稳定成立,**已断言**(实测差约 600 倍)|
| **`Vector < RAG`** | ❌ **不成立** —— 补上后**第一次跑全量就红了**;两者都含同一次 embedding,冷启动下仅差 **6%**(373 vs 397ms)|

⇒ **不只是"文档没验证过",而是那句话本身不成立**。文档已改成与事实相符,
并发耗时列标注为**记录值、非断言值**。判据与证据见 **`DEC-005`**
(「断言只能写机制决定的关系,不能写当次测量决定的关系」)
- **`CLAUDE.md` 保鲜** —— 清掉 5 处已过时的警告(如"Ollama 未安装"、"7 个模块留着死 `PG_CONN`"、
"15s 超时待修"、"45 passed"),**过时的警告比没有更坏**

### 修订(Changed)· **CI 改成两个 job 都阻断**

- 去掉 `test-embedding` 的 `continue-on-error: true`(**推翻 DEC-002 原裁决**,当日修订,见该文档 §七)
Expand Down
26 changes: 15 additions & 11 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ docker compose up -d # Redis 走 6379 上现成的 redis-rag,不在此列
# 环境:venv 已建好(Python 3.11);重建时用 python3.11,⛔ 别用 3.9(见 §2 坑 1)
source memory-system-venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # 只有 DEEPSEEK_API_KEY 真被代码读取
cp .env.example .env # PG_PASSWORD 必填;DEEPSEEK_API_KEY 可留空(见 §4)

# 全部测试 / 单个文件 / 单个用例
./memory-system-venv/bin/python -m pytest -q
Expand All @@ -27,7 +27,7 @@ cp .env.example .env # 只有 DEEPSEEK_API_KEY 真被代码读取
可直接 `python ledger_api.py` 单独跑该模块的自检 —— **这是不起服务、不跑 pytest 时最快的单模块验证方式**(需在仓根、用 venv 的 python)。
不起 `main()` 的是:`unified_api` `db_pool` `cache_manager` `skill_finalizer` 与一次性脚本(`insert_*` `append_location_history` `embedding_test`)。

外部依赖:**Ollama `bge-m3`**(`ollama pull bge-m3`,向量/技能匹配必需 —— ⚠️ **本机当前未安装**,缺它会有 11 个用例失败)、
外部依赖:**Ollama `bge-m3`**(已装好、模型已拉,向量/技能匹配必需 —— 见 §2)、
**DeepSeek API Key**(可选,缺省降级为规则摘要 / 跳过 LLM 重排序)。

---
Expand All @@ -47,14 +47,16 @@ cp .env.example .env # 只有 DEEPSEEK_API_KEY 真被代码读取

**四条坑,动手前先知道:**

1. **`requirements.txt` 在 Python 3.9 上装不上** —— 文件头写着「Python 3.9,验证可复现」,但 `urllib3==2.6.3` 现在要求 ≥3.10 ⇒ **只能用 3.11+**。(3.9 是原环境;今天已不成立。**未修,待裁决**。)
1. **`requirements.txt` 在 Python 3.9 上装不上** —— `urllib3==2.6.3` 现要求 ≥3.10 ⇒ **只能用 3.11+**。
✅ 文件头那句「Python 3.9,验证可复现」**已于第 1 轮改正**(现写 ≥3.10 + 原因 + 回归 3.9 的办法)。
2. **端口 5432/6379 被 rag 项目占着** —— `postgres-rag`(pg17,库 `rag_db`/`rag_test`,只有 `postgres` 角色) 与 `redis-rag`。所以本项目 PG 改到 **5433**:`db_pool.py`(连接池)与 `event_bus.py`(`EventBus` 自己直连,**写路径绕开连接池**)两处已同步。
3. **`data/db` 是原库的整份副本**(含原项目 8/16 的实验数据,非空库)。测试按 `user_test_%` 前缀隔离,不受影响。
4. **首次跑 embedding 会冷启动超时(flake)** —— 模型要现加载 1.2 GB,而 `skill_candidate_store.py` 的超时写死 **15s**(其余几处是 30/30/30/60)。
⇒ 表现是 `test_day18::test_procedural_memory_evolution` 偶发 `ReadTimeout` 变红,**不是逻辑错**。
4. **首次跑 embedding 仍可能慢(但不再必超时)** —— 模型要现加载 1.2 GB。
✅ 第 1 轮已把 `skill_candidate_store` 的超时 **15s → 30s**,与其余几处统一(此前 15s 不够冷启动,表现为 `test_day18` 偶发 `ReadTimeout`)。
**做法**:跑全量前先 `curl -s http://localhost:11434/api/tags >/dev/null` 唤醒,或先单跑一条。

**跑测试**:`./memory-system-venv/bin/python -m pytest -q` → 当前 **45 passed / 0 failed**(模型热的情况下;冷启动可能因上面第 4 条偶发红)。
**跑测试**:`./memory-system-venv/bin/python -m pytest -q` → 当前 **58 passed / 0 failed**。
不起 Ollama 时:`pytest -m "not requires_ollama"` → **45 passed**。
**全量耗时 41–75 s** —— 差异全在 embedding 走 CPU,别以为是卡死了。

---
Expand Down Expand Up @@ -106,9 +108,10 @@ skill_candidate_store(候选 + 双阈值 0.85/0.65 检索)
`PG_PASSWORD` **没有默认值**:缺失时 `db_pool` 直接抛明确错误,compose 用 `${PG_PASSWORD:?}` 拒绝启动。
- **服务地址仍硬编码**:`OLLAMA_EMBED_URL`(`http://localhost:11434/api/embed`,散在 `vector_semantic`/`skill_candidate_store`/`skill_matcher_v2`)、DeepSeek 的 URL 与模型名。
- **`DEEPSEEK_API_KEY` 从环境变量读**(`os.getenv`,散布在 `summary_api`/`rag_knowledge`/`skill_generator`/`vector_semantic` 四处)。**缺它不算错**:摘要降级为规则摘要、SKILL 生成抛 `SkillGenerationError`、LLM 重排序跳过。
- ⚠️ **只有两处 PG 连接是活的**:`db_pool.py`(连接池,读路径用)与 `event_bus.py` 的 `EventBus.__init__`(**写路径自己直连,绕开连接池**)。
**另有 7 个模块**(`kv_api` `ledger_api` `summary_api` `policy_api` `rag_knowledge` `skill_candidate_store` `vector_semantic`)各自留着一份**死掉的** `PG_CONN = {...}` + 三引号注释掉的 `_get_conn()` —— 它们是**地雷**(谁解注释谁就连到错库),不是活配置。
**改端口/改库名必须动的是上面那两处**,别只改一处。
- **全仓只有两处 PG 连接**:`db_pool.py`(连接池,读路径用)与 `event_bus.py` 的 `EventBus.__init__`(**写路径自己直连,绕开连接池**)。
**改端口/改库名必须同时动这两处。**
⚠️ **遗留**:连接池在**写路径上仍未生效**(`EventBus` 每次 `record_event` 新建连接再关,见 audit D1 未修部分)。
7 个模块曾各有 `PG_CONN` + 注释掉的 `_get_conn` 死代码 —— **已于第 1 轮清除**(别再按旧文档去找它们)。
- **新增/修改任何查询都必须透传 `user_id`**(默认值 `"user_default"`)。同理 RAG 相关必带 `tenant_id`。这是全仓一致性要求,也是唯一有测试兜底的设计约束。
- **阈值不要抄数字,引用常量名**:`skill_candidate_store.py`(`SUCCESS_SIMILARITY_THRESHOLD=0.85` / `QUERY_SIMILARITY_THRESHOLD=0.65`)、`skill_matcher_v2.py`(复用阈值 0.55)。
⚠️ 曾有 **5 处 docstring 停在旧值 0.75/0.50**(与常量差了整整一档)—— **这就是抄数字的后果**,已于第 1 轮全部改成引用常量名。别再抄。
Expand Down Expand Up @@ -151,12 +154,13 @@ skill_candidate_store(候选 + 双阈值 0.85/0.65 检索)

| 条目 | 说明 |
|---|---|
| **A1** | `rerank_with_llm` 未接线 —— 定义在 `vector_semantic.py`,唯一调用点在自己模块的 `main()` 演示里;真检索走 `rrf_fusion` 后**直接截断**,没有重排那一步。**改它要先做 DEC**(接进去 / 还是删掉或标"未启用") |
| **E** | 性能断言缺口:`性能基线与容量规划.md` 声称"排序验证结论…断言通过",但测试只断言了 2 条关系 |
| ~~**A1**~~ | ✅ **已裁决:不接,明确标注未启用**(`DEC-004`)。docstring 已写「⛔ 未启用」+ 为什么 + 将来怎么启用;`ARCHITECTURE.md §11` 同步 |
| ~~**E**~~ | ✅ 已处置(`DEC-005`):断言只保留**稳定成立**的关系;`Vector<RAG` 实测不成立(差 6%),已在文档与测试里改掉 |
| **D4** | `search_rag_knowledge` 同一查询查两遍 + BM25 语料每次现建 |
| **口令轮换** | 旧 PG 口令仍在公开 git 历史里,改代码抹不掉 —— 需 `ALTER USER` + 更新 `.env` |

> ✅ 第 2 轮已完成:**A3**(RAG 条件性判据)· **B1①②**(接线 + 删幻影形参)· 挂 CI · 文档计数校正
> ✅ 第 3 轮:**A1**(重排序:裁决为**不接**,标注未启用,见 DEC-004)· **E**(性能断言:**`Vector<RAG` 不成立**,改为只断言稳定关系,见 DEC-005)

> ⚠️ **第 1 轮已修的:A2 · C2 · D1 · D2 · B2 · B3 · D3**,外加两条新发现(**删除不清缓存** · 7 个模块的死 `PG_CONN`)。
> 细节与证据全在 `CHANGELOG.md` 与复盘里 —— **别再照待修清单去"修"已修好的东西**。
Expand Down
63 changes: 63 additions & 0 deletions docs/decisions决策/DEC-004-重排序是否接线-20260921.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# DEC-004 · `rerank_with_llm` 接不接进检索链

| 项 | 值 |
|---|---|
| **日期** | 2026-09-21 |
| **状态** | ✅ 已裁决(用户 2026-09-21 选定「**不接,明确标注未启用**」) |
| **触发** | `audit源码通读-待修清单-20260921.md` **A1** ——「重排序实现了,但真正的检索入口从不调用它」 |
| **相关** | `vector_semantic.rerank_with_llm` · `rag_knowledge.search_rag_knowledge` · `DEC-003`(同族:判据里的幻影量) |

---

## 一 · 问题

`rerank_with_llm` 实现了(约 80 行,含 prompt 与日志),**但没有任何生产调用点**:

- 定义:`vector_semantic.py:423`
- 唯一调用点:同文件 `main()` 的演示(对比 `hybrid_search` 的结果)
- **真检索**:`rag_knowledge.search_rag_knowledge` 在 `rrf_fusion(...)` 之后**直接 `return fused[:limit]`**

⇒ 检索链的实际形态是 **改写 → 向量+BM25 → RRF → 截断**,**没有重排那一步**。

**为什么必须处理它**:「实现了但不生效」是最容易被误当成「已具备该能力」的一类 ——
这正是本仓的系统性模式(`demote_from_kv` · `cache_delete` · `summary_confidence` 都如此,见 CLAUDE.md §6)。

## 二 · 备选方案(三选一)

| 方案 | 做法 | 优 | 劣 |
|---|---|---|---|
| A. 接进去 | 在 `rrf_fusion` 之后调 `rerank_with_llm` 再截断 | 检索质量可提升;能力真实生效 | 每次 RAG **多一次外部 LLM 往返**(秒级;实测 RAG 均 **573ms**);依赖 DeepSeek 可用性;需补降级路径 |
| **B. 不接,明确标注「未启用」** ✅**选定** | 保留代码,但在 docstring 明写未启用 + 为什么 + 如何启用;文档与 `ARCHITECTURE` 同步 | **零风险、零延迟代价**;消除"以为已具备"的误导;保留未来启用的可能 | 重排序这个能力**当前不生效**(但这是事实,不是隐瞒) |
| C. 接进去 + 调用方开关 | `search_rag_knowledge(..., rerank=True)` 默认关 | 兼顾两者 | 多一个开关;默认关 ⇒ **实践中几乎不会开**,等于换个形式挂在那里 |

**选 B 的核心理由**:**当前收益为零、代价确定。**
`.env` 里 `DEEPSEEK_API_KEY` 默认为空 ⇒ 接进去也只是打印"跳过 LLM 重排序"再原样返回;
而代价(一次秒级往返、一个外部依赖、一条要维护的降级路径)是**确定的**。
在收益为 0 时付出确定代价,不划算 —— 与 DEC-003 同一条纪律:**别留旋钮没人转**。

## 三 · 决定

1. **不改检索链**:`search_rag_knowledge` 保持 `rrf_fusion → 截断`。
2. **在 `rerank_with_llm` 的 docstring 里明写「⛔ 未启用」**,含三件事:
- 为什么**不接**(不是忘了接)—— 外部 LLM 依赖 / 秒级往返 / Key 默认为空
- **唯一调用点**是 `main()` 演示
- **若要启用**:在 `rrf_fusion` 之后接,**并同时**给出降级路径与性能影响评估
3. `ARCHITECTURE.md §11`(已知缺口)与 `CLAUDE.md` 的待办表同步标注为「已裁决:不接」。

## 四 · 反悔成本 / 将来怎么启用

**低。** 启用是一个局部改动(一个调用点 + 一条降级路径 + 一组性能断言):

1. 配好 `DEEPSEEK_API_KEY`(否则重排序是空转)
2. 在 `search_rag_knowledge` 的 `rrf_fusion(...)` 之后加 `rerank_with_llm(query, fused)`
3. **必须同时**:
- 降级路径(LLM 超时/报错 ⇒ 回到未重排结果,不能把 RAG 打挂)
- 性能断言(加入重排后 RAG 的延迟上限要重新标定,见 `性能基线与容量规划.md`)
- 一条测试证明"有重排 vs 无重排"的排序确实变了(否则无法证明它生效)
4. 更新本 DEC(状态改为"已启用")与 `ARCHITECTURE.md`

## 五 · 验收判据

- [x] `rerank_with_llm` 的 docstring 有「未启用」标记与理由
- [x] `grep -rn "rerank_with_llm"` 的结果中,**生产代码里没有调用点**(只有定义 + `main()` 演示)
- [x] 本 DEC 落文档;`ARCHITECTURE.md §11` / `CLAUDE.md` 同步
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# DEC-005 · 性能排序断言能断言到什么程度(`Vector < RAG` 不成立)

| 项 | 值 |
|---|---|
| **日期** | 2026-09-21 |
| **状态** | ✅ 已处置(用户当日选「补齐那条断言」,**补了之后发现它不成立**,故改为只断言稳定关系) |
| **触发** | `audit源码通读-待修清单-20260921.md` **E** ——「文档说"排序验证结论…断言通过",但测试只断言了 2 条关系」 |
| **相关** | `test_day19_performance_stability.py` · `性能基线与容量规划.md §一` · `DEC-003`(同族:别断言幻影量) |

---

## 一 · 事情经过(这次是"补了才发现")

1. audit 的 E 指出:文档声称 `KV < Ledger < Vector < RAG`「断言通过」,**实际只断言了 2 条**
(`KV≤Ledger`、`RAG>KV`)。选项是「补齐那两条」或「改文档为部分断言」。
2. 用户当日选**补齐**。
3. 补齐后**第一次跑全量就红了**(`test_performance_baseline`)。
4. **主动复现**(`ollama stop bge-m3` 造冷启动)拿到实测值:

| 层 | 平均 |
|---|---|
| KV | 0.4 – 0.6 ms |
| Summary | 1.0 – 1.4 ms |
| Ledger | 1.1 – 1.6 ms |
| Vector | **290 – 373 ms** |
| RAG | **341 – 554 ms** |

5. ⇒ **`Vector` 与 `RAG` 差值落在噪声里**(冷启动下 373 vs 397 ms,**只差 6%**)。
两者的耗时**都由同一次 Ollama embedding 主导**,谁快取决于当时负载 ⇒ **不可稳定排序**。

**结论不只是"文档没验证",而是"那句话本身不成立"。**

## 二 · 决定

**断言只写稳定成立的关系**(`test_day19`):

| 关系 | 断言? | 依据 |
|---|---|---|
| `KV < Ledger` | ✅ 断言 | 同为毫秒级但稳定差 2–3 倍 |
| `Vector > KV × 20`、`RAG > KV × 20` | ✅ 断言 | 实测差 **约 600 倍**,稳 |
| **`Vector < RAG`** | ⛔ **不断言** | 差值 6%,被噪声打红 |
| 各层绝对阈值(KV/Summary/Ledger<0.5s、Vector/RAG<5s) | ✅ 保留 | 只做"别慢到离谱"的兜底 |

文档同步改成与事实相符(`性能基线与容量规划.md §一`),并把并发的耗时列标注为**记录值、非断言值**。

## 三 · 可复用的判据(本次的实质产出)

> **断言只能写"机制决定的"关系,不能写"当次测量决定的"关系。**

判别方法:**问这句话是否由架构决定,而不是由当次负载决定。**
- 「向量层比 KV 慢一个量级」—— **架构决定**(KV 走缓存,向量层必须调 embedding)⇒ 可断言
- 「向量层比 RAG 快」—— **当次测量决定**(两者都含 embedding,差值是噪声)⇒ 不可断言

**推论**:一条断言若**必须靠"这次刚好"才过,它就是在给未来埋一个 flaky 测试**。
本次若不是真去补、真看它红,就会留下一颗这种雷。

## 四 · 为什么这和 `DEC-003` 是同一条纪律

| | 表现形式 | 共同判据 |
|---|---|---|
| `DEC-003` | 判据里用了**没有生产者**的量(`summary_confidence` 恒 0.0) | **别让"没人产出的东西"参与判定** |
| `DEC-005` | 断言里写了**不稳定成立**的关系(`Vector<RAG`) | **别让"当次测量"冒充"架构事实"** |

⇒ 都是:**别把"看起来该是这样"写进判据/断言。** 先量,再写。

## 五 · 反悔成本

低。若将来把 Vector 与 RAG 的路径拆开(例如 RAG 不再复用同一 embedding、或加了重排序
使 RAG 必然显著变慢),那条关系**由架构决定**了,就可以把断言加回来 —— 届时请**同时更新本 DEC**。
20 changes: 18 additions & 2 deletions test_day19_performance_stability.py
Original file line number Diff line number Diff line change
Expand Up @@ -99,8 +99,24 @@ def bench(name, fn):
# ---- 断言(Vector/RAG 含 Ollama embedding,阈值放宽)----
for layer, thr in [("KV", 0.5), ("Summary", 0.5), ("Ledger", 0.5), ("Vector", 5.0), ("RAG", 5.0)]:
assert layers[layer]["avg"] < thr, f"{layer} 平均 {layers[layer]['avg']:.4f}s 超过阈值 {thr}s"
assert layers["KV"]["avg"] <= layers["Ledger"]["avg"], "KV 应快于 Ledger"
assert layers["RAG"]["avg"] > layers["KV"]["avg"], "RAG 应慢于 KV"

# ---- 排序断言:只断言**稳定成立**的关系 ----
# ⚠️ 2026-09-21 修正。原先 性能基线与容量规划.md §一 声称
# 「KV < Ledger < Vector < RAG(断言通过)」,但实测下来**最后一段不成立**:
# · 稳定:DB/缓存层(毫秒)≪ 向量/RAG 层(百毫秒,被 embedding 主导)
# 实测 KV 0.4–0.6ms · Ledger 1.1–1.6ms · Vector 290–373ms · RAG 341–554ms
# · **不稳定**:Vector 与 RAG 谁更快 —— 两者都含同一次 Ollama embedding,
# 冷启动下实测仅差 6%(373 vs 397ms);跑全量时曾真的出现 RAG 反超 Vector
# 导致断言失败(这就是加它之后立刻红一次的原因)。
# ⇒ ⛔ **不要再把 Vector<RAG 写成断言**,那是会被噪声打红的假关系。
# 改成断言"量级":向量/RAG 两层都应比 KV 慢 20 倍以上(实测差 600 倍,稳)。
assert layers["KV"]["avg"] < layers["Ledger"]["avg"], \
"KV 应快于 Ledger(同为毫秒级,稳定成立)"
for layer in ("Vector", "RAG"):
assert layers[layer]["avg"] > layers["KV"]["avg"] * 20, (
f"{layer}({layers[layer]['avg']:.4f}s) 应比 KV({layers['KV']['avg']:.4f}s) "
"慢 20 倍以上 —— 这是「向量/RAG 被 embedding 主导」的稳定体现"
)
print(f"[perf] sync_new_events 返回: {sync_result}")
print(f"[perf] 基线汇总: { {k: round(v['avg'], 4) for k, v in layers.items()} }")

Expand Down
Loading
Loading