rag/docs/开发与系统模块说明.md

开发与系统模块说明

本文档由原《开发文档》与《模块说明》合并而成，涵盖开发环境配置、技术栈、架构以及细粒度模块说明。

第一部分：开发文档体系

RAG 知识库问答系统 - 开发文档

项目版本: v7.0.0 更新日期: 2026-06-04 文档用途: 架构说明、技术栈、部署指南

API 接口文档: 详见 后端对接规范.md

---

一、项目概述

1.1 项目定位

本项目是智能出题系统的核心知识服务层，为上层 Dify 工作流提供知识检索能力。系统通过 RAG（检索增强生成）技术，实现基于企业制度文档的智能问答，支持：

• 知识库问答：基于向量检索 + BM25 + Rerank 的混合检索
• Agentic RAG：智能问答流程（Query Rewriting、Context Compression、Answer Grounding）
• 多轮对话：会话历史管理、代词消解
• 网络搜索：实时信息获取（可选，需配置 Serper API）

1.2 系统架构

┌─────────────────────────────────────────────────────────────────────┐
│                          前端应用层                                  │
│                    (chat-ui/ 开发测试界面)                           │
└───────────────────────────────┬─────────────────────────────────────┘
                                │ HTTP API / SSE
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       API 服务层 (api/)                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌────────────┐ │
│  │   /chat     │  │    /rag     │  │ /sessions   │  │  /search   │ │
│  │ 智能聊天    │  │ SSE 流式问答│  │ 会话管理    │  │ 混合检索   │ │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └─────┬──────┘ │
└─────────┼────────────────┼────────────────┼───────────────┼────────┘
          │                │                │               │
          ▼                ▼                ▼               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       核心能力层 (core/)                             │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                     Agentic RAG (agentic.py)                 │   │
│  │  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌──────────┐ │   │
│  │  │  Query    │  │  检索层   │  │  Context  │  │  Answer  │ │   │
│  │  │ Rewriting │  │向量+BM25  │  │Compression│  │ Grounding│ │   │
│  │  │ 统一入口  │  │ +Rerank   │  │ Token控制 │  │ 幻觉闭环 │ │   │
│  │  └───────────┘  └───────────┘  └───────────┘  └──────────┘ │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       数据存储层                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌────────────┐ │
│  │  ChromaDB   │  │   .data/    │  │  SQLite     │  │ documents/ │ │
│  │  向量数据库  │  │  图片存储   │  │  会话数据   │  │  文档源    │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └────────────┘ │
└─────────────────────────────────────────────────────────────────────┘

1.3 技术栈

层级	技术	说明
API 服务	Flask + Flask-CORS	RESTful API，SSE 流式返回
文档解析	MinerU 3.0+	PDF/DOCX/PPTX/图片统一解析
向量检索	ChromaDB + BGE-base-zh	本地向量数据库 + 嵌入模型
关键词检索	BM25 + jieba	中文分词 + 倒排索引
重排序	BGE-reranker-base	CrossEncoder 精排
大模型	Qwen (通义千问)	问答生成、查询改写、意图分析
数据库	SQLite	会话管理、知识管理

---

二、项目结构

