adai/MemoryBear
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(rag): add MemoryBear RAG implementation docs v1.0
Some checks failed
Sync to Gitee / sync (push) Has been cancelled
Details

Browse Source 
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>
This commit is contained in:
Multica PM Agent
2026-05-09 10:51:48 +08:00
parent feae2f2e1e
commit 343a5eebe3
33 changed files with 8410 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

158
docs/rag/README.md Normal file
View File

@@ -0,0 +1,158 @@
# MemoryBear RAG 实现文档全集 v1.0-RC1
> **版本**：v1.0-RC1（Release Candidate 1）
> **冻结日期**：2026-05-08
> **基线源码**：MemoryBear `agent/ai/f8de881a` 分支（基于 commit `feae2f2e`）
> **目标读者**：MemoryBear 平台开发者、RAG 架构师、运维与 SRE、产品需求分析师、二次开发者
> **维护责任人**：知识运营与治理专家
> **关联仓库**：https://github.com/LuyaoCoding/MemoryBear
---
## 这本书在讲什么
MemoryBear 把"非结构化资料 → 可被对话/Agent 检索消费的知识"这条 RAG 链路完整跑通了：从 Web/飞书/语雀/本地 11 类格式的解析、Chunking、Embedding、Elasticsearch 8.x 上的 Hybrid 向量+全文混合索引、Microsoft GraphRAG（general）与 LightRAG（light）双轨知识图谱、Reranker 三路实现、流式 LLM 调用、引用回填，到对话内存与 RAG 协同的产品差异化设计。
本文档全集是上述链路的**「源码级实现说明 + 架构改造路线 + 后续迭代蓝图」**。所有结论都锚定到具体的源码位置（`path:line`），不允许凭空虚构。
> **当前状态**：**Release Candidate 1（候选发布）**。S3-T1（架构改造建议）与 S3-T2（迭代功能路线图）已通过知识运营终审；Sprint-2 部分文档（S2-T4 GraphRAG、S2-T6 E2E、S2-T7 收口评审）尚未交付，对应章节为占位说明。完整 v1.0 在 S2 收口评审通过后发布。详见 [`_release/release-manifest-v1.0-RC1.md`](_release/release-manifest-v1.0-RC1.md)。
---
## 三套阅读路径
不同角色读法不同。从你最关心的入口起：
### 🟢 路径 A · 新手 5 分钟（产品 / 业务 / 新人）
| 步骤 | 文件 | 看什么 |
|---|---|---|
| 1 | 本文 §"这本书在讲什么" | 一句话理解 RAG 链路边界 |
| 2 | [`overview/01-architecture.mmd`](overview/01-architecture.mmd) | 全链路架构图（Mermaid） |
| 3 | [`evolution/future-extensions-roadmap.md`](evolution/future-extensions-roadmap.md) §"现状速览与设计基线" | 三色标注的能力地图（已有 / 可上 / 愿景） |
| 4 | [`_indexes/glossary.md`](_indexes/glossary.md) | 关键术语（Chunk / Embedder / Hybrid / GraphRAG / Reranker） |
**预期效果**：你能用一张图讲清 MemoryBear RAG 现在能做什么，未来 6 个月在做什么。
### 🟡 路径 B · 工程师 30 分钟（开发者 / 二次开发 / 运维）
| 步骤 | 文件 | 看什么 |
|---|---|---|
| 1 | 本文 §"全部目录树" | 代码模块对应到哪些文档 |
| 2 | [`overview/source-inventory.md`](overview/source-inventory.md)（来自 S1-T3） | 24,895 LOC 的模块清单 + 依赖图 + Gap 报告 |
| 3 | [`pipeline/01-loader-parser-chunking.md`](pipeline/01-loader-parser-chunking.md)（S2-T1） | Loader / Parser / Chunking 实现详解（11 类格式解析） |
| 4 | [`pipeline/02-embedding.md`](pipeline/02-embedding.md)（S2-T2） | Embedding 双轨（RedBearEmbeddings vs 遗留层），含 10+ Provider 速查 |
| 5 | [`pipeline/03-vdb-and-retrieval.md`](pipeline/03-vdb-and-retrieval.md)（S2-T3） | Elasticsearch 8.x 选型、HNSW、Hybrid 检索（BM25 + 向量），含 SPLADE 接入预埋 |
| 6 | [`pipeline/05-reranking-prompt-llm.md`](pipeline/05-reranking-prompt-llm.md)（S2-T5） | 三路 Rerank、Prompt 工厂、流式 LLM、引用回填 |
| 7 | [`overview/boundaries.md`](overview/boundaries.md)（S1-T2 §boundaries） | 11 个 RAG 阶段的输入/输出/接口契约 |
| 8 | [`_indexes/file-index.md`](_indexes/file-index.md) | 反查：从源码模块倒查到对应文档章节 |
**预期效果**：你能定位"我要改 Embedding，要碰哪些代码、要看哪些文档"。
### 🟣 路径 C · 架构师 1 小时（技术决策 / 架构演进 / 投入决策）
| 步骤 | 文件 | 看什么 |
|---|---|---|
| 1 | 路径 B 全套（先打底） | — |
| 2 | [`overview/source-inventory.md`](overview/source-inventory.md) §四 Gap 报告 | 14 项"代码 vs 架构"差异 |
| 3 | [`evolution/architecture-refactor-suggestions.md`](evolution/architecture-refactor-suggestions.md)（S3-T1） | 11 条改造建议 + 2 套 PoC + 短/中/长三段路线图 |
| 4 | [`evolution/future-extensions-roadmap.md`](evolution/future-extensions-roadmap.md)（S3-T2） | 6 个扩展方向（多模态 / 混合搜索 / KG / 对话记忆 / 评估闭环 / 自适应路由） |
| 5 | [`evolution/capability-map.mmd`](evolution/capability-map.mmd) | 能力地图：现状 vs 短期 vs 长期 |
| 6 | [`review/S3-T1-final-review.md`](review/S3-T1-final-review.md) + [`review/S3-T2-final-review.md`](review/S3-T2-final-review.md) | 知识运营终审报告（评分 / Should-Fix / 兼容性核对） |
| 7 | [`_release/ops-and-freshness-plan.md`](_release/ops-and-freshness-plan.md) | 版本演进、保鲜与失效策略 |
**预期效果**：你能为下一季度 RAG 投入排序，给出"先做什么 / 缓做什么 / 不做什么"的判断依据。
---
## 全部目录树
```
docs/rag/
├── README.md # ← 你在这里
├── INDEX.md # 完整文件清单 + 责任矩阵
├── _meta/ # 治理资产（S1-T1）
│ ├── README.md # 治理体系总览（含 8 环节 → 代码目录速查）
│ ├── document-template.md # 统一文档模板（9 大章节）
│ ├── scoring-rubric.md # 5 维度评分卡（满分 100，通过线 80）
│ ├── review-sop.md # 审校流程：作者自检 → 同行 → 终审
│ ├── directory-naming-spec.md # 目录与命名规范、frontmatter
│ └── rubric-scoresheet.md # Sprint-2 评分记录表
├── overview/ # 总览（S1-T2 + S1-T3）
│ ├── 01-architecture.mmd # 全链路架构图（Mermaid）
│ ├── 02-indexing-pipeline.mmd # 文档入库时序图
│ ├── 03-query-pipeline.mmd # 在线检索时序图
│ ├── 04-graphrag-indexing.mmd # GraphRAG 索引时序图（light/general）
│ ├── boundaries.md # 11 个 RAG 阶段边界定义
│ ├── DocMap.md # Sprint-2 41 篇文档目录大纲
│ └── source-inventory.md # 源码盘点 + 模块依赖图谱（S1-T3）
├── pipeline/ # 各环节深度文档（S2-T1 ~ T5）
│ ├── 01-loader-parser-chunking.md # S2-T1：11 类格式 + 8 种 Chunking 策略
│ ├── 02-embedding.md # S2-T2：10+ Provider + 多模态
│ ├── 03-vdb-and-retrieval.md # S2-T3：ES 8.x + HNSW + Hybrid
│ ├── 04-graphrag.md # S2-T4：GraphRAG light + general（待交付，占位）
│ └── 05-reranking-prompt-llm.md # S2-T5：Rerank/Prompt/LLM/引用回填
├── graphrag/ # GraphRAG 专章（合并自 pipeline/04）
│ └── README.md # 占位：S2-T4 完成后并入
├── end-to-end/ # 端到端调用链（S2-T6，待交付）
│ └── README.md # 占位：依赖 S2-T1~T5 全部完成
├── evolution/ # 架构演进（S3-T1 + S3-T2）
│ ├── architecture-refactor-suggestions.md # S3-T1：11 条改造建议 + 路线图
│ ├── future-extensions-roadmap.md # S3-T2：6 个扩展方向
│ └── capability-map.mmd # 能力地图（已有 / 可上 / 愿景）
├── review/ # 评审报告归档
│ ├── S3-T1-final-review.md # S3-T1 终审报告（96/100 通过）
│ ├── S3-T2-final-review.md # S3-T2 终审报告（95/100 通过）
│ ├── S2-T7-pending.md # Sprint-2 评审收口（占位，未启动）
│ └── README.md # 评审历史索引
├── _indexes/ # 跨文档索引
│ ├── glossary.md # 关键术语表（合并所有 Sprint）
│ ├── file-index.md # 源码模块 → 文档反查
│ └── chart-index.md # 所有 Mermaid 图集中清单
└── _release/ # 发布与运营
├── release-manifest-v1.0-RC1.md # 发布候选清单（仓库 PR / Wiki / 版本约定）
├── versioning-convention.md # 版本号约定（语义化 + 锁源码 commit）
└── ops-and-freshness-plan.md # 运营与保鲜计划
```
> **未交付占位说明**：`pipeline/04-graphrag.md`、`end-to-end/`、`review/S2-T7-pending.md` 三处为占位，正文位于关联子任务的评论中（[WS-18](mention://issue/16bdb196-e10e-489b-b01c-9067b1f1bb23) / [WS-20](mention://issue/a3deeaa1-5b30-4da5-b4af-1b081f7f6394) / [WS-21](mention://issue/41f2482b-6f3e-4253-95f7-3e22e790f31c)）。完整 v1.0 在 S2-T7 评审通过后发布，参见 `_release/release-manifest-v1.0-RC1.md`。
---
## 与代码的对应关系（速查）
| RAG 环节 | 代码目录 | 对应文档 |
|---|---|---|
| 文档加载（Web / 飞书 / 语雀 / 本地） | `api/app/core/rag/{crawler,integrations}` | [`pipeline/01-loader-parser-chunking.md`](pipeline/01-loader-parser-chunking.md) |
| 多格式解析 + OCR + 版面识别 | `api/app/core/rag/{deepdoc/{parser,vision},app/naive.py}` | 同上 |
| Chunking + Tokenization | `api/app/core/rag/{nlp,common/token_utils.py}` | 同上 |
| Embedding（双轨） | `api/app/core/{models/embedding.py, rag/llm/embedding_model.py}` | [`pipeline/02-embedding.md`](pipeline/02-embedding.md) |
| Vector DB + 索引 | `api/app/core/rag/vdb/elasticsearch/` | [`pipeline/03-vdb-and-retrieval.md`](pipeline/03-vdb-and-retrieval.md) |
| BM25 + 向量混合检索 | `api/app/core/rag/{nlp/search.py, vdb/elasticsearch}` | 同上 |
| Knowledge Graph（GraphRAG） | `api/app/core/rag/graphrag/{light,general}` | [`pipeline/04-graphrag.md`](pipeline/04-graphrag.md)（占位） |
| Reranking（三路实现） | `api/app/core/{models/rerank.py, workflow/nodes/knowledge/node.py, rag/nlp/search.py}` | [`pipeline/05-reranking-prompt-llm.md`](pipeline/05-reranking-prompt-llm.md) |
| Prompt 工厂 + 模板 | `api/app/core/rag/prompts/` | 同上 |
| LLM 调用（流式 + 工具） | `api/app/core/{rag/llm/chat_model.py, agent/langchain_agent.py}` | 同上 |
| 引用回填 | `api/app/core/rag/nlp/search.py` (`Dealer.insert_citations`) | 同上 |
| Workflow Knowledge 节点 | `api/app/core/workflow/nodes/knowledge/` | [`pipeline/05-reranking-prompt-llm.md`](pipeline/05-reranking-prompt-llm.md) §3.4 |
> 详细的"源码 → 文档章节"反查请见 [`_indexes/file-index.md`](_indexes/file-index.md)。
---
## 文档治理与如何贡献
- **质量标准**：所有文档遵循 [`_meta/document-template.md`](_meta/document-template.md) 模板与 [`_meta/scoring-rubric.md`](_meta/scoring-rubric.md) 5 维评分（≥80 通过）。
- **审校流程**：作者自检（30min）→ 同行评审（48h）→ 知识运营终审（24h），见 [`_meta/review-sop.md`](_meta/review-sop.md)。
- **保鲜节奏**：每个 MemoryBear release 同步评审；超过 2 个 release 未更新触发自动归档复审，见 [`_release/ops-and-freshness-plan.md`](_release/ops-and-freshness-plan.md)。
- **版本号**：遵循语义化版本（v1.0 / v1.1 / v2.0），并在 frontmatter 锁定 `source-commit` SHA。详见 [`_release/versioning-convention.md`](_release/versioning-convention.md)。
---
## 反馈与勘误
- 发现源码引用与代码不符：在对应子任务（[WS-12 ~ WS-25](mention://issue/6c0b5472-a0fa-4997-925c-a67f235f82da)）评论中标注，由责任专家修订。
- 内容缺漏 / 阅读路径建议：在 [WS-24](mention://issue/a07f108d-06ee-41b8-8b57-22455f60ddeb) 评论中提交，由知识运营专家整理进下次保鲜窗口。
- 安全 / 隐私 / 合规问题：请直接联系工作空间负责人，不要在公开 issue 中详细描述。
— **MemoryBear RAG Docs · v1.0-RC1 · 2026-05-08** —