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
parent feae2f2e1e
commit 343a5eebe3
33 changed files with 8410 additions and 1 deletions
--- a/docs/rag/overview/DocMap.md
+++ b/docs/rag/overview/DocMap.md
@@ -0,0 +1,194 @@
+# DocMap — MemoryBear RAG 文档目录大纲
+
+> **定位**：Sprint-2 深度文档化的任务拆解输入。每行 = 一篇待写文档，标题格式与 [S1-T1] 统一模板兼容。
+> **责任人草拟**：基于当前 Sprint-1 分工建议，实际分配由项目经理确认。
+> **目录结构**：`docs/rag/<stage>/<topic>.md`
+
+---
+
+## 文档目录总览
+
+```
+docs/rag/
+├── _meta/                          # [S1-T1] 模板与评分卡（由 @知识运营与治理专家 维护）
+├── 01-loader/
+│   ├── 01-web-crawler.md           # Web 爬虫：URL 发现、内容提取、速率控制
+│   ├── 02-feishu-integration.md    # 飞书集成：API 调用、鉴权、文档导出
+│   ├── 03-yuque-integration.md     # 语雀集成：知识库同步、文档下载
+│   └── 04-file-upload.md           # 文件上传与预处理（本地文件系统、NFS 兼容）
+├── 02-parser/
+│   ├── 01-pdf-parser.md            # PDF 解析：OCR + Layout + Table 流水线
+│   ├── 02-docx-parser.md           # DOCX 解析：段落提取、图片嵌入
+│   ├── 03-html-md-parser.md        # HTML / Markdown / TXT 解析
+│   ├── 04-excel-parser.md          # Excel 解析：行列转表格结构
+│   └── 05-vision-pipeline.md       # 视觉模块：OCR、布局识别、表格结构识别
+├── 03-chunking/
+│   ├── 01-chunking-strategies.md   # 分块策略全景：naive_merge、层级分块、树分块
+│   ├── 02-task-type-adapters.md    # 文档类型适配器：book / paper / laws / qa / one
+│   ├── 03-tokenizer.md             # RagTokenizer：中文分词、英文处理、fine_grained
+│   └── 04-multimodal-chunking.md   # 多模态分块：图片 VLM 描述、音频转文本
+├── 04-embedding/
+│   ├── 01-embedding-model-arch.md  # Embedding 模型架构：Base 接口 + 10+ Provider
+│   ├── 02-provider-guide.md        # Provider 接入指南：OpenAI / HuggingFace / 国产模型
+│   └── 03-auto-questions.md        # 自动问题生成：并发策略、LLM 缓存
+├── 05-vdb/
+│   ├── 01-elasticsearch-schema.md  # ES 索引 Schema：字段定义、mapping、analyzer
+│   ├── 02-hybrid-search.md         # 混合检索：BM25 + Vector 加权融合
+│   └── 03-storage-connections.md   # 存储连接层：ES、Redis、DocStore
+├── 06-graphrag/
+│   ├── 01-graphrag-overview.md     # GraphRAG 总览：Light vs General 对比
+│   ├── 02-entity-relation-extraction.md  # 实体关系抽取：Extractor 流程、Prompt 工程
+│   ├── 03-graph-merge-and-rank.md  # 图合并与 PageRank：子图合并、实体消歧
+│   ├── 04-community-reports.md     # 社区报告：Leiden 聚类、LLM 报告生成（General only）
+│   └── 05-knowledge-graph-search.md # KG 检索：Query 分析、实体匹配、N-hop 扩展
+├── 07-retrieval/
+│   ├── 01-retrieval-api.md         # 检索 API：knowledge_retrieval()、Dealer.search()
+│   ├── 02-query-understanding.md   # Query 理解：关键词提取、同义词扩展
+│   └── 03-multi-kb-retrieval.md    # 多知识库检索：结果合并、去重策略
+├── 08-reranking/
+│   ├── 01-rerank-architecture.md   # 重排序架构：内置评分 vs 外部 Rerank 模型
+│   └── 02-rerank-providers.md      # Rerank Provider：Jina / DashScope / Xinference
+├── 09-prompt/
+│   ├── 01-prompt-system.md         # Prompt 模板系统：template.py + generator.py
+│   ├── 02-citation-prompts.md      # 引用标注 Prompt：citation_prompt / citation_plus
+│   └── 03-toc-prompts.md           # 目录相关 Prompt：TOC 检测、提取、相关性
+├── 10-llm/
+│   ├── 01-llm-chat-model.md        # Chat 模型架构：Base.chat() / chat_streamly()
+│   ├── 02-llm-providers.md         # Chat Provider 全景：OpenAI / Azure / 国产模型
+│   └── 03-vision-model.md          # 视觉模型：VLM 描述、图片理解
+├── 11-e2e/
+│   ├── 01-indexing-pipeline.md     # 端到端入库流程：Celery 任务链、错误处理、进度追踪
+│   ├── 02-query-pipeline.md        # 端到端检索流程：Workflow Node → 检索 → 生成
+│   └── 03-answer-postprocess.md    # 回答后处理：引用插入、缓存、流式输出
+└── 12-architecture-evolution/
+    ├── 01-modularization-roadmap.md  # 模块化拆分建议
+    ├── 02-performance-optimization.md # 性能优化方向
+    └── 03-future-extensions.md       # 未来扩展：多模态检索、混合搜索、对话记忆
+```
+
+---
+
+## 文档详细定义
+
+### 01-loader
+
+| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
+|------|------|----------|-------------|-----------|------|
+| 01-01 | Web 爬虫 | **写**：URL 规范化、robots.txt 检查、速率限制、HTTP 抓取、内容提取、去重策略。**不写**：搜索引擎索引、分布式爬虫、JS 渲染。 | `crawler/web_crawler.py`, `crawler/http_fetcher.py`, `crawler/content_extractor.py`, `crawler/rate_limiter.py`, `crawler/robots_parser.py` | Python 工程师 | 需覆盖 CrawledDocument 数据结构 |
+| 01-02 | 飞书集成 | **写**：App 鉴权、文件夹遍历、文档导出（PDF/DOCX/Sheet）、异步轮询下载。**不写**：飞书审批流、机器人消息推送。 | `integrations/feishu/client.py`, `integrations/feishu/retry.py`, `integrations/feishu/models.py` | Python 工程师 | 需说明 `_export_file` vs `_download_file` 区别 |
+| 01-03 | 语雀集成 | **写**：个人 Token 鉴权、知识库遍历、文档详情获取、多种格式下载（MD/HTML/Excel）。**不写**：语雀协作编辑、版本管理。 | `integrations/yuque/client.py`, `integrations/yuque/retry.py`, `integrations/yuque/models.py` | Python 工程师 | lakesheet 解压逻辑需重点说明 |
+| 01-04 | 文件上传 | **写**：文件上传接口、NFS 同步等待、binary 读取策略、进度追踪。**不写**：CDN 分发、大文件分片上传。 | `controllers/document_controller.py`, `utils/file_utils.py`, `tasks.py:213` | Python 工程师 | 30s NFS 等待逻辑是 MemoryBear 特有 |
+
+### 02-parser
+
+| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
+|------|------|----------|-------------|-----------|------|
+| 02-01 | PDF 解析 | **写**：PDF 渲染、OCR 文本检测、布局分类、表格结构识别、文本合并策略。**不写**：PDF 生成/编辑、数字签名验证。 | `deepdoc/parser/pdf_parser.py`, `deepdoc/vision/ocr.py`, `deepdoc/vision/layout_recognizer.py`, `deepdoc/vision/table_structure_recognizer.py` | Python 工程师 | 核心中的核心，需重点投入 |
+| 02-02 | DOCX 解析 | **写**：段落提取、图片提取、超链接提取、OLE 嵌入文件。**不写**：DOCX 生成、样式渲染。 | `deepdoc/parser/docx_parser.py`, `utils/file_utils.py:extract_embed_file` | Python 工程师 | 需与 `app/naive.py` 的 vision_figure_parser 联动说明 |
+| 02-03 | HTML/MD/TXT 解析 | **写**：HTML 标签清洗、Markdown 结构化解析、纯文本处理。**不写**：CSS 样式解析、JS 执行。 | `deepdoc/parser/html_parser.py`, `deepdoc/parser/markdown_parser.py`, `deepdoc/parser/txt_parser.py` | Python 工程师 | 合并为一篇即可 |
+| 02-04 | Excel 解析 | **写**：行列读取、Sheet 遍历、表头检测、Markdown 表格转换。**不写**：公式计算、图表提取。 | `deepdoc/parser/excel_parser.py` | Python 工程师 | 轻量 |
+| 02-05 | 视觉流水线 | **写**：OCR 模型（ONNXRuntime）、布局识别模型、表格结构模型、图像预处理。**不写**：模型训练、模型量化。 | `deepdoc/vision/*.py` | Python 工程师 | 含模型加载、推理、后处理 |
+
+### 03-chunking
+
+| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
+|------|------|----------|-------------|-----------|------|
+| 03-01 | 分块策略全景 | **写**：naive_merge、naive_merge_with_images、hierarchical_merge、tree_merge 的实现与选择策略。**不写**：通用 NLP 分词算法原理。 | `nlp/__init__.py:562+`, `nlp/rag_tokenizer.py` | Python 工程师 | 需附决策树：何时用哪种策略 |
+| 03-02 | 文档类型适配器 | **写**：book/paper/manual/laws/qa/one/picture/audio 各自的分块逻辑、数据结构差异。**不写**：业务场景适配（如医疗/法律专有分块）。 | `app/naive.py:508`, `app/book.py`, `app/paper.py`, `app/manual.py`, `app/laws.py`, `app/qa.py`, `app/one.py`, `app/picture.py`, `app/audio.py` | Python 工程师 | 核心章节，需逐一说明 |
+| 03-03 | RagTokenizer | **写**：中文分词（Huqie/datrie）、英文处理（nltk/Porter/WordNet）、fine_grained_tokenize、分词对检索的影响。**不写**：分词算法数学推导。 | `nlp/rag_tokenizer.py` | Python 工程师 | 与 ES ik_max_word 的对比 |
+| 03-04 | 多模态分块 | **写**：图片 VLM 描述调用链、音频 sequence2txt 转录、视频处理（如有）。**不写**：VLM/ASR 模型内部原理。 | `app/picture.py`, `app/audio.py`, `llm/cv_model.py`, `llm/sequence2txt_model.py`, `deepdoc/parser/figure_parser.py` | Python 工程师 | 需说明 vision_model 注入机制 |
+
+### 04-embedding
+
+| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
+|------|------|----------|-------------|-----------|------|
+| 04-01 | Embedding 模型架构 | **写**：Base.encode() 接口、批次处理、Token 截断（8000/2048）、返回格式。**不写**：Embedding 模型原理（Word2Vec/BERT 等）。 | `llm/embedding_model.py` | Python 工程师 | 重点讲接口契约 |
+| 04-02 | Provider 接入指南 | **写**：10+ Provider 的配置方式、API Key 管理、Base URL 设置、批次大小差异。**不写**：各厂商 API 的通用文档。 | `llm/embedding_model.py` 各子类 | Python 工程师 | 表格形式列出即可 |
+| 04-03 | 自动问题生成 | **写**：并发生成策略（ThreadPoolExecutor）、LLM 缓存机制（redis）、问题注入到 chunk metadata。**不写**：问题生成质量评估。 | `tasks.py:323+`, `prompts/generator.py:question_proposal()` | Python 工程师 | 与检索效果的关系 |
+
+### 05-vdb
+
+| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
+|------|------|----------|-------------|-----------|------|
+| 05-01 | ES 索引 Schema | **写**：字段定义、mapping 类型、ik_max_word analyzer、dense_vector cosine 配置、动态维度。**不写**：ES 集群运维、分片策略。 | `vdb/field.py`, `vdb/elasticsearch/elasticsearch_vector.py:653+` | Python 工程师 | 需附完整 mapping 示例 |
+| 05-02 | 混合检索 | **写**：BM25 + Vector 加权融合（0.05:0.95）、FusionExpr、score 归一化、降级策略。**不写**：BM25 算法数学推导、近似最近邻算法。 | `nlp/search.py:439`, `vdb/elasticsearch/elasticsearch_vector.py:374`, `utils/doc_store_conn.py:FusionExpr` | Python 工程师 | 核心章节，需讲清楚为什么权重是 0.05:0.95 |
+| 05-03 | 存储连接层 | **写**：ES 连接、Redis 缓存、DocStore 抽象。**不写**：连接池调优、网络安全配置。 | `utils/es_conn.py`, `utils/redis_conn.py`, `utils/doc_store_conn.py` | Python 工程师 | 轻量 |
+
+### 06-graphrag
+
+| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
+|------|------|----------|-------------|-----------|------|
+| 06-01 | GraphRAG 总览 | **写**：Light vs General 架构对比、适用场景、配置开关（use_graphrag/resolution/community）。**不写**：图数据库选型对比（已选 ES）。 | `graphrag/light/`, `graphrag/general/`, `graphrag/search.py` | Python 工程师 | 必须包含对比表格 |
+| 06-02 | 实体关系抽取 | **写**：Extractor 基类、_process_single_content 流程、Gleaning Loop、Prompt 工程、LLM 输出解析。**不写**：信息抽取的通用 NLP 方法。 | `graphrag/light/graph_extractor.py`, `graphrag/general/graph_extractor.py`, `graphrag/general/extractor.py` | Python 工程师 | 核心章节 |
+| 06-03 | 图合并与 PageRank | **写**：merge_subgraph 流程、nx.Graph 操作、PageRank 计算、实体消歧（EntityResolution）。**不写**：PageRank 数学推导。 | `graphrag/general/index.py`, `graphrag/entity_resolution.py` | Python 工程师 | 需附图数据结构示例 |
+| 06-04 | 社区报告 | **写**：Leiden 层次聚类、社区报告 Prompt、报告数据结构、存储方式。**不写**：社区发现算法数学原理。 | `graphrag/general/leiden.py`, `graphrag/general/community_reports_extractor.py`, `graphrag/general/community_report_prompt.py` | Python 工程师 | General only |
+| 06-05 | KG 检索 | **写**：KGSearch.retrieval() 流程、Query Rewrite、实体匹配、N-hop 扩展、社区报告检索。**不写**：图遍历算法通用理论。 | `graphrag/search.py:130` | Python 工程师 | 与标准检索的交互关系 |
+
+### 07-retrieval
+
+| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
+|------|------|----------|-------------|-----------|------|
+| 07-01 | 检索 API | **写**：knowledge_retrieval() 接口、Dealer.search() 内部实现、MatchDenseExpr / MatchTextExpr / FusionExpr。**不写**：信息检索通用理论。 | `nlp/search.py:36`, `nlp/search.py:349`, `utils/doc_store_conn.py` | Python 工程师 | 核心章节 |
+| 07-02 | Query 理解 | **写**：关键词提取、同义词扩展、查询改写、min_match 阈值调整。**不写**：NLP 句法分析。 | `nlp/query.py`, `nlp/synonym.py`, `nlp/term_weight.py` | Python 工程师 | 轻量 |
+| 07-03 | 多知识库检索 | **写**：Folder 类型递归检索、跨 KB 结果去重、权限过滤。**不写**：权限系统的 RBAC 设计。 | `workflow/nodes/knowledge/node.py:195`, `knowledge_repository.py` | Python 工程师 | 需说明 Folder 类型的特殊处理 |
+
+### 08-reranking
+
+| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
+|------|------|----------|-------------|-----------|------|
+| 08-01 | 重排序架构 | **写**：内置重排（token+vector 相似度融合）vs 外部 Rerank 模型、调用时机、容错降级。**不写**：Learning-to-Rank 通用理论。 | `nlp/search.py:606`, `models/rerank.py` | Python 工程师 | 需对比两种方式的适用场景 |
+| 08-02 | Rerank Provider | **写**：JinaRerank、DashScopeRerank 的 API 调用、参数映射。**不写**：各厂商 API 通用文档。 | `models/rerank.py:57+` | Python 工程师 | 轻量 |
+
+### 09-prompt
+
+| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
+|------|------|----------|-------------|-----------|------|
+| 09-01 | Prompt 模板系统 | **写**：template.py 的 .md 文件加载机制、generator.py 的函数式 Prompt 组装、参数替换。**不写**：Prompt Engineering 通用方法论。 | `prompts/template.py`, `prompts/generator.py` | Python 工程师 | 需列出全部模板清单 |
+| 09-02 | 引用标注 Prompt | **写**：citation_prompt / citation_plus 的输入输出、引用格式、上下文窗口管理。**不写**：学术论文引用规范。 | `prompts/generator.py:citation_prompt()` | Python 工程师 | 与 insert_citations 联动 |
+| 09-03 | 目录相关 Prompt | **写**：TOC 检测、提取、层级分配、基于 TOC 的 chunk 相关性筛选。**不写**：目录生成算法。 | `prompts/generator.py` TOC 系列函数 | Python 工程师 | 轻量 |
+
+### 10-llm
+
+| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
+|------|------|----------|-------------|-----------|------|
+| 10-01 | Chat 模型架构 | **写**：Base.chat() / chat_streamly() / chat_with_tools() 接口、返回格式、流式输出。**不写**：Transformer 模型原理。 | `llm/chat_model.py` | Python 工程师 | 重点讲接口契约 |
+| 10-02 | Chat Provider 全景 | **写**：各 Provider 配置、温度/TopP/MaxTokens 参数透传、错误处理。**不写**：各厂商 API 通用文档。 | `llm/chat_model.py` 各子类 | Python 工程师 | 表格形式 |
+| 10-03 | 视觉模型 | **写**：CV 模型接口、VLM 描述调用、图片理解。**不写**：CNN/ViT 原理。 | `llm/cv_model.py` | Python 工程师 | 轻量 |
+
+### 11-e2e
+
+| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
+|------|------|----------|-------------|-----------|------|
+| 11-01 | 端到端入库流程 | **写**：Celery 任务链、parse_document 完整流程、进度追踪、错误处理、GraphRAG 异步触发。**不写**：Celery 分布式队列原理。 | `tasks.py` | Python 工程师 | 核心章节，需附时序图 |
+| 11-02 | 端到端检索流程 | **写**：Workflow Knowledge Node 完整流程、检索模式选择、结果组装。**不写**：Workflow Engine 通用设计。 | `workflow/nodes/knowledge/node.py` | Python 工程师 | 核心章节 |
+| 11-03 | 回答后处理 | **写**：引用插入、缓存策略、流式输出处理。**不写**：WebSocket 通用原理。 | `nlp/search.py:489`, `utils/redis_conn.py` | Python 工程师 | 轻量 |
+
+### 12-architecture-evolution
+
+| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
+|------|------|----------|-------------|-----------|------|
+| 12-01 | 模块化拆分建议 | **写**：当前耦合点识别、建议的接口抽象（如 ParserInterface、ChunkerInterface）、拆分优先级。**不写**：微服务拆分方案。 | 全局代码分析 | AI 知识库专家 | 架构建议，无代码 |
+| 12-02 | 性能优化方向 | **写**：Embedding 批处理优化、ES 查询优化、GraphRAG 并发优化、缓存命中率提升。**不写**：通用性能优化方法论。 | 全局代码分析 | AI 知识库专家 | 需量化当前瓶颈假设 |
+| 12-03 | 未来扩展 | **写**：多模态检索、混合搜索增强、对话记忆优化、知识图谱演进方向。**不写**：产品需求文档。 | 全局代码分析 | AI 知识库专家 | 架构建议，无代码 |
+
+---
+
+## 工作量估算
+
+| 阶段 | 文档数 | 预估 Sprint-2 人天（每篇 0.5~1d） |
+|------|--------|----------------------------------|
+| 01-loader | 4 | 2d |
+| 02-parser | 5 | 3d |
+| 03-chunking | 4 | 2.5d |
+| 04-embedding | 3 | 1.5d |
+| 05-vdb | 3 | 2d |
+| 06-graphrag | 5 | 3d |
+| 07-retrieval | 3 | 2d |
+| 08-reranking | 2 | 1d |
+| 09-prompt | 3 | 1.5d |
+| 10-llm | 3 | 1.5d |
+| 11-e2e | 3 | 2d |
+| 12-architecture-evolution | 3 | 1.5d |
+| **合计** | **41** | **~23.5d** |
+
+> 注：Python 工程师承担约 30 篇（技术实现细节），AI 知识库专家承担约 8 篇（架构/优化/扩展方向）。具体分配由项目经理确认。