# RAG Agent - 模块化知识库问答系统 基于本地向量模型 + Chroma向量数据库 + Neo4j知识图谱 + Qwen API 的智能知识库问答系统，支持双模式对话、Agentic RAG 和 Graph RAG。 > **最新版本**: v6.5.0 (枚举查询优化、开发前端界面、数据库连接分离) ## 运行模式 本项目支持两种运行模式： | 模式 | 说明 | 前端 | 适用场景 | |------|------|------|----------| | **生产环境** | 通过后端网关注入用户认证，提供 API 服务 | chat-ui/ | 企业部署、API 对接 | | **开发环境** | 本地模拟用户，支持个人知识库使用 | dev-ui/ | 个人使用、开发测试 | ### 环境切换 ```bash # 生产环境（默认） export DEV_MODE=false python main.py # 开发环境 export DEV_MODE=true # 默认值 python main.py ``` 开发环境特性： - 支持模拟用户登录（`Authorization: Bearer mock-token-admin`） - 额外的调试接口（`/debug/scan`、`/auth/users` 等） - 完整的 Vue3 前端界面（dev-ui/） ## 功能特性 ### 最新特性 (v6.3.0) - **状态码系统**：统一 API 响应格式，新增 `status_code` 字段便于后端判断处理状态（10xx 处理中、20xx 成功、40xx 客户端错误、50xx 服务端错误） - **MMR 去重优化**：支持高精度版（语义向量）和轻量版（文本相似度）双模式切换 - **查询扩展增强**：新增查询扩展器、语义缓存、意图分析器 - **部署稳定性**：Gunicorn gthread 模式修复心跳超时问题，Docker shm_size 优化 ### v6.2.0 特性 - **Docker 部署方案**：新增完整 Docker 部署配置（Dockerfile、docker-compose、nginx） - **会话管理重构**：引入 Repository 模式，支持无状态/SQLite 双模式会话存储 - **查询增强优化**：新增自适应 TopK、查询分解器、缓存层、LLM 预算管理 - **配置管理优化**：配置文件模板化（config.example.py、mineru.json.template、.env.production） - **文档完善**：新增 API 对接规范、MinerU 部署指南、企业文档更新方案 ### v6.0.0 特性 - **模块化架构重构**：代码从单文件拆分为清晰的模块结构，提升可维护性 - `core/` 核心引擎：查询分类、质量评估、置信度门控、推理反思、循环防护 - `api/` 路由模块：11 个独立路由文件，职责单一 - `parsers/` 文档解析：支持 PDF/Word/Excel/TXT/图片提取 - `knowledge/` 知识库管理：多向量库、同步、生命周期 - `services/` 业务服务：会话、反馈、审计、纲要 - `auth/` 认证安全：网关认证、输入输出安全 - `exam_pkg/` 考试系统：出题、批卷、分析 - **图片提取功能**：新增 `image_extractor.py`，支持从文档中提取图片 - **前端界面优化**：chat-ui 样式更新，交互体验提升 - **新增统一入口**：`main.py` 作为推荐启动入口 ### v5.0.0 特性 - **多向量库与细粒度权限控制**：全面重构向量库底层，基于公共知识库(`public_kb`)和各部门隔离的子知识库(`dept_xxx`)实现物理阻断，通过网关注入进行 Role/Department 鉴权 - **文档生命周期与版本差异引擎**：引入文档全生命周期跟踪和 MD5 哈希监控差异引擎，文档废止或更新时自动分析关联考题的连带影响 - **本地化自治出题与批卷系统**：建立独立的本地出卷、题库存储系统与题库分析系统，支持脱离工作流进行溯源追踪与本地打分 - **问答质量闭环与纲要生成**：支持记录用户点赞/点踩动作与追问形成本地 FAQ 闭环；使用大模型自动化提取文档大纲及关联推荐 - **全新解析与分块器**：集成结构化 PDF 解析(ODL解析)与 Excel 深度解析扩展，引入智能语义切块算法提升检索精准度 ### v4.x 特性 - **v4.2.0**: 出题系统完善，试卷生成/审核/批阅完整流程 - **v4.1.0**: 前端日志面板，实时显示 Agent 思考过程 - **v4.0.0**: Graph RAG，Neo4j 图数据库存储实体关系，多跳推理查询 ### Agentic RAG 核心能力 - **知识库检索**：向量检索 + BM25 + Rerank - **网络搜索**：实时信息自动搜索（需配置 SERPER_API_KEY） - **图谱检索**：实体关系推理、多跳查询 - **Agent 决策**：动态决定检索、改写、分解等操作 - **多源融合**：智能处理知识库、网络、图谱内容 ### 基础功能 - 支持多种文档格式：PDF、Word(.docx)、Excel(.xlsx)、TXT、图片提取 - 本地向量模型：BGE-base-zh-v1.5 - 本地向量数据库：Chroma - 精确元数据记录：页码、章节、表格、行列号等 - 增量更新：无需每次完全重建 ## 项目结构（模块化） ``` rag-agent/ ├── main.py # ✨ 统一启动入口（推荐） ├── config.py # API 配置（需自行创建） ├── config.example.py # API 配置模板 ├── requirements.txt # 依赖列表 │ ├── core/ # RAG 核心引擎 │ ├── agentic.py # Agentic RAG 智能问答引擎 │ ├── engine.py # 检索引擎核心 │ ├── bm25_index.py # BM25 关键词检索 │ ├── chunker.py # 语义分块器 │ ├── query_classifier.py # 查询分类器 │ ├── quality_assessor.py # 质量评估器 │ ├── confidence_gate.py # 置信度门控 │ ├── reasoning_reflector.py # 推理反思器 │ └── loop_guard.py # 循环防护器 │ ├── parsers/ # 文档解析器 │ ├── 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/ # 知识库管理 │ ├── manager.py # 多向量库管理器 │ ├── router.py # 知识库路由器 │ ├── sync.py # 同步服务 │ ├── lifecycle.py # 文档生命周期 │ ├── diff.py # 文档差异分析 │ └── vector_store/ # 向量存储目录 │ ├── exam_pkg/ # 考试系统 │ ├── manager.py # 出题与批卷管理 │ ├── api.py # Flask Blueprint │ ├── analysis.py # 考试分析 │ ├── local_db.py # 本地题库 │ └── question_hook.py # 题目维护钩子 │ ├── services/ # 业务服务 │ ├── session.py # 会话管理 │ ├── audit.py # 审计日志 │ ├── feedback.py # 反馈质量闭环 │ ├── outline.py # 纲要生成与推荐 │ └── user_info.py # 用户信息服务 │ ├── auth/ # 认证与安全 │ ├── gateway.py # 网关认证 │ └── security.py # 输入/输出安全 │ ├── api/ # API 路由层 │ ├── __init__.py # Flask 应用工厂 │ ├── chat_routes.py # 聊天路由 │ ├── document_routes.py # 文档管理路由 │ ├── kb_routes.py # 知识库路由 │ ├── sync_routes.py # 同步路由 │ ├── session_routes.py # 会话路由 │ ├── feedback_routes.py # 反馈路由 │ ├── outline_routes.py # 纲要路由 │ ├── question_routes.py # 题目路由 │ ├── audit_routes.py # 审计路由 │ ├── graph_routes.py # 图谱路由 │ ├── image_routes.py # 图片路由 │ └── auth_routes.py # 认证路由 │ ├── graph/ # 知识图谱 ├── scripts/ # 工具脚本 ├── models/ # 本地模型目录 ├── documents/ # 知识库文档目录 ├── data/ # SQLite 数据库 ├── chat-ui/ # 生产前端（静态 HTML） ├── dev-ui/ # 开发前端（Vue3 + Naive UI） ├── tests/ # 测试 ├── docs/ # 文档 ├── venv/ # 虚拟环境 │ ├── rag_api_server.py # ⚠️ 旧入口（兼容层） └── rag_demo.py # ⚠️ 旧入口（兼容层） ``` ## 快速开始 ### 1. 克隆仓库 ```bash git clone https://github.com/lacerate551-dev/RAG_damo.git cd RAG_damo ``` ### 2. 创建虚拟环境 ```bash python -m venv venv # Windows PowerShell venv\Scripts\activate # Windows Git Bash source venv/Scripts/activate # Linux/macOS source venv/bin/activate ``` ### 3. 安装依赖 ```bash pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple ``` Graph RAG 额外依赖： ```bash pip install neo4j -i https://pypi.tuna.tsinghua.edu.cn/simple ``` ### 4. 下载模型 本项目使用两个模型： | 模型 | 用途 | 大小 | 是否必需 | |------|------|------|----------| | BGE-base-zh-v1.5 | 向量编码 | ~400MB | **必需** | | BGE-reranker-base | 结果重排序 | ~280MB | 可选（首次运行自动下载） | ```bash # 创建模型目录 mkdir models # 下载向量模型 huggingface-cli download BAAI/bge-base-zh-v1.5 --local-dir ./models/bge-base-zh-v1.5 ``` ### 5. 配置API密钥 ```bash cp config.example.py config.py # 编辑 config.py，填入你的 API Key ``` 配置文件内容： ```python # 通义千问API配置（必需） DASHSCOPE_API_KEY = "your-dashscope-api-key" DASHSCOPE_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1" DASHSCOPE_MODEL = "qwen3.5-plus" # Serper API（可选，用于网络搜索） SERPER_API_KEY = "your-serper-api-key" # Neo4j 图数据库配置（可选，用于 Graph RAG） NEO4J_URI = "bolt://localhost:7687" NEO4J_USER = "neo4j" NEO4J_PASSWORD = "password123" USE_GRAPH_RAG = True # 是否启用图谱检索 # 兼容旧变量名 API_KEY = DASHSCOPE_API_KEY BASE_URL = DASHSCOPE_BASE_URL MODEL = DASHSCOPE_MODEL ``` ### 6. 启动 Neo4j（可选，用于 Graph RAG） ```bash # 使用 Docker 启动 Neo4j docker run -d \ --name neo4j \ -p 7474:7474 -p 7687:7687 \ -e NEO4J_AUTH=neo4j/password123 \ -v neo4j_data:/data \ neo4j:latest # 访问 Neo4j Browser: http://localhost:7474 ``` ### 7. 准备知识库文档 将文档放入 `documents/` 目录，支持 PDF、Word(.docx)、Excel(.xlsx)、TXT 格式。 ### 8. 构建知识库 ```bash # 激活虚拟环境后运行 python rag_demo.py --rebuild # 构建知识图谱（需要 Neo4j） python graph_build.py ``` ### 9. 启动服务 ```bash # ✨ 推荐方式 - 新入口 python main.py # 启动 API 服务（端口 5001） python main.py --port 8080 # 指定端口 # 旧入口（仍可用） python rag_api_server.py # 启动 API 服务 ``` 服务启动后： - API 地址：http://localhost:5001 - 前端页面：打开 `chat-ui/index.html` ## 使用方法 ### 双模式对话 | 模式 | 端点 | 特点 | |------|------|------| | 智能聊天 | `/chat` | 支持网络搜索，适合实时问题（天气、新闻等） | | 知识库问答 | `/rag` | 知识库 + 网络 + 图谱多源检索，专业准确 | 前端界面可点击按钮切换模式。 ### Graph RAG API ```bash # 图谱检索 curl -X POST http://localhost:5001/graph/search \ -H "Content-Type: application/json" \ -d '{"query": "信息技术部负责什么？", "top_k": 5, "depth": 2}' # 获取图谱统计 curl http://localhost:5001/graph/stats # 重建图谱索引 curl -X POST http://localhost:5001/graph/build ``` ### 命令行问答 ```bash # 知识库问答 python -c "from core.agentic import AgenticRAG; rag = AgenticRAG(); print(rag.query('请假流程是什么'))" # 交互模式 python rag_demo.py # 单次问答 python rag_demo.py "请假流程是什么" ``` 交互模式命令： | 命令 | 说明 | |------|------| | `/quit` | 退出程序 | | `/kb 问题` | 仅知识库检索 | | `/web 问题` | 强制网络搜索 | ## 出题系统 ### 功能概述 出题系统支持智能生成试卷、审核管理、学生答题和自动批阅。 ### 使用流程 ``` 生成试卷 → 管理员审核 → 学生答题 → 自动批阅 → 生成报告 (草稿) (通过/驳回) (已通过试卷) (系统评分) ``` ### 前端界面 访问 `chat-ui/exam.html` 进入出题系统： 1. **生成试卷**：输入主题、题目数量、难度等参数 2. **审核试卷**：管理员审核草稿试卷（审核通过后才能用于考试） 3. **批阅试卷**：选择已通过的试卷，学生作答后系统自动批阅 4. **批阅报告**：查看历史批阅记录和成绩 ### API 调用示例 ```bash # 生成试卷 curl -X POST http://localhost:5001/exam/generate \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"topic": "Python基础", "choice_count": 5, "name": "Python入门测试"}' # 审核通过 curl -X POST http://localhost:5001/exam//review \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"action": "approve"}' # 批阅试卷 curl -X POST http://localhost:5001/exam//grade \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"student_name": "张三", "answers": {"choice_1": "A", "blank_1": "答案"}}' ``` ## 技术架构 ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ 前端 (chat-ui) │ │ HTML + CSS + JavaScript │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ 智能聊天 │ │ 知识库问答 │ │ 图谱状态显示 │ │ │ │ +网络搜索 │ │ +图谱检索 │ │ 节点/关系/类型 │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ API 路由层 (api/) │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ chat_routes │ │ kb_routes │ │ graph_routes │ │ │ │ /chat │ │ /kb │ │ /graph/* │ │ │ └──────┬──────┘ └──────┬──────┘ └───────────┬─────────────┘ │ └──────────┼──────────────────┼───────────────────────┼───────────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ 核心引擎层 (core/) │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ agentic.py │ │ engine.py │ │ Graph RAG │ │ │ │ Agent决策 │ │ 检索引擎 │ │ 实体提取 + 图谱查询 │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │ │ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────────────────┐ │ │ │ query_ │ │ quality_ │ │confidence_│ │ reasoning_reflector │ │ │ │ classifier│ │ assessor │ │ gate │ │ 推理反思器 │ │ │ └───────────┘ └───────────┘ └───────────┘ └───────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ 数据层 │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ ChromaDB │ │ BM25索引 │ │ Neo4j │ │ │ │ 向量数据库 │ │ 关键词检索 │ │ 知识图谱 │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ 文档解析器 (parsers/) │ │ │ │ PDF / Word / Excel / TXT / 图片提取 │ │ │ └─────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘ ``` ## API 接口文档 ### 基础接口 | 接口 | 方法 | 说明 | |------|------|------| | `/chat` | POST | 智能聊天（支持网络搜索） | | `/rag` | POST | 知识库问答（多源检索） | | `/search` | POST | 混合检索（供 Dify 调用） | | `/sessions` | GET | 获取会话列表 | | `/history/` | GET | 获取会话历史 | | `/session/` | DELETE | 删除会话 | | `/health` | GET | 健康检查 | ### Graph RAG 接口 | 接口 | 方法 | 说明 | |------|------|------| | `/graph/search` | POST | 图谱检索 | | `/graph/build` | POST | 重建图谱索引 | | `/graph/stats` | GET | 获取图谱统计 | ### 出题系统接口 | 接口 | 方法 | 说明 | |------|------|------| | `/exam/generate` | POST | 生成试卷 | | `/exam/list` | GET | 获取试卷列表 | | `/exam/` | GET/PUT/DELETE | 试卷 CRUD | | `/exam//review` | POST | 审核试卷（管理员） | | `/exam//grade` | POST | 批阅试卷 | | `/exam/report/` | GET | 获取批阅报告 | | `/exam/report/list` | GET | 批阅报告列表 | ### 文档管理接口 | 接口 | 方法 | 说明 | |------|------|------| | `/documents/upload` | POST | 上传文件到知识库 | | `/documents/list` | GET | 获取文档列表 | | `/documents/` | DELETE | 删除文档 | 详细 API 文档请参考 [API接口文档](docs/API接口文档.md) ## 依赖库 | 库名 | 用途 | |------|------| | chromadb | 向量数据库 | | sentence-transformers | 向量模型 | | openai | 大模型API | | neo4j | 图数据库 | | pdfplumber | PDF解析 | | python-docx | Word解析 | | openpyxl | Excel解析 | | flask | API服务 | | flask-cors | 跨域支持 | | rank_bm25 | BM25检索 | | jieba | 中文分词 | | requests | HTTP请求 | ## 常见问题 ### Q: Neo4j 连接失败？ 1. 确认 Docker 已启动 Neo4j 容器 2. 访问 http://localhost:7474 检查 Neo4j Browser 3. 检查 config.py 中的 NEO4J_PASSWORD 是否正确 ### Q: Graph RAG 未启用？ 确保 config.py 中设置： ```python USE_GRAPH_RAG = True ``` ### Q: 网络搜索不工作？ 1. 确认 config.py 中配置了 SERPER_API_KEY 2. 注册地址: https://serper.dev/ ### Q: 向量模型加载失败？ 确保 `models/bge-base-zh-v1.5/` 目录包含必要文件。 ## 版本历史 | 版本 | 更新内容 | |------|----------| | **v6.5.0** | 枚举查询优化：上下文连续性保护、查询类型识别；开发前端界面(dev-ui)；数据库连接分离；审计日志接口 | | v6.3.0 | 状态码系统：统一 API 响应格式(status_code)、MMR 双模式去重、查询扩展增强、Gunicorn gthread 稳定性修复 | | v6.2.0 | 部署优化版：Docker 部署方案、会话管理 Repository 重构、查询增强（自适应TopK/分解器/缓存）、配置模板化 | | v6.1.0 | 部署准备版：表格摘要懒加载优化、MinerU解析器统一、出题系统增强、新增后端对接规范文档 | | v6.0.0 | 模块化架构重构：代码拆分为 core/api/parsers/knowledge/services/auth/exam_pkg 模块；新增图片提取功能；前端优化；统一入口 main.py | | v5.0.0 | 多向量库权限控制、文档生命周期、本地出卷系统、ODL解析、Semantic Chunker | | v4.2.0 | 出题系统完善：试卷审核流程优化、前端界面修复 | | v4.1.0 | 前端日志面板：实时显示 Agent 思考过程，日志持久化 | | v4.0.0 | Graph RAG：Neo4j 知识图谱、实体提取、多跳推理 | | v3.0.0 | 双模式 RAG 系统：普通聊天/知识库问答，会话管理 | | v2.1.0 | Dify 智能出题系统集成 | | v1.1.0 | RAG 幻觉优化：混合检索 + Rerank + 置信度 | | v1.0.0 | 初始版本：RAG 本地知识库问答系统 | ## 文档 - [API接口文档](docs/API接口文档.md) - 完整 API 接口说明、认证、出题系统 - [开发文档](docs/开发文档.md) - 系统架构、技术栈、部署指南 - [模块说明](docs/模块说明.md) - 各模块职责与接口 - [数据库设计文档](docs/数据库设计文档.md) - 数据库表结构设计 - [多向量库实现权限划分](docs/多向量库实现权限划分.md) - 权限系统技术说明 - [多源信息融合指南](docs/多源信息融合指南.md) - 知识库与网络搜索融合策略 ## License MIT