MemoryBear/docs/rag/README.md

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。

---

三套阅读路径

不同角色读法不同。从你最关心的入口起：

🟢 路径 A · 新手 5 分钟（产品 / 业务 / 新人）

步骤	文件	看什么
1	本文 §"这本书在讲什么"	一句话理解 RAG 链路边界
2	overview/01-architecture.mmd	全链路架构图（Mermaid）
3	evolution/future-extensions-roadmap.md §"现状速览与设计基线"	三色标注的能力地图（已有 / 可上 / 愿景）
4	_indexes/glossary.md	关键术语（Chunk / Embedder / Hybrid / GraphRAG / Reranker）

预期效果：你能用一张图讲清 MemoryBear RAG 现在能做什么，未来 6 个月在做什么。

🟡 路径 B · 工程师 30 分钟（开发者 / 二次开发 / 运维）

步骤	文件	看什么
1	本文 §"全部目录树"	代码模块对应到哪些文档
2	overview/source-inventory.md（来自 S1-T3）	24,895 LOC 的模块清单 + 依赖图 + Gap 报告
3	pipeline/01-loader-parser-chunking.md（S2-T1）	Loader / Parser / Chunking 实现详解（11 类格式解析）
4	pipeline/02-embedding.md（S2-T2）	Embedding 双轨（RedBearEmbeddings vs 遗留层），含 10+ Provider 速查
5	pipeline/03-vdb-and-retrieval.md（S2-T3）	Elasticsearch 8.x 选型、HNSW、Hybrid 检索（BM25 + 向量），含 SPLADE 接入预埋
6	pipeline/05-reranking-prompt-llm.md（S2-T5）	三路 Rerank、Prompt 工厂、流式 LLM、引用回填
7	overview/boundaries.md（S1-T2 §boundaries）	11 个 RAG 阶段的输入/输出/接口契约
8	_indexes/file-index.md	反查：从源码模块倒查到对应文档章节

预期效果：你能定位"我要改 Embedding，要碰哪些代码、要看哪些文档"。

🟣 路径 C · 架构师 1 小时（技术决策 / 架构演进 / 投入决策）

步骤	文件	看什么
1	路径 B 全套（先打底）	—
2	overview/source-inventory.md §四 Gap 报告	14 项"代码 vs 架构"差异
3	evolution/architecture-refactor-suggestions.md（S3-T1）	11 条改造建议 + 2 套 PoC + 短/中/长三段路线图
4	evolution/future-extensions-roadmap.md（S3-T2）	6 个扩展方向（多模态 / 混合搜索 / KG / 对话记忆 / 评估闭环 / 自适应路由）
5	evolution/capability-map.mmd	能力地图：现状 vs 短期 vs 长期
6	review/S3-T1-final-review.md + review/S3-T2-final-review.md	知识运营终审报告（评分 / Should-Fix / 兼容性核对）
7	_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 / WS-20 / WS-21）。完整 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
多格式解析 + 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
Vector DB + 索引	api/app/core/rag/vdb/elasticsearch/	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（占位）
Reranking（三路实现）	api/app/core/{models/rerank.py, workflow/nodes/knowledge/node.py, rag/nlp/search.py}	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 §3.4

详细的"源码 → 文档章节"反查请见 _indexes/file-index.md。

---

文档治理与如何贡献

• 质量标准：所有文档遵循 _meta/document-template.md 模板与 _meta/scoring-rubric.md 5 维评分（≥80 通过）。
• 审校流程：作者自检（30min）→ 同行评审（48h）→ 知识运营终审（24h），见 _meta/review-sop.md。
• 保鲜节奏：每个 MemoryBear release 同步评审；超过 2 个 release 未更新触发自动归档复审，见 _release/ops-and-freshness-plan.md。
• 版本号：遵循语义化版本（v1.0 / v1.1 / v2.0），并在 frontmatter 锁定 source-commit SHA。详见 _release/versioning-convention.md。

---

反馈与勘误

• 发现源码引用与代码不符：在对应子任务（WS-12 ~ WS-25）评论中标注，由责任专家修订。
• 内容缺漏 / 阅读路径建议：在 WS-24 评论中提交，由知识运营专家整理进下次保鲜窗口。
• 安全 / 隐私 / 合规问题：请直接联系工作空间负责人，不要在公开 issue 中详细描述。

— MemoryBear RAG Docs · v1.0-RC1 · 2026-05-08 —