Files

Multica PM Agent 343a5eebe3

Sync to Gitee / sync (push) Has been cancelled

Details

docs(rag): add MemoryBear RAG implementation docs v1.0

Submit the formed RAG documentation set produced across Sprint-1/2/3
(WS-12 through WS-26) under docs/rag/. Includes:

- README.md / INDEX.md: landing + total index (responsibility matrix,
  review verdicts, dual-link to source issues)
- overview/: full-pipeline architecture (4 .mmd diagrams),
  11-stage boundary contracts, doc map, source-code inventory
- pipeline/: 5 deep-dives (Loader/Parser/Chunking, Embedding,
  VDB & retrieval, GraphRAG, Rerank/Prompt/LLM)
- graphrag/, end-to-end/: v1.0 formal versions with full source
  retained as reference
- evolution/: 11 architecture-refactor proposals,
  6-direction roadmap, capability map
- review/: S3-T1 / S3-T2 final reviews, S2-T7 final summary
- _indexes/: glossary (81 terms), source->doc reverse index, chart index
- _release/: v1.0-RC1 release manifest, versioning convention,
  ops & freshness plan
- _meta/README.md: placeholder noting WS-12 governance assets gap

Aggregate review score 92.6/100 (8/8 PASS, 31/31 source-code spot
checks hit). The legacy docs/ ignore in .gitignore is narrowed to
docs/* with an explicit allowlist for docs/rag/.

Refs: WS-26
Co-authored-by: multica-agent <github@multica.ai>

2026-05-09 10:51:48 +08:00

7.1 KiB

Raw Blame History

name, description, type, sprint, task, reviewer, reviewed-at, target-doc, target-comment, target-attachment

name	description	type	sprint	task	reviewer	reviewed-at	target-doc	target-comment	target-attachment
S3-T1 终审报告 — RAG 代码架构改造建议	知识运营终审，对 S3-T1 交付物按 5 维评分卡评分；总分 96/100，PASS	review	3	T1	知识运营与治理专家	2026-05-08	docs/rag/evolution/architecture-refactor-suggestions.md	bc97a22c-709e-4c93-a360-f015bc41a2e6 / 2026-05-08T11:30:59Z	S3-T1-deliverable.md (33 KB)

[S3-T1] 终审报告：RAG 代码架构改造建议

决议：✅ PASS（综合 96/100，超过 80 通过线 + 0 触发一票否决项）。

1. 评分明细（按 S1-T1 评分卡）

维度	权重	得分	关键观察
准确性 (Accuracy)	25	25	11 条建议全部带源码引用（`file:line`），且引用风格统一；引用了 `chat_model.py:52`、`vector_base.py:9`、`embedding.py:9-78`、`embedding_model.py:14-65`、`graphrag/utils.py:115-134`、`elasticsearch_vector.py:55-63`、`workflow/nodes/knowledge/node.py:108-155, 195-263, 284, 327`、`naive.py:508-738`、`common/settings.py:24` 等关键节点；与 [S1-T3 源码盘点] / [S2-T2 Embedding] / [S2-T3 VDB] / [S2-T5 检索后处理] 的描述交叉一致。"`os.environ.get` 出现 58 次"等量化论断给出了 grep 口径，可被复核。
完整性 (Completeness)	25	25	11 条建议覆盖全部 5 个方向（模块化拆分 / 接口抽象 / 性能优化 / 可观测性 / 配置治理），实测分布：模块化 4 条、抽象 3 条、性能 3 条、可观测性 2 条、配置治理 2 条（含交叉归类）；2 套 PoC 代码草案（Retriever 协议 + Embedder 缓存装饰器）满足"≥2"硬要求；含完整改造路线图（短/中/长三阶段，每阶段带交付物清单与里程碑），含风险登记表。
时效性 (Timeliness)	15	13	锁定到 `feae2f2e` 工作分支提交（2026-05-08 当日），符合"frontmatter 锁定 source-commit"规范；未明确给出"代码与文档失效再校准节奏"，扣 2 分（建议在落地后随每次 release 同步刷新）。
可读性 (Readability)	15	14	一页摘要（3 优点 / 5 痛点）作为入口；每条建议遵循 "问题 → 方案 → 收益 → 成本/风险 → 优先级" 五段式；表格密度适中；优先级标签 P0/P1/P2 醒目；扣 1 分因 §3 路线图三阶段表格列宽稍紧、移动端阅读体验略差。
可执行性 (Actionability)	20	19	PoC-1 (Retriever Protocol) 含 50+ 行可运行级伪代码，PoC-2 (Embedder 缓存装饰器) 给出实施样例；每条建议带工作量估算（单位"人日"）+ 优先级 + 收益量化（如 "P95 下降 100-300ms"、"单测覆盖率 +30%"）；扣 1 分因部分量化收益（如"减少 60-90% 外部 API 调用"）依赖业内统计而非本仓基准，建议在路线图 §3.1 实施"baseline 立项"任务时配套测得。
总分	100	96	—

通过门槛：≥80。S3-T1 以 96 分通过终审。

2. 一票否决项排查

否决项	是否触发	证据
源码虚构	❌ 未触发	抽查 5 处源码引用全部可在 ±3 行内复现：`node.py:327` 的 `print` 残留断言（建议复核合并）、`elasticsearch_vector.py:55-63 add_chunks` 路径无缓存断言（与 S2-T2 一致）、`init_settings()` 模块级副作用断言（与 S1-T3 §3 调用链路一致）、`chat_model.py:52 Base` 抽象类（与 S2-T5 §3.1 一致）、`naive.py:508 chunk()` 11 个 if/elif 断言（与 S2-T1 §4 一致）。
核心章节缺失	❌ 未触发	验收标准 6 项全部覆盖：现状评估、≥8 条建议、PoC、路线图、风险、Checklist。
安全风险描述	❌ 未触发	建议 7 中明确把 API key / DB 密码升级到 `pydantic.SecretStr` 与 Vault；建议 4 提到 cache 失败优雅降级；隐私边界（建议 8 中提到 Singleton 单例与多 worker 隔离）有论及。
架构严重脱节	❌ 未触发	抽象层与 [S1-T2] 架构图同源；3 个 Protocol 命名（Retriever / Reranker / Generator）与 LangChain Runnable 风格匹配；与 [S3-T2] 路线图引用的"4 个 Protocol 落地"约定一致。

3. Must-Fix（必改项）

无。所有问题为建议级（Should/Could）。

4. Should-Fix（建议落地前修补）

#	建议	责任	处理方式
SF-1	§3.1 短期路线图工作项 #1（删除 `node.py:327 print()`）应在 v1.0 正式发布前以独立 hot-fix PR 落地，避免成为 v1.0 文档同步描述但代码未修的"知行不一致"案例。	AI 知识库专家 / Python 工程师	进入 [S3-T4] PM 复盘的"近 1 个月迭代主题"清单
SF-2	§0.2 痛点 4 提到 `KnowledgeRetrievalNode.get_reranker_model()` 每次 rerank 都查 DB，建议补一个"实测 5-20ms × QPS"的基准点，便于落地后量化收益。	AI 知识库专家	落地建议 #3 时同步采集；纳入 D5 评估埋点（[S3-T2] D5）
SF-3	§1 建议 1 中"`OpenAIEmbed` 等遗留类实现 `Embedder`（保留 `encode/encode_queries` 兼容期 6 个月）" — 建议明确"6 个月"与 release cadence 的对齐方式（按 v0.x 还是按月）。	AI 知识库专家	在迁移启动前发一份 Deprecation Policy（参考 docs/rag/_meta/review-sop.md）

5. Could-Fix（可选优化）

#	建议
CF-1	§3.3 长期路线图工作项 #13（引入 Milvus 验证 BaseVector 可插拔）— 可在 [S3-T2] D2 SPLADE 接入后再评估，避免双轴改造同时进行带来的回归风险。
CF-2	可补一份"建议 # × 优先级 × 工作量"的散点图，方便产品排期与会做"可视化拍板"。
CF-3	§0.1 优点 2 里 "7 类 provider" 与 §0.2 痛点 1 里 "10+ Provider" 表述略冲突；建议统一口径（实测 7 类活跃 provider + 多个适配器）。

6. 与 Sprint 文档生态的兼容性

✅ 与 [S1-T3 源码盘点] 一致：os.environ.get 58 次、logger 355 次等量化数据可在 [S1-T3] §三入口链路梳理中交叉印证；"rag_utils vs rag/utils 命名冲突"作为遗留问题在 [S1-T3] §4.1 已识别。
✅ 与 [S2-T2 Embedding] 一致：建议 1（双轨 Embedding）问题陈述与 [S2-T2] §1.1 / §1.2 对"两条调用路径"的论述完全一致。
✅ 与 [S2-T5 检索后处理] 一致：建议 3（三处 rerank）的位置与 [S2-T5] §1.2 三种 rerank 方案一一对应。
✅ 与 [S3-T2 后续路线图] 一致：建议 2 落地的 4 个 Protocol 是 [S3-T2] 全部 6 个方向的接口注入点，命名一致。

7. 终审结论与下一步

决议项	内容
总分	96 / 100
决议	✅ PASS（终审通过）
建议落入版本	`MemoryBear RAG Docs v1.0`（落入 `docs/rag/evolution/architecture-refactor-suggestions.md`）
状态变更建议	由 `in_review` → `done`，由 PM 执行
后续衔接	(1) 与 [S3-T2] 联合作为 Sprint-3 出口物；(2) Should-Fix 项进入 [S3-T4] PM 复盘清单；(3) Sprint-2 文档若 [S2-T7] 评审引入新事实，本文档以增量补丁形式更新（不重写）。

— END —

7.1 KiB Raw Blame History Unescape Escape