jhzhang/rag
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(readme): 更新 README 至 v7.0.0，反映云端 Reranker、Docker 部署、性能优化等当前状态

Browse Source
This commit is contained in:
lacerate551
2026-06-04 17:45:56 +08:00
parent 100d1a06eb
commit a1a0814633
1 changed files with 334 additions and 419 deletions
Download Patch File Download Diff File Expand all files Collapse all files

717
README.md
View File

@@ -1,108 +1,108 @@
# RAG Agent - 模块化知识库问答系统 # RAG Agent - 模块化知识库问答系统
基于本地向量模型 + Chroma向量数据库 + Neo4j知识图谱 + Qwen API 的智能知识库问答系统，支持双模式对话、Agentic RAG 和 Graph RAG。 基于本地向量模型 + Chroma 向量数据库 + 云端 Reranker + Qwen API 的智能知识库问答系统，支持 Agentic RAG 多源检索、意图分析、混合检索与多样性去重。
> **最新版本**: v6.5.0 (枚举查询优化、开发前端界面、数据库连接分离) > **最新版本**: v7.0.0（云端 Reranker、性能优化、Agentic 引擎拆分、Docker 生产部署）
## 运行模式
本项目支持两种运行模式：
| 模式 | 说明 | 前端 | 适用场景 |
|------|------|------|----------|
| **生产环境** | 通过后端网关注入用户认证，提供 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) ### v7.0.0（当前版本）
- **状态码系统**：统一 API 响应格式，新增 `status_code` 字段便于后端判断处理状态（10xx 处理中、20xx 成功、40xx 客户端错误、50xx 服务端错误）
- **MMR 去重优化**：支持高精度版（语义向量）和轻量版（文本相似度）双模式切换
- **查询扩展增强**：新增查询扩展器、语义缓存、意图分析器
- **部署稳定性**：Gunicorn gthread 模式修复心跳超时问题，Docker shm_size 优化
### v6.2.0 特性 - **云端 Reranker**：接入 DashScope qwen3-rerank API 替代本地 CrossEncoder，CPU 服务器上重排序耗时从 ~8s 降至 <1s
- **Docker 部署方案**：新增完整 Docker 部署配置（Dockerfile、docker-compose、nginx） - **MMR 双模式去重**：支持语义向量（高精度）和文本 Jaccard 相似度（轻量）两种模式，轻量模式在 CPU 环境节省 ~36s
- **会话管理重构**：引入 Repository 模式，支持无状态/SQLite 双模式会话存储 - **意图分析加速**：独立 INTENT_MODEL 配置，使用 qwen-turbo 将意图分析从 ~12s 降至 ~2s
- **查询增强优化**：新增自适应 TopK、查询分解器、缓存层、LLM 预算管理 - **VLM 图片理解**：集成 qwen-vl-plus 视觉语言模型，支持文档内图片的语义描述与上下文融合
- **配置管理优化**：配置文件模板化（config.example.py、mineru.json.template、.env.production） - **Agentic 引擎模块化拆分**：从单一 agentic.py 拆分为 search / answer / citation / context / query / media / quality / meta 八个子模块
- **文档完善**：新增 API 对接规范、MinerU 部署指南、企业文档更新方案 - **Docker 生产部署**：完整的 Dockerfile + docker-compose + Gunicorn + nginx 配置，支持一键部署
- **多模型协同配置**：LLM / 意图分析 / VLM / Reranker 分别配置独立模型，按场景选择最优性价比
### 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 特性 - **混合检索**：向量检索 + BM25 关键词检索，RRF 融合排序
- **多向量库与细粒度权限控制**：全面重构向量库底层，基于公共知识库(`public_kb`)和各部门隔离的子知识库(`dept_xxx`)实现物理阻断，通过网关注入进行 Role/Department 鉴权 - **云端重排序**：DashScope qwen3-rerank 或本地 BGE-reranker（ONNX 加速），可切换
- **文档生命周期与版本差异引擎**：引入文档全生命周期跟踪和 MD5 哈希监控差异引擎，文档废止或更新时自动分析关联考题的连带影响 - **MMR 多样性去重**：最大边际相关性算法，防止同一文档片段重复占位
- **本地化自治出题与批卷系统**：建立独立的本地出卷、题库存储系统与题库分析系统，支持脱离工作流进行溯源追踪与本地打分 - **意图分析器**：自动识别查询类型（直接回答 / 知识库检索 / 枚举查询），优化检索策略
- **问答质量闭环与纲要生成**：支持记录用户点赞/点踩动作与追问形成本地 FAQ 闭环；使用大模型自动化提取文档大纲及关联推荐 - **查询扩展与分解**：同义词扩展、复杂查询自动分解
- **全新解析与分块器**：集成结构化 PDF 解析(ODL解析)与 Excel 深度解析扩展，引入智能语义切块算法提升检索精准度 - **自适应 TopK**：根据置信度动态调整返回结果数
- **上下文扩展**：枚举 / 条款类问题自动扩展相邻切片，保证上下文连贯
- **语义缓存**：相似查询复用结果，减少重复 LLM 调用
- **多向量库隔离**：按部门 / 权限隔离的独立向量库，支持物理阻断
- **文档生命周期管理**：MD5 哈希差异引擎，文档更新时自动分析影响
- **引用溯源**：返回结果包含 chunk_index、来源文件、页码、bbox 等定位信息，支持前端跳转
### v4.x 特性 ### 支持的文档格式
- **v4.2.0**: 出题系统完善，试卷生成/审核/批阅完整流程
- **v4.1.0**: 前端日志面板，实时显示 Agent 思考过程
- **v4.0.0**: Graph RAG，Neo4j 图数据库存储实体关系，多跳推理查询
### Agentic RAG 核心能力 PDF、Word（.docx）、Excel（.xlsx）、TXT、图片提取（MinerU 解析器）
- **知识库检索**：向量检索 + BM25 + Rerank
- **网络搜索**：实时信息自动搜索（需配置 SERPER_API_KEY）
- **图谱检索**：实体关系推理、多跳查询
- **Agent 决策**：动态决定检索、改写、分解等操作
- **多源融合**：智能处理知识库、网络、图谱内容
### 基础功能 ## 项目结构
- 支持多种文档格式：PDF、Word(.docx)、Excel(.xlsx)、TXT、图片提取
- 本地向量模型：BGE-base-zh-v1.5
- 本地向量数据库：Chroma
- 精确元数据记录：页码、章节、表格、行列号等
- 增量更新：无需每次完全重建
## 项目结构（模块化）
``` ```
rag-agent/ rag-agent/
├── main.py # ✨ 统一启动入口（推荐） ├── main.py # 统一启动入口
├── config.py # API 配置（需自行创建） ├── config.py # 全局配置（环境变量驱动）
├── config.example.py # API 配置模板 ├── config.example.py # 配置模板
├── requirements.txt # 依赖列表 ├── requirements.txt # 开发依赖
├── requirements-prod.txt # 生产环境精简依赖
│ │
├── core/ # RAG 核心引擎 ├── core/ # RAG 核心引擎
│ ├── agentic.py # Agentic RAG 智能问答引擎 │ ├── engine.py # 检索引擎（模型加载、混合检索、Rerank）
│ ├── engine.py # 检索引擎核心 │ ├── agentic.py # Agentic RAG 入口
│ ├── bm25_index.py # BM25 关键词检索 │ ├── agentic_base.py # 基类与公共逻辑
│ ├── chunker.py # 语义分块器 │ ├── agentic_search.py # 检索策略（知识库 / 网络 / 图谱）
│ ├── agentic_answer.py # 回答生成
│ ├── agentic_citation.py # 引用构建与溯源
│ ├── agentic_context.py # 上下文构建
│ ├── agentic_query.py # 查询预处理
│ ├── agentic_media.py # 多媒体（图片）处理
│ ├── agentic_quality.py # 质量评估
│ ├── agentic_meta.py # 元数据管理
│ ├── intent_analyzer.py # 意图分析器
│ ├── query_classifier.py # 查询分类器 │ ├── query_classifier.py # 查询分类器
│ ├── quality_assessor.py # 质量评估器 │ ├── query_expansion.py # 查询扩展
│ ├── query_decomposer.py # 查询分解
│ ├── bm25_index.py # BM25 索引
│ ├── mmr.py # MMR 多样性去重
│ ├── chunker.py # 语义分块器
│ ├── adaptive_topk.py # 自适应 TopK
│ ├── cache.py # 查询结果缓存
│ ├── semantic_cache.py # 语义缓存
│ ├── confidence_gate.py # 置信度门控 │ ├── confidence_gate.py # 置信度门控
│ ├── quality_assessor.py # 质量评估器
│ ├── reasoning_reflector.py # 推理反思器 │ ├── reasoning_reflector.py # 推理反思器
│ └── loop_guard.py # 循环防护器 │ ├── loop_guard.py # 循环防护
│ ├── llm_budget.py # LLM 调用预算管理
│ ├── llm_utils.py # LLM 调用工具
│ ├── status_codes.py # 统一状态码
│ └── constants.py # 常量定义
│
├── api/ # API 路由层
│ ├── __init__.py # Flask 应用工厂
│ ├── chat_routes.py # 聊天与 RAG 问答
│ ├── document_routes.py # 文档管理与预览
│ ├── kb_routes.py # 知识库管理
│ ├── sync_routes.py # 文档同步
│ ├── session_routes.py # 会话管理
│ ├── feedback_routes.py # 反馈闭环
│ ├── image_routes.py # 图片处理
│ ├── audit_routes.py # 审计日志
│ ├── auth_routes.py # 认证
│ └── response_utils.py # 响应工具函数
│
├── knowledge/ # 知识库管理
│ ├── manager.py # 多向量库管理器
│ ├── router.py # 知识库路由（权限匹配）
│ ├── document.py # 文档切片操作
│ ├── collection.py # Collection 管理
│ ├── search.py # 向量检索
│ ├── permission.py # 权限控制
│ ├── sync.py # 文件同步
│ ├── processing.py # 文档处理管线
│ ├── chunk.py # 切片数据结构
│ ├── index.py # 索引管理
│ ├── document_versions.py # 文档版本差异
│ ├── cleanup.py # 清理服务
│ ├── lazy_enhance.py # 懒加载增强
│ └── vector_store/ # 向量存储目录
│ │
├── parsers/ # 文档解析器 ├── parsers/ # 文档解析器
│ ├── mineru_parser.py # MinerU 统一解析（PDF/DOCX/PPTX/图片） │ ├── mineru_parser.py # MinerU 统一解析（PDF/DOCX/PPTX/图片）
@@ -111,60 +111,54 @@ rag-agent/
│ ├── txt_parser.py # TXT 文本解析 │ ├── txt_parser.py # TXT 文本解析
│ └── image_extractor.py # 图片提取器 │ └── image_extractor.py # 图片提取器
│ │
├── knowledge/ # 知识库管理 ├── repositories/ # 数据仓储层
│ ├── manager.py # 多向量库管理器 │ ├── session_repo.py # 会话仓储接口
│ ├── router.py # 知识库路由器 │ ├── sqlite_session_repo.py # SQLite 实现
│ ├── sync.py # 同步服务 │ └── stateless_session_repo.py # 无状态实现
│ ├── lifecycle.py # 文档生命周期
│ ├── diff.py # 文档差异分析
│ └── vector_store/ # 向量存储目录
│
├── exam_pkg/ # 考试系统
│ ├── manager.py # 出题与批卷管理
│ ├── api.py # Flask Blueprint
│ ├── analysis.py # 考试分析
│ ├── local_db.py # 本地题库
│ └── question_hook.py # 题目维护钩子
│ │
├── services/ # 业务服务 ├── services/ # 业务服务
│ ├── session.py # 会话管理 │ ├── session.py # 会话管理
│ ├── audit.py # 审计日志
│ ├── feedback.py # 反馈质量闭环 │ ├── feedback.py # 反馈质量闭环
│ ├── outline.py # 纲要生成与推荐 │ └── outline.py # 纲要生成与推荐
│ └── user_info.py # 用户信息服务
│ │
├── auth/ # 认证与安全 ├── auth/ # 认证与安全
│ ├── gateway.py # 网关认证 │ ├── gateway.py # 网关认证
│ └── security.py # 输入/输出安全 │ └── security.py # 输入 / 输出安全
│ │
├── api/ # API 路由层 ├── exam_pkg/ # 出题系统
│ ├── __init__.py # Flask 应用工厂 │ ├── manager.py # 出题管理
│ ├── chat_routes.py # 聊天路由 │ ├── generator.py # 试卷生成器
│ ├── document_routes.py # 文档管理路由 │ ├── grader.py # 自动批阅
│ ├── kb_routes.py # 知识库路由 │ ├── api.py # Flask Blueprint
│ ├── sync_routes.py # 同步路由 │ └── local_db.py # 本地题库
│ ├── session_routes.py # 会话路由 │
│ ├── feedback_routes.py # 反馈路由 ├── tools/ # 分析与运维工具
│ ├── outline_routes.py # 纲要路由 │ ├── chunk_analyzer.py # 切片质量分析
│ ├── question_routes.py # 题目路由 │ ├── chunk_metrics.py # 切片度量指标
│ ├── audit_routes.py # 审计路由 │ ├── chunk_report.py # 切片报告生成
│ ├── graph_routes.py # 图谱路由 │ ├── llm_evaluator.py # LLM 评估器
│ ├── image_routes.py # 图片路由 │ └── export_chunks.py # 切片导出
│ └── auth_routes.py # 认证路由 │
├── deploy/ # 部署配置
│ ├── Dockerfile.prod # 生产环境 Dockerfile
│ ├── docker-compose.prod.yml # 生产环境 compose
│ ├── gunicorn.conf.py # Gunicorn 配置
│ ├── nginx.conf # Nginx 反向代理
│ └── wsgi.py # WSGI 入口
│ │
├── graph/ # 知识图谱
├── scripts/ # 工具脚本 ├── scripts/ # 工具脚本
├── models/ # 本地模型目录 │ ├── evaluate_rag.py # RAG 效果评估
│ ├── rebuild_multi_kb.py # 重建多向量库
│ ├── migrate_*.py # 数据迁移脚本
│ └── test_*.sh / test_*.py # 测试脚本
│
├── docs/ # 项目文档
├── documents/ # 知识库文档目录 ├── documents/ # 知识库文档目录
├── models/ # 本地模型目录
├── data/ # SQLite 数据库 ├── data/ # SQLite 数据库
├── chat-ui/ # 生产前端（静态 HTML） ├── chat-ui/ # 生产前端（静态 HTML）
├── dev-ui/ # 开发前端（Vue3 + Naive UI） ├── dev-ui/ # 开发前端（Vue3 + Naive UI）
├── tests/ # 测试 └── tests/ # 单元测试
├── docs/ # 文档
├── venv/ # 虚拟环境
│
├── rag_api_server.py # ⚠️ 旧入口（兼容层）
└── rag_demo.py # ⚠️ 旧入口（兼容层）
``` ```
## 快速开始 ## 快速开始
@@ -172,8 +166,8 @@ rag-agent/
### 1. 克隆仓库 ### 1. 克隆仓库
```bash ```bash
git clone https://github.com/lacerate551-dev/RAG_damo.git git clone https://git.njtobaccosales.top/jhzhang/rag.git
cd RAG_damo cd rag
``` ```
### 2. 创建虚拟环境 ### 2. 创建虚拟环境
@@ -181,13 +175,10 @@ cd RAG_damo
```bash ```bash
python -m venv venv python -m venv venv
# Windows PowerShell # Windows
venv\Scripts\activate venv\Scripts\activate
# Windows Git Bash # Linux / macOS
source venv/Scripts/activate
# Linux/macOS
source venv/bin/activate source venv/bin/activate
``` ```
@@ -197,352 +188,276 @@ source venv/bin/activate
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
``` ```
Graph RAG 额外依赖： ### 4. 下载向量模型
```bash
pip install neo4j -i https://pypi.tuna.tsinghua.edu.cn/simple
```
### 4. 下载模型
本项目使用两个模型：
| 模型 | 用途 | 大小 | 是否必需 | | 模型 | 用途 | 大小 | 是否必需 |
|------|------|------|----------| |------|------|------|----------|
| BGE-base-zh-v1.5 | 向量编码 | ~400MB | **必需** | | BGE-base-zh-v1.5 | 向量编码 | ~400MB | 必需 |
| BGE-reranker-base | 结果重排序 | ~280MB | 可选（首次运行自动下载） | | BGE-reranker-base | 本地重排序 | ~280MB | 可选（使用云端 Reranker 时不需要） |
```bash ```bash
# 创建模型目录
mkdir models mkdir models
# 下载向量模型
huggingface-cli download BAAI/bge-base-zh-v1.5 --local-dir ./models/bge-base-zh-v1.5 huggingface-cli download BAAI/bge-base-zh-v1.5 --local-dir ./models/bge-base-zh-v1.5
``` ```
### 5. 配置API密钥 ### 5. 配置环境变量
```bash ```bash
cp config.example.py config.py cp config.example.py config.py
# 编辑 config.py，填入你的 API Key # 编辑 config.py 或创建 .env 文件
``` ```
配置文件内容： 关键配置项（通过环境变量或 `.env` 文件设置）：
```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 ```bash
# 使用 Docker 启动 Neo4j # ---- LLM 模型 ----
docker run -d \ DASHSCOPE_API_KEY=sk-your-api-key
--name neo4j \ DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
-p 7474:7474 -p 7687:7687 \ DASHSCOPE_MODEL=qwen3.6-flash # 文本生成模型
-e NEO4J_AUTH=neo4j/password123 \ RAG_CHAT_MODEL=qwen3.6-flash # RAG 对话模型（可与上面相同）
-v neo4j_data:/data \ INTENT_MODEL=qwen-turbo # 意图分析模型（轻量快速）
neo4j:latest VLM_MODEL=qwen-vl-plus # 视觉语言模型
# 访问 Neo4j Browser: http://localhost:7474 # ---- 云端 Reranker（推荐）----
RERANK_BACKEND=cloud # local / cloud / fallback
RERANK_CLOUD_API_KEY=sk-your-api-key
RERANK_CLOUD_MODEL=qwen3-rerank
RERANK_CLOUD_BASE_URL=https://dashscope.aliyuncs.com/compatible-api/v1/reranks
# ---- 性能调优 ----
MMR_USE_EMBEDDING=false # CPU 环境建议 false（文本相似度，快）
RERANK_USE_ONNX=true # 本地 Reranker 时启用 ONNX 加速
# ---- MinerU 解析 ----
MINERU_API_TOKEN=your-token # MinerU 在线 API Token
``` ```
### 7. 准备知识库文档 ### 6. 准备知识库文档
将文档放入 `documents/` 目录，支持 PDF、Word(.docx)、Excel(.xlsx)、TXT 格式。 将文档放入 `documents/` 目录，支持 PDF、Word（.docx）、Excel（.xlsx）、TXT 格式。
### 8. 构建知识库 ### 7. 启动服务
```bash ```bash
# 激活虚拟环境后运行 # 开发模式
python rag_demo.py --rebuild python main.py # 默认端口 5001
# 构建知识图谱（需要 Neo4j）
python graph_build.py
```
### 9. 启动服务
```bash
# ✨ 推荐方式 - 新入口
python main.py # 启动 API 服务（端口 5001）
python main.py --port 8080 # 指定端口 python main.py --port 8080 # 指定端口
# 旧入口（仍可用） # 生产模式（通过 Gunicorn）
python rag_api_server.py # 启动 API 服务 gunicorn -c deploy/gunicorn.conf.py deploy.wsgi:app
``` ```
服务启动后： 服务启动后访问 `http://localhost:5001`。
- API 地址：http://localhost:5001
- 前端页面：打开 `chat-ui/index.html`
## 使用方法 ## Docker 部署
### 双模式对话 生产环境推荐使用 Docker 部署，完整配置在 `deploy/` 目录下。
| 模式 | 端点 | 特点 | ### 构建与启动
|------|------|------|
| 智能聊天 | `/chat` | 支持网络搜索，适合实时问题（天气、新闻等） |
| 知识库问答 | `/rag` | 知识库 + 网络 + 图谱多源检索，专业准确 |
前端界面可点击按钮切换模式。
### Graph RAG API
```bash ```bash
# 图谱检索 cd /opt/rag-agent
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 docker-compose -f deploy/docker-compose.prod.yml up -d --build
# 重建图谱索引 # 仅重启（不重建镜像）
curl -X POST http://localhost:5001/graph/build docker-compose -f deploy/docker-compose.prod.yml restart
# 查看日志
docker-compose -f deploy/docker-compose.prod.yml logs -f rag-service
``` ```
### 命令行问答 ### 环境变量管理
生产环境通过 `deploy/.env.production` 文件注入环境变量，docker-compose 使用 `env_file` 加载。修改配置后需执行 `up -d`（不是 `restart`）才能重新读取环境变量。
### 数据卷挂载
容器内代码在镜像中，以下目录通过挂载持久化：
- `knowledge/vector_store` — 向量数据库
- `documents/` — 知识库文档
- `models/` — 本地模型文件
- `data/` — SQLite 数据库
- `.data/` — 运行时缓存
### 热更新代码（不重建镜像）
对于小幅代码修改，可以通过 `docker cp` + `restart` 快速更新：
```bash ```bash
# 知识库问答 # 复制修改后的文件到容器
python -c "from core.agentic import AgenticRAG; rag = AgenticRAG(); print(rag.query('请假流程是什么'))" docker cp ./core/engine.py rag-service:/app/core/engine.py
# 交互模式 # 重启容器使生效
python rag_demo.py docker-compose -f deploy/docker-compose.prod.yml restart
# 单次问答
python rag_demo.py "请假流程是什么"
``` ```
交互模式命令： 注意：`up -d --build` 会重建镜像，覆盖所有 docker cp 的修改。
| 命令 | 说明 | ## 配置管理
所有配置项在 `config.py` 中定义，通过环境变量注入。以下是生产环境推荐配置：
### 模型选型建议
| 组件 | 推荐模型 | 选型理由 |
|------|----------|----------|
| 文本生成 | qwen3.6-flash | 速度快（~24s 生成）、1024K 上下文、性价比高 |
| 意图分析 | qwen-turbo | 轻量快速（~2s），任务简单不需要强模型 |
| 视觉语言 | qwen-vl-plus | 图片描述质量足够，支持缓存 |
| 重排序 | qwen3-rerank（云端） | 替代本地 CrossEncoder，CPU 环境显著提升 |
| 向量编码 | BGE-base-zh-v1.5（本地） | 中文语义质量高，~400MB |
### 性能参考
典型 RAG 查询耗时分解（4vCPU / 8GB 内存服务器）：
| 阶段 | 耗时 |
|------|------| |------|------|
| `/quit` | 退出程序 | | 意图分析 | ~2s |
| `/kb 问题` | 仅知识库检索 | | 向量 + BM25 检索 | ~1s |
| `/web 问题` | 强制网络搜索 | | 云端 Reranker | ~0.5s |
| VLM 图片描述（缓存命中） | ~0.1s |
| LLM 生成回答 | ~24s |
| **总计** | **~28s** |
## 出题系统 ## API 接口
### 功能概述 ### 核心接口
出题系统支持智能生成试卷、审核管理、学生答题和自动批阅。
### 使用流程
```
生成试卷 → 管理员审核 → 学生答题 → 自动批阅 → 生成报告
(草稿) (通过/驳回) (已通过试卷) (系统评分)
```
### 前端界面
访问 `chat-ui/exam.html` 进入出题系统：
1. **生成试卷**：输入主题、题目数量、难度等参数
2. **审核试卷**：管理员审核草稿试卷（审核通过后才能用于考试）
3. **批阅试卷**：选择已通过的试卷，学生作答后系统自动批阅
4. **批阅报告**：查看历史批阅记录和成绩
### API 调用示例
```bash
# 生成试卷
curl -X POST http://localhost:5001/exam/generate \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"topic": "Python基础", "choice_count": 5, "name": "Python入门测试"}'
# 审核通过
curl -X POST http://localhost:5001/exam/<exam_id>/review \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"action": "approve"}'
# 批阅试卷
curl -X POST http://localhost:5001/exam/<exam_id>/grade \
-H "Authorization: Bearer <token>" \
-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 接口文档
### 基础接口
| 接口 | 方法 | 说明 | | 接口 | 方法 | 说明 |
|------|------|------| |------|------|------|
| `/rag` | POST | 知识库问答（多源检索 + 引用溯源） |
| `/chat` | POST | 智能聊天（支持网络搜索） | | `/chat` | POST | 智能聊天（支持网络搜索） |
| `/rag` | POST | 知识库问答（多源检索） | | `/search` | POST | 混合检索（供外部系统调用） |
| `/search` | POST | 混合检索（供 Dify 调用） |
| `/sessions` | GET | 获取会话列表 |
| `/history/<id>` | GET | 获取会话历史 |
| `/session/<id>` | DELETE | 删除会话 |
| `/health` | GET | 健康检查 | | `/health` | GET | 健康检查 |
### Graph RAG 接口 ### 文档管理
| 接口 | 方法 | 说明 |
|------|------|------|
| `/graph/search` | POST | 图谱检索 |
| `/graph/build` | POST | 重建图谱索引 |
| `/graph/stats` | GET | 获取图谱统计 |
### 出题系统接口
| 接口 | 方法 | 说明 |
|------|------|------|
| `/exam/generate` | POST | 生成试卷 |
| `/exam/list` | GET | 获取试卷列表 |
| `/exam/<id>` | GET/PUT/DELETE | 试卷 CRUD |
| `/exam/<id>/review` | POST | 审核试卷（管理员） |
| `/exam/<id>/grade` | POST | 批阅试卷 |
| `/exam/report/<id>` | GET | 获取批阅报告 |
| `/exam/report/list` | GET | 批阅报告列表 |
### 文档管理接口
| 接口 | 方法 | 说明 | | 接口 | 方法 | 说明 |
|------|------|------| |------|------|------|
| `/documents/upload` | POST | 上传文件到知识库 | | `/documents/upload` | POST | 上传文件到知识库 |
| `/documents/list` | GET | 获取文档列表 | | `/documents/list` | GET | 获取文档列表 |
| `/documents/<path>` | DELETE | 删除文档 | | `/documents/<path>` | DELETE | 删除文档 |
| `/documents/<collection>/<source>/preview` | GET | 文档预览与切片定位 |
详细 API 文档请参考 [API接口文档](docs/API接口文档.md) ### 引用跳转数据流
`/rag` 返回的 `citations` 数组包含引用定位信息：
```json
{
"answer": "...",
"citations": [
{
"chunk_index": 5,
"source": "规章制度.pdf",
"collection": "public_kb",
"page": 12,
"bbox": [100, 200, 500, 300],
"content": "切片内容预览（最多300字）..."
}
]
}
```
前端可通过 `GET /documents/{collection}/{source}/preview?chunk_index=N&context=3` 获取完整切片文本用于高亮定位。详细说明参见 [RAG 引用跳转-前端实现说明](docs/RAG引用跳转-前端实现说明.md)。
### 其他接口
| 接口 | 方法 | 说明 |
|------|------|------|
| `/sessions` | GET | 获取会话列表 |
| `/history/<id>` | GET | 获取会话历史 |
| `/session/<id>` | DELETE | 删除会话 |
| `/kb/list` | GET | 获取知识库列表 |
| `/kb/sync` | POST | 触发文档同步 |
| `/feedback` | POST | 提交反馈（点赞 / 点踩） |
## 技术架构
```
┌──────────────────────────────────────────────────────────────┐
│ 前端 (chat-ui / dev-ui) │
│ HTML + CSS + JS | Vue3 + Naive UI │
└────────────────────────────┬─────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ API 路由层 (api/) │
│ chat | document | kb | sync | session | feedback │
└────────────────────────────┬─────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Agentic RAG 引擎 (core/) │
│ │
│ 意图分析 ──→ 查询预处理 ──→ 混合检索 ──→ 云端Rerank │
│ │ │ │ │
│ │ 向量检索 ──┐ │ MMR去重 ──┘ │
│ │ BM25检索 ──┤ RRF │
│ │ ┘ 融合 │
│ │ │
│ └──→ 上下文构建 ──→ 自适应TopK ──→ LLM生成 ──→ 引用溯源 │
└────────────────────────────┬─────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ 数据层 │
│ ChromaDB | BM25索引 | FAISS(语义缓存) | SQLite │
│ │
│ 文档解析器 (parsers/) │
│ MinerU: PDF / DOCX / PPTX / 图片 │
│ Excel: Pandas 管道 | TXT: 纯文本 │
└──────────────────────────────────────────────────────────────┘
```
## 依赖库 ## 依赖库
| 库名 | 用途 | | 库名 | 用途 |
|------|------| |------|------|
| flask / gunicorn | Web 框架与 WSGI 服务器 |
| chromadb | 向量数据库 | | chromadb | 向量数据库 |
| sentence-transformers | 向量模型 | | sentence-transformers | 向量编码（BGE-base-zh-v1.5） |
| openai | 大模型API | | rank-bm25 / jieba | BM25 关键词检索与中文分词 |
| neo4j | 图数据库 | | faiss-cpu | FAISS 向量索引（语义缓存） |
| pdfplumber | PDF解析 | | openai | LLM API 客户端（兼容 DashScope） |
| python-docx | Word解析 | | optimum[onnxruntime] | 本地 Reranker ONNX 加速 |
| openpyxl | Excel解析 | | mineru | 文档解析（PDF / DOCX / PPTX / 图片） |
| flask | API服务 | | pandas / openpyxl | Excel 解析 |
| flask-cors | 跨域支持 | | langchain-text-splitters | 语义分块 |
| rank_bm25 | BM25检索 | | watchdog | 文档变更监控 |
| jieba | 中文分词 | | python-dotenv | 环境变量管理 |
| requests | HTTP请求 |
## 常见问题 ## 常见问题
### Q: Neo4j 连接失败？ **Q: docker-compose restart 后新环境变量不生效？**
1. 确认 Docker 已启动 Neo4j 容器 `restart` 只是重启现有容器，不会重新读取 `.env.production`。修改环境变量后必须使用 `docker-compose up -d` 重建容器。
2. 访问 http://localhost:7474 检查 Neo4j Browser
3. 检查 config.py 中的 NEO4J_PASSWORD 是否正确
### Q: Graph RAG 未启用？ **Q: 云端 Reranker 超时或报错？**
确保 config.py 中设置： 检查 `RERANK_CLOUD_API_KEY` 和 `RERANK_CLOUD_BASE_URL` 配置，确认 DashScope API 可用。可设置 `RERANK_BACKEND=fallback` 实现云端优先、失败回退本地。
```python
USE_GRAPH_RAG = True
```
### Q: 网络搜索不工作？ **Q: MMR 去重很慢？**
1. 确认 config.py 中配置了 SERPER_API_KEY CPU 环境下设置 `MMR_USE_EMBEDDING=false`，使用文本 Jaccard 相似度替代语义向量计算，速度提升显著。
2. 注册地址: https://serper.dev/
### Q: 向量模型加载失败？ **Q: MinerU 解析失败？**
确保 `models/bge-base-zh-v1.5/` 目录包含必要文件。 配置 `MINERU_API_TOKEN` 使用 MinerU 在线 API 作为备选。设置 `MINERU_PREFER_ONLINE=true` 优先使用在线解析（效果更好）。
## 版本历史
| 版本 | 更新内容 |
|------|----------|
| **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 接口说明、认证、出题系统 - [API 与后端对接规范](docs/API与后端对接规范.md)
- [开发文档](docs/开发文档.md) - 系统架构、技术栈、部署指南 - [RAG 引用跳转-前端实现说明](docs/RAG引用跳转-前端实现说明.md)
- [模块说明](docs/模块说明.md) - 各模块职责与接口 - [RAG 数据流程详解](docs/RAG数据流程详解.md)
- [数据库设计文档](docs/数据库设计文档.md) - 数据库表结构设计 - [MinerU 模型部署指南](docs/MinerU模型部署指南.md)
- [多向量库实现权限划分](docs/多向量库实现权限划分.md) - 权限系统技术说明 - [多向量库权限划分](docs/多向量库实现权限划分.md)
- [多源信息融合指南](docs/多源信息融合指南.md) - 知识库与网络搜索融合策略 - [数据库设计文档](docs/数据库设计文档.md)
- [认证与权限配置指南](docs/认证与权限配置指南.md)
## License ## License