adai/MemoryBear
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
343a5eebe3bee2eccc9b10ecdf1fad7596aa4c94
MemoryBear/docs/rag/overview/DocMap.md
Multica PM Agent 343a5eebe3
Some checks failed
Sync to Gitee / sync (push) Has been cancelled
Details
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

195 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 篇（架构/优化/扩展方向）。具体分配由项目经理确认。
Reference in New Issue View Git Blame Copy Permalink