Files

lacerate551 100d1a06eb init: RAG 知识库服务初始提交

- 后端 API（Flask + Gunicorn）
- RAG 引擎（混合检索 + 云端 Reranker + 引用溯源）
- 文档解析（MinerU + 多格式支持）
- Docker 生产部署配置
- 排除前端项目、敏感配置、模型文件

2026-06-04 17:35:27 +08:00

39 KiB

Raw Blame History

开发与系统模块说明

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

第一部分：开发文档体系

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

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

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

一、项目概述

1.1 项目定位

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

知识库问答：基于向量检索 + BM25 + Rerank 的混合检索
Agentic RAG：智能问答流程（Query Rewriting、Context Compression、Answer Grounding）
多轮对话：会话历史管理、代词消解
图谱推理：基于 Neo4j 的多跳关系查询（可选）
网络搜索：实时信息获取（可选，需配置 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
│
├── core/                    # RAG 核心引擎
│   ├── agentic.py           #   AgenticRAG 智能问答
│   ├── engine.py            #   检索引擎封装
│   ├── bm25_index.py        #   BM25 索引
│   ├── chunker.py           #   文本分块
│   ├── query_classifier.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              #   同步服务
│
├── services/                # 业务服务
│   ├── session.py           #   会话管理 (SQLite)
│   ├── audit.py             #   审计日志
│   └── feedback.py          #   反馈系统
│
├── auth/                    # 认证与安全
│   ├── gateway.py           #   网关认证 (DEV_MODE mock token)
│   └── security.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 测试面板
│
├── docs/                    # 文档
│   ├── 后端对接规范.md       #   API 接口规范 (主要)
│   ├── 开发文档.md           #   本文档
│   └── ...
│
├── scripts/                 # 工具脚本
│   └── analyze_chunks.py    #   切片分析
│
├── tools/                   # 开发工具
│   └── export_chunks.py     #   导出切片
│
└── exam_pkg/                # 出题系统（可选）
    ├── manager.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 - 数据库结构
模块说明.md - 模块详细说明
Agentic_RAG完整指南.md - Agentic RAG 详解

第二部分：模块规范体系

项目模块说明文档 (v6.1.0)

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

项目架构概览

┌─────────────────────────────────────────────────────────────────────────────┐
│                              API 服务层                                      │
│                            main.py (入口)                                   │
│    (Flask 应用工厂，整合所有 Blueprint，提供 REST API)                        │
└─────────────────────────────────────────────────────────────────────────────┘
         │         │         │         │         │         │         │
         ▼         ▼         ▼         ▼         ▼         ▼         ▼
┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌──────────┐
│ RAG 核心 ││  图谱模块 ││ 出题系统 ││ 安全模块 ││ 同步服务 ││ 反馈闭环 ││ 纲要生成 │
│core/     ││graph/    ││exam_pkg/ ││auth/     ││knowledge/││services/ ││services/ │
│agentic.py││graph_    ││manager.py││gateway.py││sync.py   ││feedback.py││outline.py│
│engine.py ││manager.py││api.py    ││security.py││          ││          ││          │
│bm25_     ││entity_   ││local_db.py││          ││          ││          ││          │
│index.py  ││extractor ││analysis.py││          ││          ││          ││          │
│chunker.py││graph_rag ││question_ ││          ││          ││          ││          │
│          ││graph_    ││hook.py   ││          ││          ││          ││          │
│          ││build.py  ││          ││          ││          ││          ││          │
└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘
     │                                                    │
     ▼                                                    │
┌──────────────────────────┐                              │
│   多向量库管理            │                              │
│ knowledge/manager.py     │                              │
│ knowledge/router.py      │                              │
└──────────────────────────┘                              │
                              ┌─────────────────────┼─────────────────────┐
                              │                     │                     │
                              ▼                     ▼                     ▼
                       ┌──────────┐          ┌──────────┐          ┌──────────┐
                       │会话管理  │          │题库分析  │          │ 审计日志 │
                       │services/ │          │exam_pkg/ │          │services/ │
                       │session.py│          │analysis.py│         │audit.py  │
                       └──────────┘          └──────────┘          └──────────┘

目录结构

