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

# 开发与系统模块说明

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

## 第一部分：开发文档体系

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

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

> **API 接口文档**: 详见 [后端对接规范.md](./后端对接规范.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](./后端对接规范.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 环境准备

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

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

### 5.2 配置文件

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

```python
# config.py - 必需配置

# LLM API（必需）
DASHSCOPE_API_KEY = "your-api-key"
DASHSCOPE_BASE_URL = "https://token-plan-cn.xiaomimimo.com/v1"
DASHSCOPE_MODEL = "mimo-v2.5"              # 文本模型
VLM_MODEL = "mimo-v2.5"                    # 视觉模型（图片描述）

# 兼容变量
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 启动服务

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

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

### 6.2 同步知识库

```powershell
# 通过 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](./后端对接规范.md) - API 接口规范（主要）
- [数据库设计文档.md](./数据库设计文档.md) - 数据库结构
- [RAG系统完整指南.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
- 可选模块按需加载

**使用方式**：
```python
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()` | 简化调用接口 |

**使用方式**：
```python
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 融合结果

**使用方式**：
```python
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` | 知识库同步、文档版本、纲要缓存 |

**使用方式**：
```python
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` - 会话管理

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

**主要功能**：
- 会话创建与管理
- 消息历史存储
- 上下文压缩
- 会话过期清理

**使用方式**：
```python
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](./数据库设计文档.md) |
| `data/knowledge.db` | 知识库同步、文档哈希、纲要缓存、版本管理 | [数据库设计文档.md](./数据库设计文档.md) |
| `knowledge/vector_store/` | 多向量库存储（ChromaDB + BM25） | [多向量库实现权限划分.md](./多向量库实现权限划分.md) |

---

## 运行命令

```powershell
# ✨ 推荐方式 - 新入口
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](./API接口文档.md) - REST API 详细说明
- [数据库设计文档.md](./数据库设计文档.md) - 所有数据库结构
- [认证与权限配置指南.md](./认证与权限配置指南.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）