├── main.py                  # 统一启动入口
├── config.py                # API 配置（需自行创建）
├── requirements.txt         # 依赖列表
│
├── api/                     # API 路由层（Flask Blueprint）
│   ├── __init__.py          #   create_app() 应用工厂
│   ├── chat_routes.py       #   /chat, /rag (SSE), /search
│   ├── session_routes.py    #   /sessions, /history
│   ├── auth_routes.py       #   /health, /auth/me
│   ├── kb_routes.py         #   /collections
│   ├── document_routes.py   #   /documents/upload
│   ├── sync_routes.py       #   /sync
│   ├── image_routes.py      #   /images/<id>
│   ├── feedback_routes.py   #   /feedback
│   └── response_utils.py    #   统一响应格式工具
│
├── core/                    # RAG 核心引擎
│   ├── agentic.py           #   AgenticRAG 智能问答（兼容入口）
│   ├── agentic_base.py      #   Agentic 基类与公共逻辑
│   ├── agentic_search.py    #   智能检索模块
│   ├── agentic_answer.py    #   答案生成模块
│   ├── agentic_citation.py  #   引用与来源标注
│   ├── agentic_context.py   #   上下文压缩与管理
│   ├── agentic_query.py     #   查询改写与处理
│   ├── agentic_media.py     #   富媒体处理
│   ├── agentic_quality.py   #   质量评估与幻觉检测
│   ├── agentic_meta.py      #   元信息与状态管理
│   ├── engine.py            #   检索引擎封装
│   ├── bm25_index.py        #   BM25 索引
│   ├── chunker.py           #   文本分块
│   ├── query_classifier.py  #   查询分类器
│   ├── intent_analyzer.py   #   意图分析器
│   ├── confidence_gate.py   #   置信度门控
│   ├── quality_assessor.py  #   质量评估器
│   ├── loop_guard.py        #   循环防护
│   └── reasoning_reflector.py # 推理反思器
│
├── parsers/                 # 文档解析器
│   ├── mineru_parser.py     #   MinerU 统一解析 (PDF/DOCX/PPTX/图片)
│   ├── excel_parser.py      #   Excel 专属管道
│   └── image_extractor.py   #   图片噪音过滤
│
├── knowledge/               # 知识库管理
│   ├── manager.py           #   多向量库管理器
│   ├── router.py            #   知识库路由器
│   ├── sync.py              #   同步服务
│   ├── document.py          #   文档管理
│   ├── collection.py        #   集合管理
│   ├── search.py            #   检索接口
│   ├── permission.py        #   权限控制
│   ├── processing.py        #   处理流水线
│   ├── chunk.py             #   切片管理
│   └── ...                  #   更多模块见第二部分
│
├── services/                # 业务服务
│   ├── session.py           #   会话管理 (SQLite)
│   ├── feedback.py          #   反馈系统
│   └── outline.py           #   纲要生成
│
├── auth/                    # 认证与安全
│   ├── gateway.py           #   网关认证 (DEV_MODE mock token)
│   └── security.py          #   安全防护
│
├── repositories/            # 数据仓库层
│   ├── session_repo.py      #   会话仓库（抽象接口）
│   ├── sqlite_session_repo.py  # SQLite 实现
│   └── stateless_session_repo.py # 无状态实现
│
├── data/                    # SQLite 数据库
│   ├── db.py                #   统一数据访问层
│   ├── rag_core.db          #   会话/反馈数据
│   └── knowledge.db         #   知识管理数据
│
├── .data/                   # 运行时数据
│   ├── files/images/        #   提取的图片
│   └── mineru_output/       #   MinerU 解析输出
│
├── chat-ui/                 # 前端测试界面
│   ├── index.html           #   主页面
│   ├── app.js               #   主逻辑
│   └── api-test.js          #   API 测试面板
│
├── deploy/                  # 部署配置
│   ├── Dockerfile.prod      #   生产环境 Docker
│   ├── docker-compose.prod.yml # 生产环境 Compose
│   ├── gunicorn.conf.py     #   Gunicorn 配置
│   ├── nginx.conf           #   Nginx 配置
│   └── wsgi.py              #   WSGI 入口
│
├── docs/                    # 文档
│   ├── 后端对接规范.md       #   API 接口规范 (主要)
│   ├── 开发文档.md           #   本文档
│   └── ...
│
├── scripts/                 # 工具脚本
│   └── analyze_chunks.py    #   切片分析
│
├── tools/                   # 开发工具
│   ├── chunk_analyzer.py    #   切片分析
│   ├── chunk_metrics.py     #   指标统计
│   ├── llm_evaluator.py     #   LLM 评估
│   └── export_chunks.py     #   导出切片
│
└── exam_pkg/                # 出题系统（可选）
    ├── generator.py         #   试题生成
    ├── grader.py            #   评分批阅
    ├── manager.py           #   出题管理
    ├── local_db.py          #   本地题库
    └── api.py               #   Flask Blueprint

---

三、Agentic RAG 流程

3.1 完整流程图

用户问题 (query)
     │
     ▼
┌─────────────────────────────────────────────────────────────┐
│  1. Query Rewriting（统一入口）                              │
│     - 有历史对话 → 强制改写（消歧）                           │
│     - 短查询 (<10字符) → 强制改写（扩展）                     │
│     - 其他 → LLM 判断是否需要改写                            │
└─────────────────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────────────────┐
│  2. 查询分类 (QueryClassifier)                              │
│     - FACT: 事实查询 → 直接检索                              │
│     - COMPARISON: 比较查询 → 分解检索                        │
│     - META: 元问题 → 直接回答                                │
│     - REALTIME: 实时信息 → 网络搜索（可选）                   │
└─────────────────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────────────────┐
│  3. 检索流程                                                 │
│     - 向量检索 + BM25 + Rerank                               │
│     - 置信度门控检查 (threshold=0.3)                         │
│     - 多维质量评估 (相关性/完整性/准确性/覆盖率)              │
└─────────────────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────────────────┐
│  4. Context Compression                                      │
│     - Rerank 过滤 (score < 0.3 丢弃)                         │
│     - 去重 (相同来源+页码只保留一个)                          │
│     - Token 控制 (max=3500 tokens, max=20 条)               │
└─────────────────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────────────────┐
│  5. 答案生成                                                 │
│     - 多源融合 (知识库 + 网络)                               │
│     - 来源标注                                               │
└─────────────────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────────────────┐
│  6. Answer Grounding（幻觉闭环）                             │
│     - 幻觉检测 (推理反思器)                                  │
│     - 发现幻觉 → 补充检索 → 重新生成                         │
│     - 最多重试 1 次                                          │
└─────────────────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────────────────┐
│  7. 输出                                                     │
│     - answer: 回答内容                                       │
│     - sources: 来源列表（已去重，含页码范围）                 │
│     - images/tables: 富媒体信息                              │
│     - session_id: 会话ID（用于多轮对话）                      │
└─────────────────────────────────────────────────────────────┘

