MemoryBear/docs/rag/overview/source-inventory.md

[S1-T3] MemoryBear RAG 源码盘点与模块依赖关系图谱 — 交付物

一、模块清单

统计口径：api/app/core/rag/ 全部子目录 + api/app/core/workflow/nodes/knowledge + api/app/core/rag_utils/ 共 ~24,900+ LOC Python 代码。

子模块路径	主要职责	入口文件 / 关键类 / 关键函数	对外接口（被谁调用 / 调用谁）	第三方依赖	文件数 / 行数
rag/app	文档解析与分块 orchestrator；按 doc_type 路由到不同解析策略（naive / book / paper / qa / audio / picture / manual / laws / mail / one）	naive.py:508 chunk()、naive.py:257 naive.__call__()、naive.py:27 by_deepdoc()、naive.py:45 by_mineru()、naive.py:65 by_textln()	被 tasks.py 调用（Celery ingestion）；调用 deepdoc/parser + deepdoc/vision + rag/nlp + rag/llm/cv_model + rag/llm/sequence2txt_model	python-docx, openpyxl, pdfplumber, markdown, Pillow	12 / 2,923
rag/common	RAG 共享常量、异常、装饰器、工具函数（文件/浮点/日志/字符串/Token 计数）	constants.py（常量定义）、token_utils.py（encoder）、settings.py:13 init_settings()（单例初始化）	被 rag/utils/es_conn.py、rag/graphrag/utils.py、rag/nlp/search.py 等广泛 import	tiktoken（tokenizer）	12 / 602
rag/crawler	Web 页面抓取与内容提取	web_crawler.py、content_extractor.py、http_fetcher.py	被 tasks.py 调用；由 knowledge sync 触发	requests	9 / 1,237
rag/deepdoc/parser	11 种格式文档解析（PDF/Word/Excel/HTML/MD/JSON/TXT/PPT）	pdf_parser.py:34 RAGPdfParser.__call__:1124、docx_parser.py:9 RAGDocxParser、mineru_parser.py:41 MinerUParser`	被 rag/app/naive.py import 并调用	pdfplumber, pypdf, python-docx, openpyxl, beautifulsoup4, markdown, pandas	12 / 3,228
rag/deepdoc/vision	文档视觉分析：布局识别 + OCR + 表格结构识别	ocr.py:522 OCR.__call__:694、layout_recognizer.py:17 LayoutRecognizer、table_structure_recognizer.py:15 TableStructureRecognizer	被 pdf_parser.py 调用进行版面/表格/图像识别	onnxruntime, huggingface_hub, Pillow, opencv-python, numpy	10 / 3,657
rag/graphrag（顶层）	GraphRAG 共享工具、实体消歧、查询分析提示、知识图谱搜索	search.py:19 KGSearch(Dealer)、entity_resolution.py:31 EntityResolution、utils.py（graph merge/persist/LLM cache）	被 tasks.py、workflow knowledge node、prompts/generator.py 调用	networkx, pandas, trio, redis, xxhash, json_repair	6 / 1,452
rag/graphrag/general	通用/完整版 GraphRAG 流水线：子图抽取 → 合并 → 实体消歧 → Leiden 社区 → 社区报告	index.py:36 run_graphrag()、index.py:122 run_graphrag_for_kb()、graph_extractor.py:34 GraphExtractor、community_reports_extractor.py:37	被 tasks.py 的 Celery task 调用；调用 ElasticSearchVector 写图数据	networkx, graspologic, tiktoken, trio	11 / 1,857
rag/graphrag/light	轻量版 GraphRAG（LightRAG 风格）：简化实体/关系抽取，无社区报告	light/graph_extractor.py:31 GraphExtractor	被 general/index.py 根据 parser_config.graphrag.method 条件切换调用	networkx, trio	3 / 462
rag/integrations/feishu	飞书文档同步客户端	client.py: FeishuAPIClient	被 knowledge_controller.py + tasks.py 调用	requests	6 / 737
rag/integrations/yuque	语雀文档同步客户端	client.py: YuqueAPIClient	被 knowledge_controller.py + tasks.py 调用	requests	6 / 844
rag/llm	LLM 多模型统一 facade（Chat / Embedding / CV / Seq2txt）	chat_model.py:52 Base、embedding_model.py:14 Base、cv_model.py:19 Base、sequence2txt_model.py:15 Base	被 rag/app、rag/nlp/search、rag/graphrag、rag/vdb、workflow/nodes/knowledge 等调用	openai, dashscope, azure-openai, ollama, zhipuai, requests	5 / 1,676
rag/models	Chunk 数据模型	chunk.py:17 DocumentChunk、chunk.py:5 ChildDocumentChunk	被 rag/vdb、rag/app、workflow/nodes/knowledge、tasks.py 引用	pydantic	2 / 72
rag/nlp	NLP 工具箱：中文分词、BM25/hybrid 搜索调度、同义词扩展、术语权重、Query 重写	search.py:349 Dealer（含 retrieval:674、search:387、rerank:606）、rag_tokenizer.py:15 RagTokenizer、query.py:10 FulltextQueryer	被 rag/app/naive.py、rag/graphrag、rag/prompts/generator.py、rag/common/settings.py 调用	datrie, hanziconv, nltk, pandas, numpy	7 / 2,962
rag/prompts	Prompt 模板加载与 LLM prompt 工厂	template.py:9 load_prompt()、generator.py（citation/keyword/question/toc/reflect 等 20+ 函数）	被 tasks.py、rag/nlp/search.py、rag/graphrag 调用；依赖 .md prompt 文件	jinja2, json_repair	3 / 769 + 31 md 文件
rag/utils	ES 连接、Redis 连接、LibreOffice 转换、文件工具	es_conn.py: ESConnection、redis_conn.py、libre_office.py、file_utils.py、doc_store_conn.py	被 rag/vdb、rag/common/settings.py、rag/app/naive.py、rag/nlp/search.py 调用	elasticsearch, redis	6 / 1,578
rag/vdb	向量数据库抽象 + Elasticsearch 实现	elasticsearch/elasticsearch_vector.py:29 ElasticSearchVector、elasticsearch/elasticsearch_vector.py:666 ElasticSearchVectorFactory、vector_base.py:9 BaseVector	被 tasks.py、knowledge_controller.py、chunk_controller.py、workflow/nodes/knowledge 调用	elasticsearch, langchain-core	3 / 83 + 2 / 753
rag/res	静态资源：NER 词表、同义词表、映射表	ner.json、synonym.json、mapping.json	被 rag/nlp/term_weight.py、rag/nlp/synonym.py 加载	—	3 JSON
workflow/nodes/knowledge	Workflow 知识检索节点：多知识库检索 + 重排序 + GraphRAG 增强	node.py:29 KnowledgeRetrievalNode、node.py:303 execute()、node.py:195 knowledge_retrieval()	被 workflow/nodes/node_factory.py、workflow/nodes/__init__.py 注册；调用 rag/vdb、rag/llm、rag/models	langchain-core	3 / 455
rag_utils（⚠️ 与 rag/utils 不同）	Chunk 内容 LLM 分析：摘要生成、标签提取、洞察分析、人物画像	chunk_summary.py:68 generate_chunk_summary()、chunk_tags.py:56 extract_chunk_tags()、chunk_insight.py:137 generate_chunk_insight()	被 services/memory_dashboard_service.py 调用；依赖 app.core.memory.* LLM 工厂	pydantic	4 / 588

---

二、依赖关系图谱（Mermaid）

graph TB
    subgraph "上层调用者"
        A1[tasks.py<br/>Celery Workers]
        A2[controllers/<br/>REST API]
        A3[workflow/nodes/<br/>知识检索节点]
        A4[services/memory_<br/>dashboard_service.py]
    end

    subgraph "RAG Core"
        B1[rag/app<br/>解析与分块]
        B2[rag/deepdoc/parser<br/>格式解析]
        B3[rag/deepdoc/vision<br/>版面/OCR]
        B4[rag/crawler<br/>网页抓取]
        B5[rag/integrations<br/>飞书/语雀]
        B6[rag/nlp<br/>分词/搜索调度]
        B7[rag/llm<br/>多模型Facade]
        B8[rag/vdb<br/>ES向量存储]
        B9[rag/graphrag<br/>知识图谱]
        B10[rag/prompts<br/>Prompt工厂]
        B11[rag/models<br/>Chunk模型]
        B12[rag/common<br/>常量/工具]
        B13[rag/utils<br/>ES/Redis连接]
    end

    subgraph "旁路模块"
        C1[rag_utils<br/>Chunk LLM分析]
    end

    A1 --> B1
    A1 --> B4
    A1 --> B5
    A1 --> B8
    A1 --> B9
    A1 --> B10
    A2 --> B1
    A2 --> B5
    A2 --> B8
    A2 --> B9
    A3 --> B8
    A3 --> B7
    A3 --> B11
    A4 --> C1

    B1 --> B2
    B1 --> B3
    B1 --> B6
    B1 --> B7
    B2 --> B3
    B2 --> B6
    B3 --> B12
    B4 --> B13
    B5 --> B13
    B6 --> B7
    B6 --> B13
    B6 --> B10
    B8 --> B7
    B8 --> B11
    B8 --> B13
    B9 --> B6
    B9 --> B7
    B9 --> B10
    B9 --> B13
    B10 --> B7
    B10 --> B9

    C1 --> B7
    B12 --> B13
    B13 --> B8

---

三、入口链路梳理

3.1 文档入库链路（Indexing Pipeline）

REST POST /document 或 /knowledge/{id}/sync
    ↓ 触发
Celery task @tasks.py:212 parse_document(file_path, document_id)
    ↓ 调用
rag/app/naive.py:508 chunk(filename, binary, ...)
    ↓ 路由 by file extension
    ├─ PDF → by_deepdoc() → deepdoc/parser/pdf_parser.py:34 RAGPdfParser.__call__:1124
    ├─ PDF alt → by_mineru() → deepdoc/parser/mineru_parser.py:41 MinerUParser.parse_pdf()
    ├─ DOCX → RAGDocxParser.__call__() @ docx_parser.py:9
    ├─ XLSX → RAGExcelParser.__call__() @ excel_parser.py:16
    ├─ HTML → RAGHtmlParser.__call__() @ html_parser.py:22
    ├─ MD  → RAGMarkdownParser.__call__() @ markdown_parser.py:6
    ├─ JSON → RAGJsonParser.__call__() @ json_parser.py:7
    └─ TXT → RAGTxtParser.__call__() @ txt_parser.py:7
    ↓
rag/app/naive.py:257 naive.__call__() — 提取 sections + tables
    ↓
rag/nlp/__init__.py — tokenize / naive_merge / hierarchical_merge
    ↓
rag/vdb/elasticsearch/elasticsearch_vector.py:55 add_chunks()
    ↓ 调用
rag/vdb/elasticsearch/elasticsearch_vector.py:65 create()
    ↓ 调用
embedding_model.py: encode() → LLM API → ES bulk index

3.2 在线检索链路（Query Pipeline）

REST POST /retrieval
    或
Workflow Node: workflow/nodes/knowledge/node.py:303 execute()
    ↓
workflow/nodes/knowledge/node.py:195 knowledge_retrieval()
    ↓ 根据 retrieve_type 分支
    ├─ PARTICIPLE → ElasticSearchVector.search_by_full_text() @ elasticsearch_vector.py:468
    ├─ SEMANTIC  → ElasticSearchVector.search_by_vector() @ elasticsearch_vector.py:374
    ├─ HYBRID    → 并行 vector + full_text → dedupe → rerank @ node.py:236-271
    └─ Graph     → HYBRID 结果 + kg_retriever.retrieval()
                        ↓ 调用
                        rag/common/settings.py:10 kg_retriever (单例)
                        ↓ 调用
                        rag/graphrag/search.py:19 KGSearch.retrieval()

3.3 GraphRAG 构建链路

REST POST /knowledge/{knowledge_id}/knowledge_graph
    或
Celery task @tasks.py:472 build_graphrag_for_kb(kb_id)
    ↓
Celery task @tasks.py:557 build_graphrag_for_document(document_id, knowledge_id)
    ↓
rag/graphrag/general/index.py:36 run_graphrag(row, language, with_resolution, with_community, ...)
    ↓
rag/graphrag/general/index.py:122 run_graphrag_for_kb(kb_id, ...)
    ↓ 流水线
    1. init_graphrag() → 创建 ES 索引
    2. GraphExtractor.extract() → 逐 chunk 抽取实体/关系
       ├─ general/graph_extractor.py:34 GraphExtractor (Microsoft GraphRAG 风格)
       └─ light/graph_extractor.py:31 GraphExtractor (LightRAG 风格，条件切换)
    3. graph_merge() → 合并子图
    4. EntityResolution.resolve() → 实体消歧
    5. leiden.run() → 社区发现
    6. CommunityReportsExtractor.extract() → 社区摘要
    7. set_graph() → 写回 ES

3.4 Workflow Knowledge 节点链路

workflow/nodes/knowledge/node.py:29 KnowledgeRetrievalNode
    ↓
node.py:54 _extract_input() — 渲染 query 模板，读取 knowledge_bases 配置
    ↓
node.py:303 execute()
    ↓
node.py:335 get_knowledge_by_id() — 校验知识库存在性
    ↓
node.py:195 knowledge_retrieval()
    ↓ 分支处理
    ├─ FOLDER 类型 → 递归遍历子知识库
    ├─ PARTICIPLE → vector_service.search_by_full_text()
    ├─ SEMANTIC  → vector_service.search_by_vector()
    ├─ HYBRID    → vector + full_text 并行 → dedupe → rerank
    └─ Graph     → HYBRID + kg_retriever.retrieval() 增强
    ↓
node.py:108 rerank() — 调用 RedBearRerank 模型
    ↓
node.py:362 返回 {"chunks": [...], "citations": [...]}

---

四、Gap 报告（代码 vs S1-T2 架构预期）

4.1 "架构里列了但代码里没有 / 命名/范围不一致"

#	差异项	S1-T2 架构预期	代码实际	影响与建议
1	缺少 Milvus/Weaviate/Qdrant 支持	VDB 环节预期讨论"向量数据库选型"，暗示可能多库	仅 rag/vdb/elasticsearch/ 有实现，BaseVector 无其他子类	架构文档中 VDB 章节需要明确限定为 Elasticsearch 8.x，或规划扩展接口
2	rag_utils vs rag/utils 命名冲突	预期目录：api/app/core/rag/{deepdoc,crawler,integrations,llm,vdb,graphrag,prompts,app}	实际存在 rag/utils（文件工具/ES 连接）和 rag_utils/（Chunk LLM 分析）两个独立目录，仅下划线差异	极易混淆，建议将 rag_utils/ 重命名为 rag/chunk_analytics/ 或合并到 rag/app/ 下游
3	nlp/search.py 中的 Dealer 是遗留/旁路模块	架构中 rag/nlp 预期为"分词/NLP 工具"	rag/nlp/search.py:349 Dealer 实际是一个完整的 BM25/hybrid 搜索调度器，与 rag/vdb 的 ES 向量搜索并行存在两套检索体系	两套检索代码并存（nlp/search.py 主要被 GraphRAG 使用，vdb/elasticsearch 被 Workflow 使用）。架构文档应明确标注 nlp/search 是 GraphRAG 专用旧通道
4	缺少独立的 Reranking 模块	S1-T2 预期有独立的 Reranking 环节	重排序逻辑散布在多处：workflow/nodes/knowledge/node.py:108 rerank()、rag/vdb/elasticsearch/elasticsearch_vector.py:560 rerank()、以及 rag/nlp/search.py:606 rerank()	建议 Sprint-2 文档将 Reranking 单独成章，汇总这三处实现并标注差异（Workflow 节点用 RedBearRerank，VDB 层也有独立 rerank，NLP 层有 model-based rerank）
5	Prompt 目录含大量 .md 模板但无统一版本管理	Prompt 工程是独立环节	rag/prompts/ 有 31 个 .md 模板文件 + template.py（加载器）+ generator.py（工厂函数），但模板修改无版本控制/审计机制	建议文档中标注 prompt 管理现状：文件驱动、运行时加载、无 A/B 或版本回滚机制
6	Deepdoc vision 模型加载路径硬编码	架构预期模型管理可配置	deepdoc/vision/ 各 recognizer 硬编码从 huggingface_hub.snapshot_download(repo_id="InfiniFlow/deepdoc") 下载到 res/deepdoc/，仅 HF_ENDPOINT 环境变量可配	建议文档中明确标注模型路径约束，为后续模型热更新/私有化部署做铺垫
7	GraphRAG light 是条件分支而非独立模块	S1-T2 预期 GraphRAG 有 light 和 general 两个独立目录	light/ 仅含 graph_extractor.py + graph_prompt.py（2 个逻辑文件），其余全部复用 general/ 的 Extractor 基类、utils.py、index.py	Sprint-2 文档应将 light 标记为"general 的条件子模式"，避免读者误以为两套完整流水线

4.2 "代码里有但架构没列"

#	差异项	代码位置	说明
1	rag/app 按 doc_type 路由的 11 种解析策略	rag/app/{naive,book,paper,qa,audio,picture,manual,laws,mail,one,textin_parser}.py	S1-T2 架构只提到 "Loader / Parser"，未提及 MemoryBear 特有的 doc_type 路由体系（book/paper/qa/audio 等）
2	MinerU 第三方解析器集成	rag/deepdoc/parser/mineru_parser.py	架构中 Parser 环节未提及 MinerU（第三方 PDF 解析服务）作为 PDF 解析的替代方案
3	TextIn 第三方解析器集成	rag/app/textin_parser.py	同上，未提及 TextIn API 作为另一 PDF 解析备选
4	rag_utils（Chunk LLM 分析）	api/app/core/rag_utils/	架构中无此模块定位，它实际做 chunk 摘要/标签/洞察，与 Memory 系统耦合
5	Toc（目录）智能提取链路	rag/prompts/generator.py:408-717	大量 LLM-driven TOC 检测/提取/索引/关联代码，架构大纲中未单列 "TOC 处理" 环节
6	Crawler（网页抓取）	rag/crawler/	架构中 Loader 环节可能包含爬虫，但代码量 1,200+ LOC 值得单独标注
7	res/ 静态资源（NER、同义词表）	rag/res/{ner.json,synonym.json,mapping.json}	架构中未提及术语权重/同义词扩展的资源文件体系

---

五、关键数据速查

指标	数值
api/app/core/rag/ 总 Python LOC	~24,895
api/app/core/rag/ 子模块数	15（不含 res/）
.md Prompt 模板数	31
Parser 实现数	11 种（含 PDF 3 种策略：deepdoc/mineru/textin）
LLM Provider 实现数	Chat 9 种 + Embed 10 种 + CV 7 种 + Seq2txt 6 种 = 32 个 provider 类
Workflow Knowledge 检索类型	PARTICIPLE / SEMANTIC / HYBRID / Graph（4 种）
GraphRAG 模式	general（Microsoft GraphRAG）/ light（LightRAG 风格）
VDB 实现	Elasticsearch 8.x（唯一）

---

以上交付物已同步写入本地文件 WS-14-deliverable.md，可作为 Sprint-2 文档化的底图直接复用。