From fdcd3657430087d3d18b9c2501b7cb4cff16cc9b Mon Sep 17 00:00:00 2001 From: heweidong-ecco <290444878+heweidong-ecco@users.noreply.github.com> Date: Mon, 21 Sep 2026 20:50:13 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20D4=20=E5=90=88=E5=B9=B6=20RAG=20?= =?UTF-8?q?=E6=A3=80=E7=B4=A2=E6=9F=A5=E8=AF=A2=20+=20=E6=8B=86=E6=8E=89?= =?UTF-8?q?=20testpaths=20=E9=99=B7=E9=98=B1=EF=BC=9B=E5=8F=A3=E4=BB=A4?= =?UTF-8?q?=E8=BD=AE=E6=8D=A2=E5=AE=8C=E6=88=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit D4 · search_rag_knowledge 同一张表查两遍 → 合并为一次查询 先核实"合并会不会丢掉索引优化"(不能凭印象):content_embedding 上 **没有任何向量索引**(只有 pkey + 两个 btree),原来那句 ORDER BY cosine_distance LIMIT k 本来就是全表扫描 + 排序 ⇒ 合并零损失。 TDD(红绿都看着发生): · 先写 test_day24(3 用例):特征测试 2 条**重构前后都绿**(安全网), 往返次数那条 **RED = 实测 2 次** → 改完 GREEN = 1 次 · 排序用**原始距离**而非四舍五入后的 similarity(否则极近距离会因取整换序) ⚠️ 有意不做 BM25 索引缓存:失效边界不好划,键选错会**静默返回过期结果** (比慢更糟)—— 理由与将来怎么补见 DEC-006 §四 🔧 顺带拆掉一个反复踩中的陷阱:pytest.ini 改为自动收集 本仓**第三次**撞上"新测试文件不加进 testpaths 就不被收集" —— pytest 会**静默少跑**,看着绿其实没测(day20 / day22 / day24)。 改为 testpaths = . + norecursedirs(必须含 memory-system-venv —— pytest 默认只认 "venv" 这个名字,不排除会把 site-packages 扫进来)。 验证:自动收集到 61 个用例 / 8 个文件,venv/data/archive 零命中。 🔐 口令轮换完成(上一轮遗留) ALTER USER + 更新 .env(不入库);实测**旧口令登录被拒**、新口令走代码正路可连。 ⇒ 改代码抹不掉历史,唯一解是让历史里的值失效。 提交前两问 ① 本次有决策事项 ⇒ 新建 DEC-006-rag检索的往返次数-20260921.md (含"先看索引再决定查几次"的判据、有意不做的部分、反悔成本) ② CHANGELOG 已写(第 3 轮) 测试:61 passed(全量)· 45 passed / 16 deselected(不依赖 embedding) --- CHANGELOG.md | 17 ++++ CLAUDE.md | 18 ++-- ...7\224\346\254\241\346\225\260-20260921.md" | 95 +++++++++++++++++++ pytest.ini | 16 +++- rag_knowledge.py | 70 ++++++-------- test_day24_rag_search_roundtrip.py | 93 ++++++++++++++++++ 6 files changed, 258 insertions(+), 51 deletions(-) create mode 100644 "docs/decisions\345\206\263\347\255\226/DEC-006-rag\346\243\200\347\264\242\347\232\204\345\276\200\350\277\224\346\254\241\346\225\260-20260921.md" create mode 100644 test_day24_rag_search_roundtrip.py diff --git a/CHANGELOG.md b/CHANGELOG.md index a687aa8..11172cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -57,6 +57,16 @@ ⇒ **不只是"文档没验证过",而是那句话本身不成立**。文档已改成与事实相符, 并发耗时列标注为**记录值、非断言值**。判据与证据见 **`DEC-005`** (「断言只能写机制决定的关系,不能写当次测量决定的关系」) +- **D4 · `search_rag_knowledge` 查两遍** —— ✅ 合并为**一次查询**(`DEC-006`)。 + **先核实"合并会不会丢掉索引优化"**:`content_embedding` 上**没有任何向量索引**, + 原 `ORDER BY cosine_distance LIMIT k` 本来就是全表扫描 + 排序 ⇒ 合并**零损失**。 + TDD:先写 `test_day24`(3 用例)—— 特征测试 2 条**重构前后都绿**(安全网), + 往返次数那条**先红**(实测 2 次)→ 改完变绿(1 次)。 + ⚠️ **有意不做** BM25 索引缓存:失效边界不好划,键选错会**静默返回过期结果**(比慢更糟)—— 理由见 `DEC-006 §四` +- **🔧 顺带修掉一个反复踩中的陷阱**:`pytest.ini` 从**逐个文件名枚举**改为**自动收集** + (`testpaths = .` + `norecursedirs`)。本仓**第三次**撞上"新测试文件不加进 testpaths 就不被收集" + —— `pytest` 会**静默少跑**,看着绿其实没测。⛔ `norecursedirs` 必须含 `memory-system-venv` + (pytest 默认只认 "venv" 这个名字) - **`CLAUDE.md` 保鲜** —— 清掉 5 处已过时的警告(如"Ollama 未安装"、"7 个模块留着死 `PG_CONN`"、 "15s 超时待修"、"45 passed"),**过时的警告比没有更坏** @@ -140,6 +150,13 @@ - ✅ `git grep memory_pass_2026` **零命中** - ⚠️ **旧口令仍在公开 git 历史里** —— 改代码抹不掉历史,**要真正消除暴露必须轮换口令**(待办) +### 安全(续)· **旧口令已轮换失效**(2026-09-21) + +- `ALTER USER memory_user PASSWORD <新值>` + 更新 `.env`(不入库) +- **实测验证**:旧口令登录**被拒** ✓;新口令走代码正式路径可连 ✓ +- ⇒ **改代码抹不掉历史,唯一解是让历史里的值失效** —— 不是删历史,是让那个值没用 +- ⛔ 仍不得在任何真环境复用 `memory_pass_2026`(它在历史上仍是公开的) + ### 挂起(Blocked) diff --git a/CLAUDE.md b/CLAUDE.md index 0341c41..3a27d9e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -128,11 +128,15 @@ skill_candidate_store(候选 + 双阈值 0.85/0.65 检索) **新增表或新增落盘位置要自己在这里补一条**(文件里留了注释提示)。 - **删 Ledger 必须临时 `DISABLE TRIGGER ledger_append_only_trigger` 再恢复** —— 生产严禁。Append-Only 有测试真的断言了 UPDATE/DELETE 被拒(`test_day17:193+`)。 - ⚠️ 该断言**必须把 payload 包成 `Json()`**,否则 psycopg2 在参数适配阶段就报错、触发器根本没被触发 ⇒ **测试假绿**(`test_day17` 里有注释写明)。 -- **当前 58 用例** = `test_day17`(13,含 3×2 参数化) + `test_day18`(8) + `test_day19`(5) + `test_day20_kv_demotion`(11) + `test_day21_skill_generator_guard`(11) + `test_day22_embedding_contract`(4) + `test_day23_rag_conditional`(6)。 +- **当前 61 用例** = `test_day17`(13,含 3×2 参数化) + `test_day18`(8) + `test_day19`(5) + `test_day20_kv_demotion`(11) + `test_day21_skill_generator_guard`(11) + `test_day22_embedding_contract`(4) + `test_day23_rag_conditional`(6)。 ⚠️ `test_day18`/`test_day19` 共 13 个带 `requires_ollama` 标记(要 Ollama + bge-m3)。 **不起 Ollama 时**:`pytest -m "not requires_ollama"` → 45 个。 - **⛔ 改代码 / 提交前必须走红绿(TDD)** —— 见下 §7。 - ⚠️ **新加测试文件必须同时加进 `pytest.ini` 的 `testpaths`** —— 它是显式枚举的,不加就**不会被 `pytest` 收集**(第 1 轮新增的两个文件都加了)。 +- **`pytest.ini` 已改为自动收集**(`testpaths = .` + `norecursedirs`)—— + 新加 `test_*.py` 放仓根即被收,**不必再改 testpaths**。 + ⚠️ 这条改动修的是一个**反复踩中**的陷阱:枚举式 testpaths 下,新文件不加就**静默不跑**、看着绿其实没测 + (本仓撞过 3 次:day20 / day22 / day24)。⛔ 若你新加了目录,记得同步 `norecursedirs` + (**必须含 `memory-system-venv`** —— pytest 默认只认 "venv" 这个名字)。 - **新增用例要做反证**:用 git 取旧代码(`git stash push -- ` 或 `git show HEAD:`)确认用例**真的会红**,否则等于没测。 - `perf_baselines.json` 是 `test_day19` 的**追加式**产物,已 gitignore(本仓不存在,原目录有)。 @@ -156,8 +160,8 @@ skill_candidate_store(候选 + 双阈值 0.85/0.65 检索) |---|---| | ~~**A1**~~ | ✅ **已裁决:不接,明确标注未启用**(`DEC-004`)。docstring 已写「⛔ 未启用」+ 为什么 + 将来怎么启用;`ARCHITECTURE.md §11` 同步 | | ~~**E**~~ | ✅ 已处置(`DEC-005`):断言只保留**稳定成立**的关系;`Vector ✅ 第 2 轮已完成:**A3**(RAG 条件性判据)· **B1①②**(接线 + 删幻影形参)· 挂 CI · 文档计数校正 > ✅ 第 3 轮:**A1**(重排序:裁决为**不接**,标注未启用,见 DEC-004)· **E**(性能断言:**`Vector %s` + `ORDER BY cosine_distance LIMIT k` | + +⇒ 一次请求两次往返(且第二次要先把查询向量算出来,即 `_get_embedding` 夹在两次查询之间)。 + +## 二 · 关键核实:合并会不会丢掉"索引优化"? + +**直觉上会** —— 合并意味着"取回全部行再在 Python 里排",看起来放弃了数据库的 top-k 能力。 + +**但实测核实:不会**,因为**根本没有向量索引**可丢: + +``` +rag_knowledge_base 上的索引: + rag_knowledge_base_pkey PRIMARY KEY (knowledge_id) + idx_rag_kb_source btree (source) + idx_rag_kb_version btree (version) + ← content_embedding 上没有任何 hnsw / ivfflat 索引 +``` + +⇒ 原来那句 `ORDER BY cosine_distance LIMIT k` **本来就是全表扫描 + 排序**。 +合并成一次查询后,把同样的排序搬到 Python,**在规模上没有任何损失**。 + +> 📌 本条是本 DEC 的实质:**"合并会不会更慢"必须先看有没有索引可丢**, +> 不能凭"聚合查询更慢"的一般印象下判断。 + +## 三 · 决定 + +**合并为一次查询**:带上 `content_embedding <=> %s::vector AS cosine_distance` 取回全部行,然后: + +- `all_records`:全部行 → 喂 BM25(顺序不影响打分) +- `vector_results`:按**原始距离**升序取前 `limit*3` 条 + - ⚠️ **必须用原始距离排,不能用四舍五入后的 `similarity`** —— + 极近的距离会因取整而换序,那就不再等价于原 SQL 的 `ORDER BY cosine_distance` +- `_get_embedding(query)` 上移到唯一那次查询之前 + +**等价性**:结果集与排序均与原实现一致(原 SQL 排的就是同一个距离)。 + +## 四 · 有意**不做**:BM25 语料/索引的缓存 + +audit 还提到「`BM25Okapi(corpus)` 每次调用现建索引」。**本次不做**,理由: + +1. **合并后,语料本来就每次都要取回来**(BM25 要全量语料),省不掉那趟 IO; + 能省的只是 `BM25Okapi` 的构造与 jieba 分词。 +2. **缓存的失效边界不好划**:语料随 `add_external_knowledge` 变化, + 要么在写入端做失效(多一处耦合),要么按键(行数/最新时间)判缓存 —— + 键选错就会**静默返回过期检索结果**,那是比慢更糟的错。 +3. 当前数据量下**无感**(audit 自己也标了这一条为低优先)。 + +⇒ 按"**别留旋钮没人转**"的同一条纪律:**宁可先不做,也不留一个半正确的缓存**。 +若将来规模上来,正确做法是**在 `add_external_knowledge` 里显式失效**,并补一条 +"写入后检索必须看到新内容"的测试 —— 届时另开 DEC。 + +## 五 · 验收判据 + +- [x] **RED**:`test_search_uses_single_round_trip` 修复前 FAIL(实测 **2 次**往返) +- [x] **GREEN**:修复后 PASS(**1 次**) +- [x] **安全网**:`test_search_returns_relevant_row_first` / `test_search_respects_source_and_tenant_filter` + 在重构**前后都通过**(特征测试,锁住行为不变) +- [x] 全量 `pytest` 61 passed + +## 六 · 顺带修掉一个反复踩中的陷阱(`pytest.ini`) + +本次新增 `test_day24` 时**第三次**撞上「新文件不加进 `testpaths` 就不被收集」—— +`pytest` 会静默少跑,看着绿其实没测。已把 `pytest.ini` 从**逐个文件名枚举**改为**自动收集**: + +```ini +testpaths = . +norecursedirs = memory-system-venv data .git __pycache__ archive docs .github +``` + +⛔ `norecursedirs` 里**必须**写 `memory-system-venv` —— pytest 默认只认 "venv" 这个名字, +而本仓的 venv 叫 `memory-system-venv`(README 起的名),不排除就会把 site-packages 里的测试扫进来。 + +## 七 · 反悔成本 + +低。若将来加了向量索引(hnsw/ivfflat),则"取回全部行"会变得不划算 —— +届时应**退回两次查询**(让索引做 top-k),并更新本 DEC。 +判据同 §二:**先看索引,再决定查几次。** diff --git a/pytest.ini b/pytest.ini index 8c2e948..07d4628 100644 --- a/pytest.ini +++ b/pytest.ini @@ -1,10 +1,20 @@ [pytest] -testpaths = test_day17_deterministic_backtrack.py test_day18_evolution_conditional.py test_day19_performance_stability.py test_day20_kv_demotion.py test_day21_skill_generator_guard.py test_day22_embedding_contract.py test_day23_rag_conditional.py +# ⚠️ 2026-09-21 改成**自动收集**(原来是逐个文件名枚举)。 +# 原因:枚举式的 testpaths 有个反复踩中的陷阱 —— +# **新加的测试文件不加进来就不会被收集**,而 `pytest` 会静默少跑, +# 看着是绿的、其实没测(本仓 3 次撞上:day20/day22/day24)。 +# 改成 `.` + 显式排除目录后,新文件 `test_*.py` 放进仓根就自动被收。 +testpaths = . +norecursedirs = memory-system-venv data .git __pycache__ archive docs .github +# ↑ ⛔ 必须排除 memory-system-venv —— pytest 的默认 norecursedirs 只认"venv"这个名字, +# "memory-system-venv" 不在其中,会把 site-packages 里的测试文件一起扫进来。 +# (本仓 venv 目录名来自 README,见 CLAUDE.md §2) + addopts = -ra filterwarnings = ignore:.*NotOpenSSLWarning.* ignore:.*urllib3.* markers = - requires_ollama: 需要本地 Ollama + bge-m3 才能跑(CI 默认跳过) + requires_ollama: 需要本地 Ollama + bge-m3 才能跑 —— 用 `pytest -m "not requires_ollama"` 跳过,`pytest -m requires_ollama` 只跑这些。 - 见 .github/workflows/tests.yml(那个 job 设了 continue-on-error,因为它依赖 CPU 推理且含性能断言) + 见 .github/workflows/tests.yml(两个 job 都阻断,见 DEC-002 §七) diff --git a/rag_knowledge.py b/rag_knowledge.py index 6dd2e81..a2df929 100644 --- a/rag_knowledge.py +++ b/rag_knowledge.py @@ -159,32 +159,45 @@ def search_rag_knowledge(query: str, source: Optional[str] = None, limit: int = - tenant_id: 租户 ID,用于多租户隔离,默认 public 返回: 检索结果列表 + + ⚠️ 2026-09-21(audit D4):本函数此前**同一张表、同一过滤条件查两遍** + (一次取全部行喂 BM25 语料,一次取 top-k 算余弦距离)。现合并为**一次查询**: + 带上 `cosine_distance` 取回全部行,top-k 在 Python 里排。 + **不会损失索引优化** —— `content_embedding` 上没有任何向量索引 + (只有 pkey + 两个 btree),原来那句 `ORDER BY cosine_distance LIMIT k` 本来就是全表扫描 + 排序。 + 见 `docs/decisions决策/DEC-006-rag检索的往返次数-20260921.md` """ - # 获取外部知识库中的所有记录(或按 source 过滤) + # 查询向量先算 —— 下面那唯一一次查询要用它 + query_embedding = _get_embedding(query) + + # 唯一一次查询:取回该(租户[, 来源])下全部 active 记录,并顺带算出余弦距离 with get_cursor() as cur: if source: cur.execute( """ - SELECT knowledge_id, source, title, content, version, updated_at, metadata + SELECT knowledge_id, source, title, content, version, updated_at, metadata, + content_embedding <=> %s::vector AS cosine_distance FROM rag_knowledge_base WHERE status = 'active' AND tenant_id = %s AND source = %s """, - (tenant_id, source), + (query_embedding, tenant_id, source), ) else: cur.execute( """ - SELECT knowledge_id, source, title, content, version, updated_at, metadata + SELECT knowledge_id, source, title, content, version, updated_at, metadata, + content_embedding <=> %s::vector AS cosine_distance FROM rag_knowledge_base WHERE status = 'active' AND tenant_id = %s """, - (tenant_id,), + (query_embedding, tenant_id), ) rows = cur.fetchall() if not rows: return [] - # 构建临时向量检索结果和 BM25 检索结果 - # 注意:这里需要把外部知识库记录转换成与 vector_semantic 检索函数兼容的格式 + # 同一次结果同时喂两条检索链: + # · all_records —— BM25 的语料(**全部行**;顺序不影响 BM25 打分) + # · vector_results —— 向量侧只取距离最近的 limit*3 all_records = [] for row in rows: all_records.append({ @@ -197,47 +210,22 @@ def search_rag_knowledge(query: str, source: Optional[str] = None, limit: int = }, }) - # 向量检索:我们需要基于 content_embedding 计算,而不是重新 embedding 所有记录 - # 简单实现:临时构建一个向量结果,用 embedding 字段 - query_embedding = _get_embedding(query) - - vector_scores = [] - with get_cursor() as cur: - if source: - cur.execute( - """ - SELECT knowledge_id, source, title, content, version, updated_at, metadata, - content_embedding <=> %s::vector AS cosine_distance - FROM rag_knowledge_base WHERE status = 'active' AND tenant_id = %s AND source = %s - ORDER BY cosine_distance LIMIT %s - """, - (query_embedding, tenant_id, source, limit * 3), - ) - else: - cur.execute( - """ - SELECT knowledge_id, source, title, content, version, updated_at, metadata, - content_embedding <=> %s::vector AS cosine_distance - FROM rag_knowledge_base WHERE status = 'active' AND tenant_id = %s - ORDER BY cosine_distance LIMIT %s - """, - (query_embedding, tenant_id, limit * 3), - ) - rows = cur.fetchall() - - vector_results = [] - for row in rows: - similarity = 1.0 - float(row["cosine_distance"]) - vector_results.append({ + # 向量侧:与原 SQL `ORDER BY cosine_distance LIMIT limit*3` 严格等价 —— + # ⚠️ 必须按**原始距离**排序,不能用四舍五入后的 similarity(极近的距离会因取整换序) + nearest = sorted(rows, key=lambda r: float(r["cosine_distance"]))[: limit * 3] + vector_results = [ + { "id": row["knowledge_id"], "content": f"{row['title']}:{row['content']}", - "similarity": round(similarity, 4), + "similarity": round(1.0 - float(row["cosine_distance"]), 4), "metadata": { "source": row["source"], "version": row["version"], "updated_at": str(row["updated_at"]), }, - }) + } + for row in nearest + ] # BM25 检索 corpus = [_tokenize(r["content"]) for r in all_records] diff --git a/test_day24_rag_search_roundtrip.py b/test_day24_rag_search_roundtrip.py new file mode 100644 index 0000000..f617449 --- /dev/null +++ b/test_day24_rag_search_roundtrip.py @@ -0,0 +1,93 @@ +# 测试脚本: +# 覆盖 audit 的 D4 —— `search_rag_knowledge` 同一张表、同一过滤条件**查两遍**。 +# 裁决与理由见 docs/decisions决策/DEC-006-rag检索的往返次数-20260921.md +# +# 本文件依赖 Ollama embedding(add_external_knowledge 与检索都要算向量)⇒ 打 requires_ollama +import pytest + +import rag_knowledge +from rag_knowledge import add_external_knowledge, search_rag_knowledge + +pytestmark = pytest.mark.requires_ollama + +# ⚠️ source 必须以 `test-` 开头 —— conftest 的 clean_db 按 `source LIKE 'test-%'` 清理 +SRC = "test-d4-roundtrip" +TENANT = "public" + +DOCS = [ + ("机票改签规则", "起飞前 24 小时以上可免费改签一次;24 小时以内收取票面价 10% 的手续费。"), + ("酒店入住时间", "大部分酒店下午 14:00 后可办理入住,次日 12:00 前退房。"), + ("北京地铁票价", "北京地铁实行里程计价,起步价 3 元,最高 10 元。"), +] + + +@pytest.fixture +def seeded_corpus(): + """铺三条外部知识(带向量),供检索用""" + for title, content in DOCS: + add_external_knowledge( + source=SRC, title=title, content=content, version="v1.0.0", tenant_id=TENANT + ) + yield + + +# ==================== 一 · 结果特征(重构的安全网)==================== + +def test_search_returns_relevant_row_first(seeded_corpus): + """ + ⚠️ 这是**特征测试**(characterization)—— 它锁定"重构前就正确"的行为, + 目的是让下面那次重构**有安全网**:重构前后它都必须过。 + """ + results = search_rag_knowledge("改签要手续费吗", source=SRC, limit=3, tenant_id=TENANT) + + assert results, "应至少命中一条" + assert len(results) <= 3 + # 最相关的那条(改签规则)应排第一 + assert "改签" in results[0]["content"], f"排序异常,首条是:{results[0]['content'][:40]}" + # 每条都要带齐字段,且 metadata 与写入时一致 + # ⚠️ 返回的是 **RRF 融合后**的结构:`rrf_score`(不是 vector 那层的 `similarity`) + # —— 这条是我写测试时的假设错误,代码本身没错(见 rrf_fusion) + for r in results: + assert set(r) >= {"id", "content", "rrf_score", "metadata"} + assert isinstance(r["rrf_score"], float) + assert r["metadata"]["source"] == SRC + assert r["metadata"]["version"] == "v1.0.0" + + +def test_search_respects_source_and_tenant_filter(seeded_corpus): + """过滤条件必须生效:查别的 source 不该拿到本 source 的内容""" + other = search_rag_knowledge("改签要手续费吗", source="test-d4-nonexistent", limit=3, tenant_id=TENANT) + assert other == [] + + +# ==================== 二 · 往返次数(D4 本体)==================== + +def test_search_uses_single_round_trip(seeded_corpus, monkeypatch): + """ + ⚠️ D4:`search_rag_knowledge` 此前**同一张表、同一过滤条件查两遍** + (一次取全部行喂 BM25 语料,一次取 top-k 算余弦距离)⇒ 两次往返。 + + 这里**数真实调用次数**(包装真实的 get_cursor,不伪造结果): + · 修复前:2 次 ⇒ 本用例 FAIL(RED) + · 修复后:1 次 ⇒ PASS(GREEN) + + 依据:`rag_knowledge_base.content_embedding` 上**没有任何向量索引** + (只有 pkey + 两个 btree),所以原来那 `ORDER BY cosine_distance LIMIT k` + 本来就是全表扫描 + 排序 ⇒ 合并成一次查询**不会丢掉索引优化**。 + """ + calls = [] + real_get_cursor = rag_knowledge.get_cursor + + def counting_get_cursor(): + calls.append(1) + return real_get_cursor() + + monkeypatch.setattr(rag_knowledge, "get_cursor", counting_get_cursor) + + results = search_rag_knowledge("改签要手续费吗", source=SRC, limit=3, tenant_id=TENANT) + + assert results, "先确认这次调用真的命中了(否则数往返次数没意义)" + assert len(calls) == 1, ( + f"D4:search_rag_knowledge 应只查一次库,实际 {len(calls)} 次" + "(同一张表查两遍是待修项;若你是有意拆开的,请更新 DEC-006)" + )