3.2 关键配置参数

参数	值	说明
MAX_CONTEXT_TOKENS	3500	上下文最大 token 数
MAX_CONTEXT_COUNT	20	上下文最大条数
RERANK_THRESHOLD	0.3	Rerank 过滤阈值
MAX_GROUNDING_RETRY	1	幻觉修正最多重试次数
max_iterations	3	最大迭代检索次数

---

四、API 接口

详细 API 文档: 详见 后端对接规范.md

核心接口概览

接口	方法	说明
/chat	POST	智能聊天
/rag	POST	知识库问答（SSE 流式）
/search	POST	混合检索（供 Dify 调用）
/sessions	GET	会话列表
/history/<id>	GET	会话历史
/collections	GET	向量库列表
/images/<id>	GET	获取图片
/sync	POST	触发同步
/health	GET	健康检查

---

五、开发环境配置

5.1 环境准备

# 创建虚拟环境
python -m venv venv
.\venv\Scripts\Activate.ps1

# 安装依赖
pip install -r requirements.txt

5.2 配置文件

复制 config.example.py 为 config.py：

# config.py - 必需配置

# 通义千问 API（必需）
DASHSCOPE_API_KEY = "your-api-key"
DASHSCOPE_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
DASHSCOPE_MODEL = "qwen-flash"           # 文本模型
DASHSCOPE_VL_MODEL = "qwen-vl-plus"      # 视觉模型（图片描述）

# 兼容变量
API_KEY = DASHSCOPE_API_KEY
BASE_URL = DASHSCOPE_BASE_URL
MODEL = DASHSCOPE_MODEL

# 文档路径
DOCUMENTS_PATH = "./documents"

# 开发模式（支持 mock 用户）
DEV_MODE = True

5.3 开发模式特性

特性	说明
Mock 用户	支持 mock-token-admin 等模拟 token
本地登录	/auth/login 接口支持用户名密码登录
会话存储	SQLite 本地存储，无需外部数据库
前端界面	http://localhost:5001 直接访问测试

模拟用户列表：

用户名	密码	角色
admin	admin123	admin
manager	manager123	manager
user	test123	user

---

六、运行命令

6.1 启动服务

# 激活虚拟环境
.\venv\Scripts\Activate.ps1

# 启动服务
python main.py                  # 端口 5001
python main.py --port 8080      # 指定端口

6.2 同步知识库

# 通过 API 触发同步
curl -X POST http://localhost:5001/sync

# 或通过前端界面操作

---

七、会话管理

7.1 多轮对话流程

首次对话:
POST /rag { "message": "出差补助标准", "collections": ["public_kb"] }
    ↓
finish 事件返回 session_id
    ↓
前端保存 session_id

后续对话:
POST /rag { "message": "它有什么限制", "session_id": "xxx", "collections": ["public_kb"] }
    ↓
RAG 服务自动从 SQLite 加载历史
    ↓
Query Rewriting: "它" → "出差补助"
    ↓
生成带上下文的回答

7.2 会话相关 API

接口	说明
GET /sessions	获取用户会话列表
GET /history/<session_id>	获取会话历史
DELETE /session/<session_id>	删除会话

---

八、部署指南

8.1 生产环境建议

项目	建议
DEV_MODE	设置为 false
WSGI 服务器	gunicorn 或 uWSGI
反向代理	Nginx
HTTPS	配置 SSL 证书

8.2 职责边界

后端负责	RAG 服务负责
用户认证	知识库问答
权限判断	向量检索
会话管理（生产）	返回溯源
消息存储	文档处理

---

九、错误码说明

状态码	说明	处理建议
200	成功	-
400	请求参数错误	检查请求体格式
401	未认证	检查 Header 认证信息
403	权限不足	检查用户角色权限
404	资源不存在	检查 session_id 或资源路径
500	服务器内部错误	查看服务日志

---

十、相关文档

• 后端对接规范.md - API 接口规范（主要）
• 数据库设计文档.md - 数据库结构
• RAG系统完整指南.md - RAG 系统架构与缓存详解

---

第二部分：模块规范体系

项目模块说明文档 (v7.0.0)

注：本项目经过大规模重构，采用模块化架构。当前版本已包含细粒度多向量库权限控制、文档生命周期跟踪、本地化自动出题系统、FAQ问答闭环反馈收集，以及 Agentic RAG 细粒度拆分模块。图谱模块(graph/)已完全移除。

