# 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** —