项目根目录/
├── main.py                  # ✨ 统一启动入口（推荐）
├── config.py                # API 配置（不提交）
├── config.example.py        # API 配置模板
├── requirements.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
│   ├── graph_routes.py      #   /graph/search, /graph/build, /graph/stats
│   ├── question_routes.py   #   /questions/*, /knowledge-points
│   ├── outline_routes.py    #   /outline/*, /recommend/*
│   ├── feedback_routes.py   #   /feedback/*, /reports/*, /faq/*
│   └── image_routes.py      #   图片相关接口
│
├── core/                    # RAG 核心引擎
│   ├── __init__.py
│   ├── agentic.py           #   AgenticRAG 智能问答
│   ├── engine.py            #   检索引擎封装
│   ├── bm25_index.py        #   BM25 关键词索引
│   ├── chunker.py           #   语义分块器
│   ├── query_classifier.py  #   查询分类器
│   ├── confidence_gate.py   #   置信度门控
│   ├── quality_assessor.py  #   质量评估器
│   ├── reasoning_reflector.py # 推理反思器
│   └── loop_guard.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
│   ├── manager.py           #   多向量库管理器
│   ├── router.py            #   知识库路由器
│   ├── sync.py              #   同步服务
│   ├── lifecycle.py         #   文档生命周期
│   ├── diff.py              #   文档差异分析
│   └── vector_store/        #   向量数据库与BM25索引
│       ├── chroma/          #   ChromaDB存储
│       └── bm25/            #   BM25索引存储
│
├── exam_pkg/                # 考试系统
│   ├── __init__.py
│   ├── manager.py           #   出题与批卷
│   ├── api.py               #   Flask Blueprint (exam_bp)
│   ├── analysis.py          #   考试分析
│   ├── local_db.py          #   本地题库
│   └── question_hook.py     #   题目维护钩子
│
├── services/                # 业务服务
│   ├── __init__.py
│   ├── session.py           #   会话管理
│   ├── audit.py             #   审计日志
│   ├── feedback.py          #   反馈质量闭环
│   ├── outline.py           #   纲要生成与推荐
│   └── user_info.py         #   用户信息服务
│
├── auth/                    # 认证与安全
│   ├── __init__.py
│   ├── gateway.py           #   网关认证
│   └── security.py          #   输入/输出安全
│
├── data/                    # SQLite 数据库
│   ├── __init__.py
│   ├── db.py                #   统一数据访问层
│   ├── rag_core.db          #   核心数据（会话、审计、反馈）
│   ├── knowledge.db         #   知识管理（同步、大纲、版本）
│   └── exam.db              #   出题系统（题目、试卷、批卷）
│
├── graph/                   # 知识图谱
│   ├── __init__.py
│   ├── graph_manager.py     #   Neo4j 图谱管理
│   ├── entity_extractor.py  #   实体提取器
│   ├── graph_rag.py         #   图谱增强检索
│   └── graph_build.py       #   图谱构建工具
│
├── documents/               # 知识库文档目录
├── models/                  # 本地模型目录
├── scripts/                 # 工具脚本
│   ├── migrate_version_status.py  # 版本状态迁移
│   ├── rebuild_multi_kb.py        # 重建多向量库
│   ├── run_exam.py                # 运行考试
│   └── test_rag_questions.py      # RAG问题测试
├── tests/                   # 测试
├── chat-ui/                 # 前端界面
├── 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
`graph_bp`	graph_routes.py	-	/graph/search, /graph/build, /graph/stats
`question_bp`	question_routes.py	-	/questions/*, /knowledge-points
`outline_bp`	outline_routes.py	-	/outline/, /recommend/
`feedback_bp`	feedback_routes.py	-	/feedback/, /reports/, /faq/*
`image_bp`	image_routes.py	-	图片上传、处理相关接口
`exam_bp`	exam_pkg/api.py	/exam	出题系统相关接口

二、核心 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. `core/engine.py` - 检索引擎封装

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

主要功能：

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

5. `core/bm25_index.py` - BM25 索引管理

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

6. `core/query_classifier.py` - 查询分类器

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

7. `core/confidence_gate.py` - 置信度门控

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

8. `core/quality_assessor.py` - 质量评估器

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

9. `core/reasoning_reflector.py` - 推理反思器

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

10. `core/loop_guard.py` - 循环防护

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

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

11. `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)

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

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

主要功能：

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

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

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

四、数据库模块 (data/)

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

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

主要功能：

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

数据库架构：

数据库	主要功能
`rag_core.db`	会话、审计、反馈、FAQ
`knowledge.db`	同步、大纲、文档版本
`exam.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/)

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

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

主要功能：

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

16. `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 数据批卷

17. `exam_pkg/analysis.py` - 题库分析模块

职责：题目与制度文档关联、知识点分析

六、服务模块 (services/)

18. `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)

19. `services/audit.py` - 审计日志

职责：用户操作审计

主要功能：

记录查询日志
记录检索结果
日志查询

20. `services/feedback.py` - 反馈服务

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

21. `services/outline.py` - 纲要生成器

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

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

22. `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`	部门

23. `auth/security.py` - 安全防护

职责：Prompt 注入防护

八、图谱模块 (graph/)

注意：图谱模块为可选功能，需在 config.py 中配置 USE_GRAPH_RAG=True 和 Neo4j 连接。

24. `graph/graph_manager.py` - 图谱管理器

职责：Neo4j 图数据库管理

25. `graph/entity_extractor.py` - 实体提取器

职责：使用 LLM 从文本提取实体和关系

26. `graph/graph_rag.py` - 图谱 RAG

职责：图谱增强检索

27. `graph/graph_build.py` - 图谱构建工具

使用方式：

python -m graph.graph_build --stats
python -m graph.graph_build --file documents/xxx.pdf

数据库文件说明

文件名	主要功能	详细文档
`data/rag_core.db`	会话管理、审计日志、用户反馈、FAQ	数据库设计文档.md
`data/knowledge.db`	知识库同步、文档哈希、纲要缓存、版本管理	数据库设计文档.md
`data/exam.db`	题目存储、试卷管理、批阅记录、分析报告	数据库设计文档.md
`knowledge/vector_store/`	多向量库存储（ChromaDB）	多向量库实现权限划分.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    # 强制重建各个部门/集合维度的知识库

最后更新

文档版本：v6.1.0
更新时间：2026-04-16
主要更新：
- 补充 core/ 目录新增模块（query_classifier、confidence_gate、quality_assessor、reasoning_reflector、loop_guard）
- 补充 api/ 目录新增的 image_routes.py
- 补充 parsers/ 目录新增的 image_extractor.py
- 修正 knowledge/ 目录重复描述，合并 vector_store 子目录说明
- 补充 scripts/ 目录实际存在的脚本文件
- 重新编号所有模块说明章节

39 KiB Raw Blame History Unescape Escape

开发与系统模块说明

第一部分：开发文档体系

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

一、项目概述

1.1 项目定位

1.2 系统架构

1.3 技术栈

二、项目结构

三、Agentic RAG 流程

3.1 完整流程图

3.2 关键配置参数

四、API 接口

核心接口概览

五、开发环境配置

5.1 环境准备

5.2 配置文件

5.3 开发模式特性

六、运行命令

6.1 启动服务

6.2 同步知识库

七、会话管理

7.1 多轮对话流程

7.2 会话相关 API

八、部署指南

8.1 生产环境建议

8.2 职责边界

九、错误码说明

十、相关文档

第二部分：模块规范体系

项目模块说明文档 (v6.1.0)

项目架构概览

目录结构

模块详细说明

一、API 路由层 (api/)

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

2. API Blueprint 分组

二、核心 RAG 模块 (core/)

3. core/agentic.py - Agentic RAG 核心

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

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

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

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

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

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

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

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

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

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

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

四、数据库模块 (data/)

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

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

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

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

17. exam_pkg/analysis.py - 题库分析模块

六、服务模块 (services/)

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

19. services/audit.py - 审计日志

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

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

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

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

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

八、图谱模块 (graph/)

24. graph/graph_manager.py - 图谱管理器

25. graph/entity_extractor.py - 实体提取器

26. graph/graph_rag.py - 图谱 RAG

27. graph/graph_build.py - 图谱构建工具

数据库文件说明

运行命令

相关文档

最后更新

39 KiB

Raw Blame History

1. `api/init.py` - 应用工厂

3. `core/agentic.py` - Agentic RAG 核心

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

5. `core/bm25_index.py` - BM25 索引管理

6. `core/query_classifier.py` - 查询分类器

7. `core/confidence_gate.py` - 置信度门控

8. `core/quality_assessor.py` - 质量评估器

9. `core/reasoning_reflector.py` - 推理反思器

10. `core/loop_guard.py` - 循环防护

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

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

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

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

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

16. `exam_pkg/api.py` - 出题系统 API

17. `exam_pkg/analysis.py` - 题库分析模块

18. `services/session.py` - 会话管理

19. `services/audit.py` - 审计日志

20. `services/feedback.py` - 反馈服务

21. `services/outline.py` - 纲要生成器

22. `auth/gateway.py` - 网关认证

23. `auth/security.py` - 安全防护

24. `graph/graph_manager.py` - 图谱管理器

25. `graph/entity_extractor.py` - 实体提取器

26. `graph/graph_rag.py` - 图谱 RAG

27. `graph/graph_build.py` - 图谱构建工具