项目架构概览

┌─────────────────────────────────────────────────────────────────────────────┐
│                              API 服务层                                      │
│                            main.py (入口)                                   │
│    (Flask 应用工厂，整合所有 Blueprint，提供 REST API)                        │
└─────────────────────────────────────────────────────────────────────────────┘
         │         │         │         │         │         │         │
         ▼         ▼         ▼         ▼         ▼         ▼         ▼
┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌──────────┐
│ RAG 核心 ││ 知识库   ││ 出题系统 ││ 安全模块 ││ 同步服务 ││ 反馈闭环 ││ 纲要生成 │
│core/     ││knowledge/││exam_pkg/ ││auth/     ││knowledge/││services/ ││services/ │
│agentic_* ││manager.py││generator ││gateway.py││sync.py   ││feedback.py││outline.py│
│engine.py ││search.py ││grader.py ││security.py│          ││          ││          │
│bm25_     ││document.py││manager.py│          ││          ││          ││          │
│index.py  ││chunk.py  ││local_db.py│          ││          ││          ││          │
│chunker.py││permission││api.py    ││          ││          ││          ││          │
│          ││processing││          ││          ││          ││          ││          │
└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘
     │                                                    │
     ▼                                                    │
┌──────────────────────────┐                              │
│   多向量库管理            │                              │
│ knowledge/manager.py     │                              │
│ knowledge/router.py      │                              │
│ knowledge/collection.py  │                              │
└──────────────────────────┘                              │
                              ┌─────────────────────┼─────────────────────┐
                              │                     │                     │
                              ▼                     ▼                     ▼
                       ┌──────────┐          ┌──────────┐          ┌──────────┐
                       │会话管理  │          │题库生成  │          │会话仓库  │
                       │services/ │          │exam_pkg/ │          │repos/    │
                       │session.py│          │generator │          │session_  │
                       └──────────┘          └──────────┘          │repo.py   │
                                                                   └──────────┘

---

目录结构

