MemoryBear/docs/rag/overview/DocMap.md

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 篇（架构/优化/扩展方向）。具体分配由项目经理确认。