diff --git a/README.md b/README.md index b5f465f..eb75765 100644 --- a/README.md +++ b/README.md @@ -1,170 +1,164 @@ # RAG Agent - 模块化知识库问答系统 -基于本地向量模型 + Chroma向量数据库 + Neo4j知识图谱 + Qwen API 的智能知识库问答系统，支持双模式对话、Agentic RAG 和 Graph RAG。 +基于本地向量模型 + Chroma 向量数据库 + 云端 Reranker + Qwen API 的智能知识库问答系统，支持 Agentic 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/） +> **最新版本**: v7.0.0（云端 Reranker、性能优化、Agentic 引擎拆分、Docker 生产部署） ## 功能特性 -### 最新特性 (v6.3.0) -- **状态码系统**：统一 API 响应格式，新增 `status_code` 字段便于后端判断处理状态（10xx 处理中、20xx 成功、40xx 客户端错误、50xx 服务端错误） -- **MMR 去重优化**：支持高精度版（语义向量）和轻量版（文本相似度）双模式切换 -- **查询扩展增强**：新增查询扩展器、语义缓存、意图分析器 -- **部署稳定性**：Gunicorn gthread 模式修复心跳超时问题，Docker shm_size 优化 +### v7.0.0（当前版本） -### v6.2.0 特性 -- **Docker 部署方案**：新增完整 Docker 部署配置（Dockerfile、docker-compose、nginx） -- **会话管理重构**：引入 Repository 模式，支持无状态/SQLite 双模式会话存储 -- **查询增强优化**：新增自适应 TopK、查询分解器、缓存层、LLM 预算管理 -- **配置管理优化**：配置文件模板化（config.example.py、mineru.json.template、.env.production） -- **文档完善**：新增 API 对接规范、MinerU 部署指南、企业文档更新方案 +- **云端 Reranker**：接入 DashScope qwen3-rerank API 替代本地 CrossEncoder，CPU 服务器上重排序耗时从 ~8s 降至 <1s +- **MMR 双模式去重**：支持语义向量（高精度）和文本 Jaccard 相似度（轻量）两种模式，轻量模式在 CPU 环境节省 ~36s +- **意图分析加速**：独立 INTENT_MODEL 配置，使用 qwen-turbo 将意图分析从 ~12s 降至 ~2s +- **VLM 图片理解**：集成 qwen-vl-plus 视觉语言模型，支持文档内图片的语义描述与上下文融合 +- **Agentic 引擎模块化拆分**：从单一 agentic.py 拆分为 search / answer / citation / context / query / media / quality / meta 八个子模块 +- **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 特性 -- **多向量库与细粒度权限控制**：全面重构向量库底层，基于公共知识库(`public_kb`)和各部门隔离的子知识库(`dept_xxx`)实现物理阻断，通过网关注入进行 Role/Department 鉴权 -- **文档生命周期与版本差异引擎**：引入文档全生命周期跟踪和 MD5 哈希监控差异引擎，文档废止或更新时自动分析关联考题的连带影响 -- **本地化自治出题与批卷系统**：建立独立的本地出卷、题库存储系统与题库分析系统，支持脱离工作流进行溯源追踪与本地打分 -- **问答质量闭环与纲要生成**：支持记录用户点赞/点踩动作与追问形成本地 FAQ 闭环；使用大模型自动化提取文档大纲及关联推荐 -- **全新解析与分块器**：集成结构化 PDF 解析(ODL解析)与 Excel 深度解析扩展，引入智能语义切块算法提升检索精准度 +- **混合检索**：向量检索 + BM25 关键词检索，RRF 融合排序 +- **云端重排序**：DashScope qwen3-rerank 或本地 BGE-reranker（ONNX 加速），可切换 +- **MMR 多样性去重**：最大边际相关性算法，防止同一文档片段重复占位 +- **意图分析器**：自动识别查询类型（直接回答 / 知识库检索 / 枚举查询），优化检索策略 +- **查询扩展与分解**：同义词扩展、复杂查询自动分解 +- **自适应 TopK**：根据置信度动态调整返回结果数 +- **上下文扩展**：枚举 / 条款类问题自动扩展相邻切片，保证上下文连贯 +- **语义缓存**：相似查询复用结果，减少重复 LLM 调用 +- **多向量库隔离**：按部门 / 权限隔离的独立向量库，支持物理阻断 +- **文档生命周期管理**：MD5 哈希差异引擎，文档更新时自动分析影响 +- **引用溯源**：返回结果包含 chunk_index、来源文件、页码、bbox 等定位信息，支持前端跳转 -### 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、图片提取（MinerU 解析器） -### 基础功能 -- 支持多种文档格式：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 # 依赖列表 +├── main.py # 统一启动入口 +├── config.py # 全局配置（环境变量驱动） +├── config.example.py # 配置模板 +├── requirements.txt # 开发依赖 +├── requirements-prod.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 # 循环防护器 +├── core/ # RAG 核心引擎 +│ ├── engine.py # 检索引擎（模型加载、混合检索、Rerank） +│ ├── agentic.py # Agentic RAG 入口 +│ ├── agentic_base.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_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 # 置信度门控 +│ ├── quality_assessor.py # 质量评估器 +│ ├── reasoning_reflector.py # 推理反思器 +│ ├── loop_guard.py # 循环防护 +│ ├── llm_budget.py # LLM 调用预算管理 +│ ├── llm_utils.py # LLM 调用工具 +│ ├── status_codes.py # 统一状态码 +│ └── constants.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 # 图片提取器 +├── 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 # 知识库路由器 -│ ├── sync.py # 同步服务 -│ ├── lifecycle.py # 文档生命周期 -│ ├── diff.py # 文档差异分析 -│ └── vector_store/ # 向量存储目录 +├── 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/ # 向量存储目录 │ -├── exam_pkg/ # 考试系统 -│ ├── manager.py # 出题与批卷管理 -│ ├── api.py # Flask Blueprint -│ ├── analysis.py # 考试分析 -│ ├── local_db.py # 本地题库 -│ └── question_hook.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 # 图片提取器 │ -├── services/ # 业务服务 -│ ├── session.py # 会话管理 -│ ├── audit.py # 审计日志 -│ ├── feedback.py # 反馈质量闭环 -│ ├── outline.py # 纲要生成与推荐 -│ └── user_info.py # 用户信息服务 +├── repositories/ # 数据仓储层 +│ ├── session_repo.py # 会话仓储接口 +│ ├── sqlite_session_repo.py # SQLite 实现 +│ └── stateless_session_repo.py # 无状态实现 │ -├── auth/ # 认证与安全 -│ ├── gateway.py # 网关认证 -│ └── security.py # 输入/输出安全 +├── services/ # 业务服务 +│ ├── session.py # 会话管理 +│ ├── feedback.py # 反馈质量闭环 +│ └── outline.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 # 认证路由 +├── auth/ # 认证与安全 +│ ├── gateway.py # 网关认证 +│ └── security.py # 输入 / 输出安全 │ -├── graph/ # 知识图谱 -├── scripts/ # 工具脚本 -├── models/ # 本地模型目录 -├── documents/ # 知识库文档目录 -├── data/ # SQLite 数据库 -├── chat-ui/ # 生产前端（静态 HTML） -├── dev-ui/ # 开发前端（Vue3 + Naive UI） -├── tests/ # 测试 -├── docs/ # 文档 -├── venv/ # 虚拟环境 +├── exam_pkg/ # 出题系统 +│ ├── manager.py # 出题管理 +│ ├── generator.py # 试卷生成器 +│ ├── grader.py # 自动批阅 +│ ├── api.py # Flask Blueprint +│ └── local_db.py # 本地题库 │ -├── rag_api_server.py # ⚠️ 旧入口（兼容层） -└── rag_demo.py # ⚠️ 旧入口（兼容层） +├── tools/ # 分析与运维工具 +│ ├── chunk_analyzer.py # 切片质量分析 +│ ├── chunk_metrics.py # 切片度量指标 +│ ├── chunk_report.py # 切片报告生成 +│ ├── llm_evaluator.py # LLM 评估器 +│ └── export_chunks.py # 切片导出 +│ +├── deploy/ # 部署配置 +│ ├── Dockerfile.prod # 生产环境 Dockerfile +│ ├── docker-compose.prod.yml # 生产环境 compose +│ ├── gunicorn.conf.py # Gunicorn 配置 +│ ├── nginx.conf # Nginx 反向代理 +│ └── wsgi.py # WSGI 入口 +│ +├── scripts/ # 工具脚本 +│ ├── evaluate_rag.py # RAG 效果评估 +│ ├── rebuild_multi_kb.py # 重建多向量库 +│ ├── migrate_*.py # 数据迁移脚本 +│ └── test_*.sh / test_*.py # 测试脚本 +│ +├── docs/ # 项目文档 +├── documents/ # 知识库文档目录 +├── models/ # 本地模型目录 +├── data/ # SQLite 数据库 +├── chat-ui/ # 生产前端（静态 HTML） +├── dev-ui/ # 开发前端（Vue3 + Naive UI） +└── tests/ # 单元测试 ``` ## 快速开始 @@ -172,8 +166,8 @@ rag-agent/ ### 1. 克隆仓库 ```bash -git clone https://github.com/lacerate551-dev/RAG_damo.git -cd RAG_damo +git clone https://git.njtobaccosales.top/jhzhang/rag.git +cd rag ``` ### 2. 创建虚拟环境 @@ -181,13 +175,10 @@ cd RAG_damo ```bash python -m venv venv -# Windows PowerShell +# Windows venv\Scripts\activate -# Windows Git Bash -source venv/Scripts/activate - -# Linux/macOS +# Linux / macOS 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 ``` -Graph RAG 额外依赖： -```bash -pip install neo4j -i https://pypi.tuna.tsinghua.edu.cn/simple -``` - -### 4. 下载模型 - -本项目使用两个模型： +### 4. 下载向量模型 | 模型 | 用途 | 大小 | 是否必需 | |------|------|------|----------| -| BGE-base-zh-v1.5 | 向量编码 | ~400MB | **必需** | -| BGE-reranker-base | 结果重排序 | ~280MB | 可选（首次运行自动下载） | +| BGE-base-zh-v1.5 | 向量编码 | ~400MB | 必需 | +| BGE-reranker-base | 本地重排序 | ~280MB | 可选（使用云端 Reranker 时不需要） | ```bash -# 创建模型目录 mkdir models - -# 下载向量模型 huggingface-cli download BAAI/bge-base-zh-v1.5 --local-dir ./models/bge-base-zh-v1.5 ``` -### 5. 配置API密钥 +### 5. 配置环境变量 ```bash cp config.example.py config.py -# 编辑 config.py，填入你的 API Key +# 编辑 config.py 或创建 .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） +关键配置项（通过环境变量或 `.env` 文件设置）： ```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 +# ---- LLM 模型 ---- +DASHSCOPE_API_KEY=sk-your-api-key +DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 +DASHSCOPE_MODEL=qwen3.6-flash # 文本生成模型 +RAG_CHAT_MODEL=qwen3.6-flash # RAG 对话模型（可与上面相同） +INTENT_MODEL=qwen-turbo # 意图分析模型（轻量快速） +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 -# 激活虚拟环境后运行 -python rag_demo.py --rebuild - -# 构建知识图谱（需要 Neo4j） -python graph_build.py -``` - -### 9. 启动服务 - -```bash -# ✨ 推荐方式 - 新入口 -python main.py # 启动 API 服务（端口 5001） +# 开发模式 +python main.py # 默认端口 5001 python main.py --port 8080 # 指定端口 -# 旧入口（仍可用） -python rag_api_server.py # 启动 API 服务 +# 生产模式（通过 Gunicorn） +gunicorn -c deploy/gunicorn.conf.py deploy.wsgi:app ``` -服务启动后： -- API 地址：http://localhost:5001 -- 前端页面：打开 `chat-ui/index.html` +服务启动后访问 `http://localhost:5001`。 -## 使用方法 +## Docker 部署 -### 双模式对话 +生产环境推荐使用 Docker 部署，完整配置在 `deploy/` 目录下。 -| 模式 | 端点 | 特点 | -|------|------|------| -| 智能聊天 | `/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}' +cd /opt/rag-agent -# 获取图谱统计 -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 -# 知识库问答 -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 - -# 单次问答 -python rag_demo.py "请假流程是什么" +# 重启容器使生效 +docker-compose -f deploy/docker-compose.prod.yml restart ``` -交互模式命令： +注意：`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` | 退出程序 | -| `/kb 问题` | 仅知识库检索 | -| `/web 问题` | 强制网络搜索 | +| 意图分析 | ~2s | +| 向量 + BM25 检索 | ~1s | +| 云端 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 " \ - -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 接口文档 - -### 基础接口 +### 核心接口 | 接口 | 方法 | 说明 | |------|------|------| +| `/rag` | POST | 知识库问答（多源检索 + 引用溯源） | | `/chat` | POST | 智能聊天（支持网络搜索） | -| `/rag` | POST | 知识库问答（多源检索） | -| `/search` | POST | 混合检索（供 Dify 调用） | -| `/sessions` | GET | 获取会话列表 | -| `/history/` | GET | 获取会话历史 | -| `/session/` | DELETE | 删除会话 | +| `/search` | POST | 混合检索（供外部系统调用） | | `/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 | 删除文档 | +| `/documents///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/` | GET | 获取会话历史 | +| `/session/` | 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 | 向量数据库 | -| sentence-transformers | 向量模型 | -| openai | 大模型API | -| neo4j | 图数据库 | -| pdfplumber | PDF解析 | -| python-docx | Word解析 | -| openpyxl | Excel解析 | -| flask | API服务 | -| flask-cors | 跨域支持 | -| rank_bm25 | BM25检索 | -| jieba | 中文分词 | -| requests | HTTP请求 | +| sentence-transformers | 向量编码（BGE-base-zh-v1.5） | +| rank-bm25 / jieba | BM25 关键词检索与中文分词 | +| faiss-cpu | FAISS 向量索引（语义缓存） | +| openai | LLM API 客户端（兼容 DashScope） | +| optimum[onnxruntime] | 本地 Reranker ONNX 加速 | +| mineru | 文档解析（PDF / DOCX / PPTX / 图片） | +| pandas / openpyxl | Excel 解析 | +| langchain-text-splitters | 语义分块 | +| watchdog | 文档变更监控 | +| python-dotenv | 环境变量管理 | ## 常见问题 -### Q: Neo4j 连接失败？ +**Q: docker-compose restart 后新环境变量不生效？** -1. 确认 Docker 已启动 Neo4j 容器 -2. 访问 http://localhost:7474 检查 Neo4j Browser -3. 检查 config.py 中的 NEO4J_PASSWORD 是否正确 +`restart` 只是重启现有容器，不会重新读取 `.env.production`。修改环境变量后必须使用 `docker-compose up -d` 重建容器。 -### Q: Graph RAG 未启用？ +**Q: 云端 Reranker 超时或报错？** -确保 config.py 中设置： -```python -USE_GRAPH_RAG = True -``` +检查 `RERANK_CLOUD_API_KEY` 和 `RERANK_CLOUD_BASE_URL` 配置，确认 DashScope API 可用。可设置 `RERANK_BACKEND=fallback` 实现云端优先、失败回退本地。 -### Q: 网络搜索不工作？ +**Q: MMR 去重很慢？** -1. 确认 config.py 中配置了 SERPER_API_KEY -2. 注册地址: https://serper.dev/ +CPU 环境下设置 `MMR_USE_EMBEDDING=false`，使用文本 Jaccard 相似度替代语义向量计算，速度提升显著。 -### Q: 向量模型加载失败？ +**Q: MinerU 解析失败？** -确保 `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 本地知识库问答系统 | +配置 `MINERU_API_TOKEN` 使用 MinerU 在线 API 作为备选。设置 `MINERU_PREFER_ONLINE=true` 优先使用在线解析（效果更好）。 ## 文档 -- [API接口文档](docs/API接口文档.md) - 完整 API 接口说明、认证、出题系统 -- [开发文档](docs/开发文档.md) - 系统架构、技术栈、部署指南 -- [模块说明](docs/模块说明.md) - 各模块职责与接口 -- [数据库设计文档](docs/数据库设计文档.md) - 数据库表结构设计 -- [多向量库实现权限划分](docs/多向量库实现权限划分.md) - 权限系统技术说明 -- [多源信息融合指南](docs/多源信息融合指南.md) - 知识库与网络搜索融合策略 +- [API 与后端对接规范](docs/API与后端对接规范.md) +- [RAG 引用跳转-前端实现说明](docs/RAG引用跳转-前端实现说明.md) +- [RAG 数据流程详解](docs/RAG数据流程详解.md) +- [MinerU 模型部署指南](docs/MinerU模型部署指南.md) +- [多向量库权限划分](docs/多向量库实现权限划分.md) +- [数据库设计文档](docs/数据库设计文档.md) +- [认证与权限配置指南](docs/认证与权限配置指南.md) ## License