项目根目录/
├── main.py                  # ✨ 统一启动入口（推荐）
├── config.py                # API 配置（不提交）
├── config.example.py        # API 配置模板
├── requirements.txt         # 依赖列表
├── requirements-prod.txt    # 生产环境依赖
│
├── api/                     # API 路由层（Flask Blueprint）
│   ├── __init__.py          #   create_app() 应用工厂
│   ├── chat_routes.py       #   /chat, /rag, /rag/stream, /search
│   ├── session_routes.py    #   /sessions, /history, /session, /clear
│   ├── auth_routes.py       #   /stats, /health, /auth/me
│   ├── audit_routes.py      #   /audit/logs
│   ├── kb_routes.py         #   /collections, /documents/sync, /kb/route
│   ├── document_routes.py   #   /documents/upload, /documents/list, 版本管理
│   ├── sync_routes.py       #   /sync, /subscribe, /notifications
│   ├── feedback_routes.py   #   /feedback/*, /reports/*, /faq/*
│   ├── image_routes.py      #   图片相关接口
│   └── response_utils.py    #   统一响应格式工具
│
├── core/                    # RAG 核心引擎
│   ├── __init__.py
│   ├── agentic.py           #   AgenticRAG 智能问答（兼容入口）
│   ├── agentic_base.py      #   Agentic 基类与公共逻辑
│   ├── agentic_search.py    #   智能检索模块
│   ├── agentic_answer.py    #   答案生成模块
│   ├── agentic_citation.py  #   引用与来源标注
│   ├── agentic_context.py   #   上下文压缩与管理
│   ├── agentic_query.py     #   查询改写与处理
│   ├── agentic_media.py     #   富媒体（图片/表格）处理
│   ├── agentic_quality.py   #   质量评估与幻觉检测
│   ├── agentic_meta.py      #   元信息与状态管理
│   ├── engine.py            #   检索引擎封装
│   ├── bm25_index.py        #   BM25 关键词索引
│   ├── chunker.py           #   语义分块器
│   ├── query_classifier.py  #   查询分类器
│   ├── intent_analyzer.py   #   意图分析器
│   ├── query_decomposer.py  #   查询分解器
│   ├── query_expansion.py   #   查询扩展
│   ├── confidence_gate.py   #   置信度门控
│   ├── quality_assessor.py  #   质量评估器
│   ├── reasoning_reflector.py # 推理反思器
│   ├── loop_guard.py        #   循环防护
│   ├── mmr.py               #   MMR 多样性排序
│   ├── cache.py             #   通用缓存
│   ├── semantic_cache.py    #   语义缓存
│   ├── adaptive_topk.py     #   自适应 TopK 选取
│   ├── llm_budget.py        #   LLM Token 预算管理
│   ├── llm_utils.py         #   LLM 调用工具
│   ├── status_codes.py      #   状态码定义
│   └── constants.py         #   全局常量
│
├── parsers/                 # 文档解析器
│   ├── __init__.py
│   ├── mineru_parser.py      #   MinerU 统一解析（PDF/DOCX/PPTX/图片）
│   ├── pdf_mineru.py         #   MinerU PDF 兼容别名
│   ├── excel_parser.py       #   Excel 解析（Pandas 管道）
│   ├── txt_parser.py         #   TXT 解析
│   └── image_extractor.py   #   图片提取器
│
├── knowledge/               # 知识库管理模块
│   ├── __init__.py
│   ├── base.py              #   知识库基类与公共定义
│   ├── manager.py           #   多向量库管理器
│   ├── router.py            #   知识库路由器
│   ├── collection.py        #   向量库集合管理
│   ├── document.py          #   文档管理（增删改查）
│   ├── document_versions.py #   文档版本管理
│   ├── search.py            #   知识库检索接口
│   ├── permission.py        #   权限控制
│   ├── processing.py        #   文档处理流水线
│   ├── chunk.py             #   切片管理
│   ├── index.py             #   索引管理
│   ├── sync.py              #   同步服务
│   ├── cleanup.py           #   清理与回收
│   ├── lazy_enhance.py      #   延迟增强（按需优化）
│   └── vector_store/        #   向量数据库与BM25索引
│       ├── chroma/          #   ChromaDB存储
│       └── bm25/            #   BM25索引存储
│
├── repositories/            # 数据仓库层
│   ├── __init__.py
│   ├── session_repo.py      #   会话仓库（抽象接口）
│   ├── sqlite_session_repo.py  #   SQLite 会话仓库实现
│   └── stateless_session_repo.py # 无状态会话仓库实现
│
├── exam_pkg/                # 考试系统
│   ├── __init__.py
│   ├── generator.py         #   试题生成器
│   ├── grader.py            #   评分与批阅
│   ├── manager.py           #   出题与批卷管理
│   ├── local_db.py          #   本地题库
│   └── api.py               #   Flask Blueprint (exam_bp)
│
├── services/                # 业务服务
│   ├── __init__.py
│   ├── session.py           #   会话管理
│   ├── feedback.py          #   反馈质量闭环
│   └── outline.py           #   纲要生成与推荐
│
├── auth/                    # 认证与安全
│   ├── __init__.py
│   ├── gateway.py           #   网关认证
│   └── security.py          #   输入/输出安全
│
├── storage/                 # 文件存储服务
│   ├── __init__.py
│   ├── file_fetcher.py      #   文件获取
│   └── file_provider.py     #   文件提供
│
├── data/                    # SQLite 数据库
│   ├── __init__.py
│   ├── db.py                #   统一数据访问层
│   ├── rag_core.db          #   核心数据（会话、反馈）
│   └── knowledge.db         #   知识管理（同步、大纲、版本）
│
├── tools/                   # 开发与分析工具
│   ├── chunk_analyzer.py    #   切片质量分析
│   ├── chunk_metrics.py     #   切片指标统计
│   ├── chunk_report.py      #   切片报告生成
│   ├── llm_evaluator.py     #   LLM 评估器
│   ├── export_chunks.py     #   导出切片
│   ├── clean_vector_store.py #  清理向量库
│   ├── rebuild_pdf_vectors.py # 重建 PDF 向量
│   └── upload_test_files.py #   上传测试文件
│
├── deploy/                  # 部署配置
│   ├── Dockerfile           #   开发环境 Docker
│   ├── Dockerfile.prod      #   生产环境 Docker
│   ├── docker-compose.yml   #   开发环境 Compose
│   ├── docker-compose.prod.yml # 生产环境 Compose
│   ├── gunicorn.conf.py     #   Gunicorn 配置
│   ├── nginx.conf           #   Nginx 配置
│   └── wsgi.py              #   WSGI 入口
│
├── documents/               # 知识库文档目录
├── models/                  # 本地模型目录
├── scripts/                 # 工具脚本
│   ├── analyze_chunks.py    #   切片分析
│   ├── analyze_content_list.py # 内容列表分析
│   ├── check_tables.py      #   数据表检查
│   ├── compare_embedding_models.py # 嵌入模型对比
│   ├── eval_e2e.py          #   端到端评估
│   ├── evaluate_answer.py   #   答案评估
│   ├── evaluate_rag.py      #   RAG 评估
│   ├── fix_image_paths.py   #   图片路径修复
│   ├── migrate_add_metadata.py   # 元数据迁移
│   ├── migrate_split_databases.py # 数据库拆分迁移
│   ├── migrate_version_status.py  # 版本状态迁移
│   ├── rebuild_multi_kb.py        # 重建多向量库
│   └── test_rag_questions.py      # RAG问题测试
├── tests/                   # 测试
├── chat-ui/                 # 前端界面
├── dev-ui/                  # 开发前端（Vite + Vue）
├── venv/                    # 虚拟环境
│

注意: 根目录下的 .py 文件大多已迁移至子包，保留仅为向后兼容。 新代码请使用子包路径导入，如 from auth.gateway import require_gateway_auth。

---

模块详细说明

一、API 路由层 (api/)

1. api/__init__.py - 应用工厂

职责：创建并配置 Flask 应用，注册所有 Blueprint

主要功能：

• 初始化共享服务（SessionManager、AuditLogger、AgenticRAG）
• 注册所有 API Blueprint
• 可选模块按需加载

使用方式：

from api import create_app

app = create_app()
app.run(host='0.0.0.0', port=5001)

2. API Blueprint 分组

Blueprint	文件	端点前缀	主要功能
auth_bp	auth_routes.py	-	/stats, /health, /auth/me
session_bp	session_routes.py	-	/sessions, /history, /session, /clear
audit_bp	audit_routes.py	-	/audit/logs
chat_bp	chat_routes.py	-	/chat, /rag, /rag/stream, /search
kb_bp	kb_routes.py	-	/collections, /documents/sync, /kb/route
document_bp	document_routes.py	-	/documents/upload, /documents/list
sync_bp	sync_routes.py	-	/sync, /subscribe, /notifications
feedback_bp	feedback_routes.py	-	/feedback/, /reports/, /faq/*
image_bp	image_routes.py	-	图片上传、处理相关接口
exam_bp	exam_pkg/api.py	/exam	出题系统相关接口

工具模块：

文件	说明
response_utils.py	统一响应格式封装（成功/错误/流式响应构造）

---

二、核心 RAG 模块 (core/)

3. core/agentic.py - Agentic RAG 兼容入口

职责：智能问答的 Agent 决策引擎（向后兼容入口，内部委托至细粒度模块）

主要功能：

• Agent 决策循环（检索、改写、分解、回答）
• 网络搜索集成（Serper API）
• 多源结果融合
• SSE 流式输出

关键类/函数：

类/函数	说明
AgenticRAG	主类，封装所有 Agent 功能
process()	处理用户查询
chat_search()	聊天搜索（支持网络搜索）
simple_query()	简化调用接口

使用方式：

from core.agentic import AgenticRAG, simple_query

# 完整模式
rag = AgenticRAG()
result = rag.process("出差补助标准是什么？")

# 简化模式
result = simple_query("出差补助标准")

4. Agentic 细粒度拆分模块

v7.0.0 将 agentic.py 的职责拆分为以下独立模块，各司其职：

模块	职责
agentic_base.py	Agentic 基类与公共逻辑（配置注入、依赖初始化）
agentic_search.py	智能检索模块（向量检索 + BM25 + Rerank 编排）
agentic_answer.py	答案生成模块（多源融合、流式输出）
agentic_citation.py	引用与来源标注（来源去重、页码范围合并）
agentic_context.py	上下文压缩与管理（Token 控制、去重、截断）
agentic_query.py	查询改写与处理（代词消解、查询扩展）
agentic_media.py	富媒体处理（图片/表格提取与标注）
agentic_quality.py	质量评估与幻觉检测（Answer Grounding）
agentic_meta.py	元信息与状态管理（计时、统计、调试信息）

5. core/engine.py - 检索引擎封装

职责：统一的检索引擎接口

主要功能：

• 向量检索
• BM25 关键词检索
• 混合检索 + Rerank

6. core/bm25_index.py - BM25 索引管理

职责：BM25 关键词索引的构建和查询

7. core/query_classifier.py - 查询分类器

职责：对用户查询进行意图分类，辅助选择合适的检索策略

8. core/intent_analyzer.py - 意图分析器

职责：深度意图分析，识别查询类型（事实/比较/元问题/实时信息）

9. core/query_decomposer.py - 查询分解器

职责：将复杂查询分解为多个子查询并行检索

10. core/query_expansion.py - 查询扩展

职责：基于 LLM 对查询进行语义扩展，提升召回率

11. core/confidence_gate.py - 置信度门控

职责：基于置信度判断是否需要额外的检索或改写

12. core/quality_assessor.py - 质量评估器

职责：评估检索结果和生成回答的质量

13. core/reasoning_reflector.py - 推理反思器

职责：对推理过程进行反思和优化

14. core/loop_guard.py - 循环防护

职责：防止 Agent 陷入无限循环，控制最大迭代次数

15. 缓存与检索优化模块

模块	职责
mmr.py	MMR（Maximal Marginal Relevance）多样性排序，减少冗余结果
cache.py	通用缓存层，加速重复查询
semantic_cache.py	语义缓存，基于向量相似度的缓存匹配
adaptive_topk.py	自适应 TopK 选取，根据查询复杂度动态调整返回数量

16. LLM 工具模块

模块	职责
llm_budget.py	LLM Token 预算管理，控制上下文与输出长度
llm_utils.py	LLM 调用工具，封装 API 请求、重试与错误处理

17. 全局定义模块

模块	职责
status_codes.py	状态码定义（成功/失败/部分成功等）
constants.py	全局常量（阈值、默认参数、配置键名）

---

三、知识库管理模块 (knowledge/)

18. knowledge/manager.py - 多向量库管理器

职责：多向量库的创建、管理和检索

主要功能：

• 多向量库创建与管理（public_kb + dept_xxx）
• 每个向量库独立的 BM25 索引
• 并行检索多个向量库
• RRF 融合结果

使用方式：

from knowledge.manager import get_kb_manager

kb_manager = get_kb_manager()

# 创建向量库
kb_manager.create_collection('dept_finance', display_name='财务部知识库')

# 检索
results = kb_manager.search_multiple(['public_kb', 'dept_finance'], query_vector)

19. knowledge/router.py - 知识库路由器

职责：根据查询意图和用户权限智能选择目标向量库

主要功能：

• 规则匹配（关键词识别部门）
• LLM 意图分析（复杂查询）
• 权限过滤

20. knowledge/sync.py - 知识库同步服务

职责：自动检测文档变更并触发增量更新

21. 知识库新增模块

v7.0.0 对 knowledge/ 进行了细粒度拆分，新增以下模块：

模块	职责
base.py	知识库基类与公共定义（接口抽象、数据类型）
collection.py	向量库集合管理（创建、删除、元数据维护）
document.py	文档管理（增删改查、状态跟踪）
document_versions.py	文档版本管理（版本创建、回滚、差异对比）
search.py	知识库检索接口（统一检索入口、多策略融合）
permission.py	权限控制（用户/部门/角色维度的访问控制）
processing.py	文档处理流水线（解析 -> 分块 -> 向量化 -> 入库）
chunk.py	切片管理（切片存储、检索、元数据）
index.py	索引管理（向量索引构建与更新）
cleanup.py	清理与回收（孤立切片清理、过期数据回收）
lazy_enhance.py	延迟增强（按需优化，如懒加载索引、延迟构建 BM25）

---

四、数据库模块 (data/)

22. data/db.py - 统一数据访问层

职责：集中管理所有数据库连接

主要功能：

• 统一数据库路径配置
• 连接池管理（上下文管理器）
• WAL 模式 + 外键约束
• 自动事务管理

数据库架构：

数据库	主要功能
rag_core.db	会话管理、用户反馈、FAQ
knowledge.db	知识库同步、文档版本、纲要缓存

使用方式：

from data.db import get_connection, init_databases

# 初始化数据库
init_databases()

# 使用连接
with get_connection("core") as conn:
    cursor = conn.cursor()
    cursor.execute("SELECT * FROM sessions WHERE user_id = ?", (user_id,))
    rows = cursor.fetchall()

---

五、出题系统模块 (exam_pkg/)

23. exam_pkg/generator.py - 试题生成器

职责：基于知识库内容自动生成试题

主要功能：

• 调用 Dify 工作流生成题目
• 题目类型控制（选择、判断、简答等）
• 难度分级生成

24. exam_pkg/grader.py - 评分与批阅

职责：自动批阅试卷并生成评分报告

25. exam_pkg/manager.py - 出题核心逻辑

职责：试卷生成、保存、批阅的核心业务逻辑

主要功能：

• 试卷 CRUD 操作
• 审核流程管理
• 自动批阅与报告生成

26. exam_pkg/local_db.py - 本地题库

职责：本地题目存储与管理

27. exam_pkg/api.py - 出题系统 API

职责：出题系统的 Flask Blueprint

API 端点：

端点	方法	说明
/exam/generate-by-file	POST	按文件生成题目（带溯源）
/exam/generate	POST	生成试卷
/exam/list	GET	获取试卷列表
/exam/<id>	GET/PUT/DELETE	试卷 CRUD
/exam/grade-from-mysql	POST	基于 MySQL 数据批卷

---

六、服务模块 (services/)

28. services/session.py - 会话管理

职责：多用户对话历史管理

主要功能：

• 会话创建与管理
• 消息历史存储
• 上下文压缩
• 会话过期清理

使用方式：

from services.session import SessionManager

sm = SessionManager()
session_id = sm.create_session("user_123")
sm.add_message(session_id, "user", "出差补助标准是什么？")
history = sm.get_history(session_id)

29. services/feedback.py - 反馈服务

职责：用户反馈收集与 FAQ 自动沉淀

30. services/outline.py - 纲要生成器

职责：自动生成文档结构纲要

---

七、认证与安全模块 (auth/)

31. auth/gateway.py - 网关认证

职责：网关注入的 Header 认证与多向量库权限控制

主要功能：

• 从 Header 读取用户信息（X-User-ID、X-User-Role、X-User-Department）
• 角色映射
• 多向量库权限控制
• @require_gateway_auth 装饰器

网关注入的 Header：

Header	说明
X-User-ID	用户唯一标识
X-User-Name	用户名
X-User-Role	用户角色
X-User-Department	部门

32. auth/security.py - 安全防护

职责：Prompt 注入防护

---

八、数据仓库层 (repositories/)

33. repositories/session_repo.py - 会话仓库（抽象接口）

职责：定义会话持久化的抽象接口，支持多种后端实现

34. repositories/sqlite_session_repo.py - SQLite 会话仓库

职责：基于 SQLite 的会话仓库实现，适用于开发和单机部署

35. repositories/stateless_session_repo.py - 无状态会话仓库

职责：无状态会话仓库实现，会话数据由调用方管理，适用于分布式部署

---

九、开发与分析工具 (tools/)

工具	职责
chunk_analyzer.py	切片质量分析（覆盖率、重叠度、语义完整性）
chunk_metrics.py	切片指标统计（长度分布、数量汇总）
chunk_report.py	切片报告生成（可视化分析报告）
llm_evaluator.py	LLM 评估器（基于大模型的检索质量评估）
export_chunks.py	导出切片（导出为 JSON/CSV 格式）
clean_vector_store.py	清理向量库（移除孤立向量、回收空间）
rebuild_pdf_vectors.py	重建 PDF 向量（强制重新索引指定文档）
upload_test_files.py	上传测试文件（自动化测试数据准备）

---

十、部署配置 (deploy/)

文件	职责
Dockerfile	开发环境 Docker 镜像构建
Dockerfile.prod	生产环境 Docker 镜像构建（多阶段构建，精简体积）
docker-compose.yml	开发环境容器编排
docker-compose.prod.yml	生产环境容器编排（含 Nginx、Gunicorn）
gunicorn.conf.py	Gunicorn 配置（worker 数量、超时、日志）
nginx.conf	Nginx 反向代理配置（负载均衡、静态文件、SSE 支持）
wsgi.py	WSGI 入口（Gunicorn 启动点）

---

十一、文件存储服务 (storage/)

模块	职责
file_fetcher.py	文件获取（从远程/本地获取文件）
file_provider.py	文件提供（统一文件访问接口）

---

数据库文件说明

文件名	主要功能	详细文档
data/rag_core.db	会话管理、用户反馈、FAQ	数据库设计文档.md
data/knowledge.db	知识库同步、文档哈希、纲要缓存、版本管理	数据库设计文档.md
knowledge/vector_store/	多向量库存储（ChromaDB + BM25）	多向量库实现权限划分.md

---

运行命令

# ✨ 推荐方式 - 新入口
python main.py                  # 启动 API 服务（端口 5001）
python main.py --port 8080      # 指定端口

# 旧入口（仍可用）
python main.py                  # 启动统一网关与大模型 API 服务
python scripts/test_rag_questions.py  # 自动化问答自评估测试
python scripts/rebuild_multi_kb.py    # 强制重建各个部门/集合维度的知识库

---

相关文档

• API接口文档.md - REST API 详细说明
• 数据库设计文档.md - 所有数据库结构
• 认证与权限配置指南.md - 网关认证说明
• 多向量库实现权限划分.md - 权限架构说明

---

最后更新

• 文档版本：v7.0.0
• 更新时间：2026-06-04
• 主要更新：
  • 版本号从 v6.1.0 升级至 v7.0.0
  • core/ 模块：补充 Agentic 细粒度拆分模块（agentic_base/search/answer/citation/context/query/media/quality/meta）、intent_analyzer、query_decomposer、query_expansion、mmr、cache、semantic_cache、adaptive_topk、llm_budget、llm_utils、status_codes、constants
  • knowledge/ 模块：补充 base、collection、document、document_versions、search、permission、processing、chunk、index、cleanup、lazy_enhance
  • services/ 模块：移除 audit.py、user_info.py（仅保留 session.py、feedback.py、outline.py）
  • api/ 模块：移除 graph_routes.py、question_routes.py、outline_routes.py；补充 response_utils.py
  • exam_pkg/ 模块：更新为 generator.py、grader.py、manager.py、local_db.py、api.py（移除 analysis.py、question_hook.py）
  • 图谱模块 (graph/) 已完全移除
  • 新增 repositories/ 模块（session_repo、sqlite_session_repo、stateless_session_repo）
  • 新增 tools/ 模块（chunk_analyzer、chunk_metrics、chunk_report、llm_evaluator、export_chunks 等）
  • 新增 deploy/ 部署配置（Dockerfile.prod、docker-compose.prod.yml、gunicorn.conf.py、nginx.conf、wsgi.py）
  • 新增 storage/ 文件存储服务（file_fetcher、file_provider）