README
RAG_AI_READ - 基于 RAG 的个性化智能阅读系统
毕业设计课题：基于检索增强生成（Retrieval-Augmented Generation）的个性化智能阅读系统的设计与实现
项目介绍
本项目是一个结合了大语言模型（LLM）与检索增强生成（RAG）技术的智能文档阅读助手。系统旨在解决传统文档阅读中"信息检索难、长文理解慢"的痛点。通过上传 PDF 文档，用户可以与 AI 进行对话，系统会基于文档内容进行精准回答，并提供智能导读、摘要生成等功能。
核心特性
- 智能解析与切片：支持 PDF 文档上传，自动进行文本归一化与智能分块，支持段落级与语义级两种策略，可插拔切换；内置页眉页脚检测、表格提取（Markdown + 自然语言描述）、Token 感知分块；绑定完整元数据与章节信息
- 混合检索机制：结合稀疏检索（BM25 + jieba 中文分词）与稠密检索，采用 RRF 融合策略，支持查询扩展、上下文扩展（相邻 chunk 拉取）与多字符词元加权，实现更精准的上下文检索
- 检索增强问答：利用检索到的私有领域知识增强大模型的回答能力，杜绝"幻觉"
- 跨语料库 Agentic RAG：支持当前文档、选定文档集、我的全部文档、自动跨库四种检索范围；通过 Corpus Registry、Corpus Router、Query Rewriter、Search Fanout、跨库重排和 Sufficient Context Gate 形成多源检索闭环
- Agentic 智能推理：基于 LangGraph 状态图，LLM 自主决定何时检索、检索什么、拆分子问题、评估充分性、自反思纠错——从"被动回答者"升级为"主动编排者"
- 模块化架构：graph.py 仅负责组装（~185 行），11 个节点拆分到独立模块，NodeContext 依赖注入，AgentConfig 集中配置
- ReAct 循环：LLM 自主调用工具（文档检索、章节浏览、摘要生成），实现多步推理
- 问题自动分解：复杂问题自动拆分为子问题 DAG，依赖关系感知的串行/并行执行；融合对话上下文，多轮对话子问题 Embedding 相似度去重，避免重复检索
- 跨库路由与查询改写：Corpus Router 根据用户可见语料库 metadata 选择目标 corpus，Query Rewriter 为不同 corpus 生成 semantic/keyword/entity/gap_fill 查询
- 跨库检索与重排：复用单库 BM25 + Dense + RRF + MMR，并增加跨库 rank-based 归一化、CrossEncoder 全局重排、source-aware MMR 和结构化引用归一化
- 充分性闸门：Sufficient Context Gate 检查检索片段、草稿答案和缺失维度，驱动补检索、回退或带缺口说明的保守回答
- Token 感知上下文截断：基于 tiktoken 精确计数，相关性降序分配 token 预算，避免关键语义截断丢失
- 迭代检索：检索充分性自动评估，不充分时 Reflector 输出
root_cause精准定位原因（检索不足/合成不佳），驱动增量重新检索而非全量重刷 - 自反思纠错：从事实一致性、问题回应性、表述明确性三个维度自检答案质量
- NLI 幻觉检测：自然语言推理语义级幻觉分析，逐条标记证据支撑状态（支撑/矛盾/不确定）
- 意图自适应检索：LLM 合并复杂度与意图分类（事实查询/概念解释/对比分析/综述摘要/深度分析），动态调节 BM25/Dense 权重与 MMR 参数
- 流式综合生成：子问题并行检索完成后，立即流式输出最终回答，首包响应时间（TTFB）缩短至 3-5 秒
- 语义缓存：基于 Embedding 相似度缓存问答对（阈值 0.92），按用户隔离，24 小时过期
- 持久化 Checkpointer：支持 memory / SQLite / PostgreSQL 三种后端，重启不丢失对话上下文
- 可观测性：节点级延迟、成功率指标收集，便于性能分析
- 外部工具调用：calculator（安全数学计算）、datetime_query（时间查询）、web_search（可选集成）
- 全链路溯源：回答中的每个事实性陈述都带有引用标记，点击可跳转到 PDF 原文对应位置
- 动态难度调整 (DDA)：基于认知负荷指数（CLI）自动调整难度等级，采用鲁棒归一化、Holt 双指数平滑、Kalman 滤波等多重算法
- 用户画像系统：隐式采集阅读行为，构建用户兴趣画像与薄弱知识点，画像驱动检索增强与 Prompt 个性化
- 智能导读 / 思维导图 / 智能笔记 / 交互测验：多维度辅助阅读
- 用户反馈闭环：Agent 回答赞/踩显式反馈，点踩收集原因标签，连续负反馈自动微调检索策略；建立
agent_feedbacks数据库表，支持离线模式分析 - 多用户系统：JWT 认证、bcrypt 密码哈希、用户注册登录、角色管理（admin/user）、数据隔离（user_id 外键）
- 流式响应：后端支持 SSE，实现打字机效果的流畅对话体验
- 后台管理：系统配置、文档管理、历史记录、日志查看、性能指标监控等
- 对话交互增强：语音输入、消息引用回复、对话分支对比、段落级追问、关键词高亮联动、对话摘要生成、快捷短语模板、消息标记置顶、Markdown 导出、输入历史翻页、@提及文档章节
技术栈
前端
- 框架：Vue 3.5 + Vite 7 + TypeScript 严格模式 (JSDoc)
- UI 组件库：Element Plus 2.11（按需导入）
- 状态管理：Pinia 3.0 + Composables
- PDF 渲染：PDF.js 5.5
- 思维导图：simple-mind-map 0.14
- 代码规范：ESLint flat/recommended + Prettier
后端
- Web 框架：FastAPI 0.135
- 大模型编排：LangChain (Community/Core/HuggingFace/OpenAI)
- Agent 编排：LangGraph 1.x（ReAct 循环、多步推理、自反思状态图）
- 中文分词：jieba（BM25 稀疏检索的中文词级分词）
- 数据库：PostgreSQL 18 + SQLAlchemy 2.0 (async) + Alembic
- 向量扩展：pgvector（向量列类型，支持余弦相似度检索）
- 向量数据库：ChromaDB
- Embedding 模型：
Qwen/Qwen3-Embedding-0.6B - Reranker 模型：
Qwen/Qwen3-Reranker-0.6B - LLM 接口：兼容 OpenAI 协议（默认适配 DeepSeek）
快速开始
1. 环境准备
- Python >= 3.10、Node.js >= 20.19、PostgreSQL >= 16（需安装 pgvector 扩展）
2. 数据库部署
createdb -U postgres rag_ai_read
psql -U postgres -d rag_ai_read -c "CREATE EXTENSION IF NOT EXISTS vector;"
3. 后端部署
cd backend
conda create -n rag-env python=3.10 -y && conda activate rag-env
pip install -r requirements.txt
pip install torch --index-url https://download.pytorch.org/whl/cu121 # GPU 可选
python download_model.py
# 配置 .env 文件（见下方配置说明，必须设置 JWT_SECRET_KEY 和 ADMIN_PASSWORD）
alembic upgrade head # 数据库迁移
python main.py # http://127.0.0.1:8000
4. 前端部署
cd frontend
pnpm install && pnpm run dev # http://localhost:5173
配置说明
在 backend/ 目录下创建 .env 文件，核心配置项：
# LLM
MODEL_NAME=deepseek-chat
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_BASE_URL=https://api.deepseek.com
# 轻量大模型（用于复杂度/意图分类等轻量任务，可选，未配置时回退使用主模型）
# LIGHTWEIGHT_MODEL_NAME=deepseek-chat
# LIGHTWEIGHT_OPENAI_BASE_URL=https://api.deepseek.com
# LIGHTWEIGHT_OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
# 数据库
DATABASE_URL=postgresql+asyncpg://postgres:password@localhost:5432/rag_ai_read
# 认证（必须配置）
JWT_SECRET_KEY=your-secret-key-here
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-admin-password
# Agent 模式（可选，默认关闭，开启后启用 Agentic RAG 智能推理）
AGENT_ENABLED=true
# 跨语料库 Agentic RAG（可选，默认关闭，可按阶段、用户和 scope 灰度）
AGENT_ENABLE_CROSS_CORPUS=false
AGENT_CROSS_CORPUS_ROLLOUT_STAGE=off
AGENT_CROSS_CORPUS_ALLOWED_USER_IDS=
AGENT_CROSS_CORPUS_ALLOWED_SCOPES=current_document
完整配置参数说明请参阅 部署指南
项目结构
RAG_AI_READ/
├── backend/ # 后端代码
│ ├── auth/ # 认证授权模块（JWT + bcrypt）
│ │ ├── utils.py # 令牌生成/验证、密码哈希
│ │ ├── dependencies.py # FastAPI 依赖工厂
│ │ └── routers/auth_router.py # 注册/登录/me/改密码 API
│ ├── rag_core/ # RAG 核心模块
│ │ ├── agent/ # Agentic RAG 编排层（LangGraph）
│ │ │ ├── graph.py # 状态图组装（~185 行）
│ │ │ ├── state.py # Agent 状态定义 + create_initial_state()
│ │ │ ├── agent_config.py # AgentConfig 集中配置
│ │ │ ├── agent_service.py # Agent 服务层（流式 SSE + 降级容错）
│ │ │ ├── json_parser.py # 共享 JSON 解析（3 层回退）
│ │ │ ├── checkpoint_utils.py # 持久化 Checkpointer 工厂
│ │ │ ├── semantic_cache.py # Agent 语义缓存
│ │ │ ├── observability.py # 可观测性指标收集
│ │ │ ├── planner.py # 问题分解规划器（递归 + DAG 依赖）
│ │ │ ├── corpus_router.py # 跨语料库路由器
│ │ │ ├── query_rewriter.py # 跨库查询改写器
│ │ │ ├── judge.py # 检索充分性自动评估
│ │ │ ├── sufficient_context_gate.py # 充分性闸门
│ │ │ ├── citation_alignment.py # 引用-陈述对齐检查
│ │ │ ├── reflector.py # 自反思与自我纠错
│ │ │ ├── hallucination_checker.py # NLI 语义级幻觉检测
│ │ │ └── nodes/ # 独立节点模块
│ │ │ ├── base.py # NodeContext 依赖注入容器
│ │ │ ├── routes.py # 条件边路由函数
│ │ │ └── ... # 11 个节点文件
│ │ ├── tools/ # Agent 工具注册模块
│ │ │ ├── retrieval_tool.py # 文档检索工具
│ │ │ ├── generation_tools.py # 摘要/测验生成工具
│ │ │ └── external_tools.py # 外部工具（计算器、时间查询、Web 搜索）
│ │ ├── rag_manager.py # RAG 管理器（核心逻辑，含缓存）
│ │ ├── rag_facade.py # RAG 门面（统一接口层）
│ │ ├── rag_factory.py # RAG 工厂（组件初始化）
│ │ ├── retrieval_service.py # 检索服务（混合检索 + 查询扩展 + 画像融合 + 上下文扩展）
│ │ ├── cross_corpus_retrieval.py # 跨语料库检索服务
│ │ ├── cross_corpus_ranking.py # 跨库排序、归一化、source-aware MMR
│ │ ├── cross_corpus_citations.py # 跨库引用标准化
│ │ ├── generation_service.py # 生成服务（LLM + 画像注入）
│ │ ├── pdf_processor.py # PDF 处理器（文本归一化 + 页眉页脚检测 + 表格提取）
│ │ ├── chunking_strategies.py # 分块策略（可插拔 + Token 感知 + 内容类型检测 + 质量评估）
│ │ ├── hybrid_retriever.py # 混合检索策略（支持 BM25 独立查询）
│ │ ├── bm25_retriever.py # BM25 稀疏检索（jieba 中文分词 + 词元长度加权）
│ │ └── ...
│ ├── services/ # 业务服务层
│ │ ├── user_profile_service.py # 用户画像服务
│ │ ├── corpus_registry_service.py # Corpus Registry 服务
│ │ └── task_service.py # 任务服务
│ ├── routers/ # API 路由层
│ ├── database/ # 数据库模块
│ │ ├── config.py # 数据库连接配置
│ │ ├── session.py # 异步 Session 工厂
│ │ ├── models.py # SQLAlchemy ORM 模型
│ │ ├── repositories/ # Repository 抽象层
│ │ └── migrations/ # Alembic 迁移脚本
│ ├── evaluation/ # 评估模块
│ │ ├── run_baseline.py # Phase 0 单文档基线评估
│ │ └── run_cross_corpus_benchmark.py # 跨语料库 benchmark
│ ├── tests/ # 测试模块
│ │ ├── test_chunking_regression.py # 分块回归测试（26 项）
│ │ ├── test_data/ # 测试数据文档
│ │ └── snapshots/ # 分块快照
│ ├── main.py # FastAPI 主入口
│ └── rag.py # RAG 实例初始化
│
├── frontend/ # 前端代码
│ ├── src/
│ │ ├── components/ # Vue 组件
│ │ ├── composables/ # 组合式函数
│ │ ├── stores/ # Pinia 状态管理
│ │ ├── utils/ # 工具函数
│ │ │ ├── helpers.js # 通用工具函数（debounce、时间格式化等）
│ │ │ ├── logger.js # 日志工具
│ │ │ ├── storage.js # 存储工具
│ │ │ └── admin.js # 管理后台工具
│ │ ├── types/ # 类型定义
│ │ │ └── quiz.d.ts # 核心数据模型 JSDoc 类型
│ │ └── views/ # 页面视图
│ └── ...
│
└── docs/ # 项目文档
├── deployment.md # 部署指南
├── api-reference.md # API 接口文档
├── architecture.md # 系统架构
└── database-migration.md # 数据库迁移指南
功能演示
| 功能 | 说明 |
|---|---|
| 文档上传与解析 | PDF 上传、文本归一化、分块策略选择、表格提取、进度显示、切片缓存 |
| 智能问答 | 基于文档内容的精准问答，流式输出，多轮对话 |
| Agentic 智能推理 | LLM 自主编排检索策略：ReAct 多步推理、复杂问题分解与去重、Token 感知截断、迭代重检索、自反思纠错、NLI 幻觉检测、意图自适应检索、流式综合生成、语义缓存、持久化对话状态 |
| 跨语料库检索 | 支持当前文档、选定文档集、我的全部文档、自动跨库；展示路由、查询改写、fanout、充分性检查和跨库引用 |
| 流式综合生成 | 子问题并行检索完成后实时流式输出，TTFB 缩短至 3-5 秒，支持预编号引用去重 |
| 意图自适应检索 | 根据意图类型（事实查询/概念解释/对比分析等）动态调节 BM25/Dense 权重与 MMR 参数 |
| 全链路溯源 | 引用标记可点击跳转到 PDF 原文对应位置 |
| 动态难度调整 | CLI 驱动自动切换启蒙/标准/学术三级难度 |
| 用户画像 | 隐式行为采集 → 兴趣画像 → 检索/生成增强 |
| 用户反馈 | Agent 回答赞/踩显式反馈，连续负反馈自动微调检索策略 |
| 智能导读 | 自动生成文档概述、核心要点，支持三档难度 |
| 思维导图 | 基于文档内容自动生成，支持编辑和保存 |
| 智能笔记 | 从 PDF 划选文本添加笔记，自动记录来源位置 |
| 交互测验 | 自动生成测验题目，支持答题和错题分析 |
| 后台管理 | 仪表盘、配置、文档管理、日志、性能监控、画像管理 |
| 用户系统 | 注册登录、JWT 认证、角色管理、数据隔离 |
| 语音输入 | 基于 Web Speech API 的语音转文字，支持中文实时转写 |
| 消息引用回复 | 引用任意消息作为上下文前缀发送追问 |
| 对话分支 | 重新生成时保留历史版本，左右箭头切换对比不同回答 |
| 段落级追问 | 选中 AI 回答中的段落，弹出"针对此段追问"快捷入口 |
| 对话摘要生成 | 一键将整段对话压缩为要点列表，快速回顾核心内容 |
| 快捷短语模板 | 自定义常用提问模板（通俗解释、列出要点等），点击即发送 |
| 消息标记置顶 | 对重要回答添加星标，支持快速筛选和导航 |
| 导出为 Markdown | 对话记录可导出为格式化的 Markdown 文件，便于分享和整理 |
| 输入历史翻页 | 上下箭头翻阅历史发送过的问题，类似终端命令历史 |
| @提及文档章节 | 输入 @ 触发文档目录补全，指定章节范围提问 |
文档导航
| 文档 | 说明 |
|---|---|
| 部署指南 | 环境要求、数据库/后端/前端部署步骤、完整 .env 配置参考 |
| API 接口文档 | 所有 REST API 端点的详细说明 |
| 系统架构 | 混合检索策略、中文分词与查询扩展、缓存机制、用户画像系统架构 |
| 数据库设计 | 表结构、索引、Repository 抽象层、事务边界 |
优化方向
- 支持更多文档格式（Word、PPT、Markdown）
- 多语言支持
- 用户系统与权限管理（JWT 认证 + 数据隔离）
- 知识图谱可视化
- 离线模式支持
- 本地 LLM 支持（Ollama）
许可证
MIT License
Contributors
lidaixingchen
317 commits
Similar repos
Languages
Python
54.9%
Vue
30.9%
JavaScript
13.6%
README
RAG_AI_READ - 基于 RAG 的个性化智能阅读系统
毕业设计课题：基于检索增强生成（Retrieval-Augmented Generation）的个性化智能阅读系统的设计与实现
项目介绍
本项目是一个结合了大语言模型（LLM）与检索增强生成（RAG）技术的智能文档阅读助手。系统旨在解决传统文档阅读中"信息检索难、长文理解慢"的痛点。通过上传 PDF 文档，用户可以与 AI 进行对话，系统会基于文档内容进行精准回答，并提供智能导读、摘要生成等功能。
核心特性
- 智能解析与切片：支持 PDF 文档上传，自动进行文本归一化与智能分块，支持段落级与语义级两种策略，可插拔切换；内置页眉页脚检测、表格提取（Markdown + 自然语言描述）、Token 感知分块；绑定完整元数据与章节信息
- 混合检索机制：结合稀疏检索（BM25 + jieba 中文分词）与稠密检索，采用 RRF 融合策略，支持查询扩展、上下文扩展（相邻 chunk 拉取）与多字符词元加权，实现更精准的上下文检索
- 检索增强问答：利用检索到的私有领域知识增强大模型的回答能力，杜绝"幻觉"
- 跨语料库 Agentic RAG：支持当前文档、选定文档集、我的全部文档、自动跨库四种检索范围；通过 Corpus Registry、Corpus Router、Query Rewriter、Search Fanout、跨库重排和 Sufficient Context Gate 形成多源检索闭环
- Agentic 智能推理：基于 LangGraph 状态图，LLM 自主决定何时检索、检索什么、拆分子问题、评估充分性、自反思纠错——从"被动回答者"升级为"主动编排者"
- 模块化架构：graph.py 仅负责组装（~185 行），11 个节点拆分到独立模块，NodeContext 依赖注入，AgentConfig 集中配置
- ReAct 循环：LLM 自主调用工具（文档检索、章节浏览、摘要生成），实现多步推理
- 问题自动分解：复杂问题自动拆分为子问题 DAG，依赖关系感知的串行/并行执行；融合对话上下文，多轮对话子问题 Embedding 相似度去重，避免重复检索
- 跨库路由与查询改写：Corpus Router 根据用户可见语料库 metadata 选择目标 corpus，Query Rewriter 为不同 corpus 生成 semantic/keyword/entity/gap_fill 查询
- 跨库检索与重排：复用单库 BM25 + Dense + RRF + MMR，并增加跨库 rank-based 归一化、CrossEncoder 全局重排、source-aware MMR 和结构化引用归一化
- 充分性闸门：Sufficient Context Gate 检查检索片段、草稿答案和缺失维度，驱动补检索、回退或带缺口说明的保守回答
- Token 感知上下文截断：基于 tiktoken 精确计数，相关性降序分配 token 预算，避免关键语义截断丢失
- 迭代检索：检索充分性自动评估，不充分时 Reflector 输出
root_cause精准定位原因（检索不足/合成不佳），驱动增量重新检索而非全量重刷 - 自反思纠错：从事实一致性、问题回应性、表述明确性三个维度自检答案质量
- NLI 幻觉检测：自然语言推理语义级幻觉分析，逐条标记证据支撑状态（支撑/矛盾/不确定）
- 意图自适应检索：LLM 合并复杂度与意图分类（事实查询/概念解释/对比分析/综述摘要/深度分析），动态调节 BM25/Dense 权重与 MMR 参数
- 流式综合生成：子问题并行检索完成后，立即流式输出最终回答，首包响应时间（TTFB）缩短至 3-5 秒
- 语义缓存：基于 Embedding 相似度缓存问答对（阈值 0.92），按用户隔离，24 小时过期
- 持久化 Checkpointer：支持 memory / SQLite / PostgreSQL 三种后端，重启不丢失对话上下文
- 可观测性：节点级延迟、成功率指标收集，便于性能分析
- 外部工具调用：calculator（安全数学计算）、datetime_query（时间查询）、web_search（可选集成）
- 全链路溯源：回答中的每个事实性陈述都带有引用标记，点击可跳转到 PDF 原文对应位置
- 动态难度调整 (DDA)：基于认知负荷指数（CLI）自动调整难度等级，采用鲁棒归一化、Holt 双指数平滑、Kalman 滤波等多重算法
- 用户画像系统：隐式采集阅读行为，构建用户兴趣画像与薄弱知识点，画像驱动检索增强与 Prompt 个性化
- 智能导读 / 思维导图 / 智能笔记 / 交互测验：多维度辅助阅读
- 用户反馈闭环：Agent 回答赞/踩显式反馈，点踩收集原因标签，连续负反馈自动微调检索策略；建立
agent_feedbacks数据库表，支持离线模式分析 - 多用户系统：JWT 认证、bcrypt 密码哈希、用户注册登录、角色管理（admin/user）、数据隔离（user_id 外键）
- 流式响应：后端支持 SSE，实现打字机效果的流畅对话体验
- 后台管理：系统配置、文档管理、历史记录、日志查看、性能指标监控等
- 对话交互增强：语音输入、消息引用回复、对话分支对比、段落级追问、关键词高亮联动、对话摘要生成、快捷短语模板、消息标记置顶、Markdown 导出、输入历史翻页、@提及文档章节
技术栈
前端
- 框架：Vue 3.5 + Vite 7 + TypeScript 严格模式 (JSDoc)
- UI 组件库：Element Plus 2.11（按需导入）
- 状态管理：Pinia 3.0 + Composables
- PDF 渲染：PDF.js 5.5
- 思维导图：simple-mind-map 0.14
- 代码规范：ESLint flat/recommended + Prettier
后端
- Web 框架：FastAPI 0.135
- 大模型编排：LangChain (Community/Core/HuggingFace/OpenAI)
- Agent 编排：LangGraph 1.x（ReAct 循环、多步推理、自反思状态图）
- 中文分词：jieba（BM25 稀疏检索的中文词级分词）
- 数据库：PostgreSQL 18 + SQLAlchemy 2.0 (async) + Alembic
- 向量扩展：pgvector（向量列类型，支持余弦相似度检索）
- 向量数据库：ChromaDB
- Embedding 模型：
Qwen/Qwen3-Embedding-0.6B - Reranker 模型：
Qwen/Qwen3-Reranker-0.6B - LLM 接口：兼容 OpenAI 协议（默认适配 DeepSeek）
快速开始
1. 环境准备
- Python >= 3.10、Node.js >= 20.19、PostgreSQL >= 16（需安装 pgvector 扩展）
2. 数据库部署
createdb -U postgres rag_ai_read
psql -U postgres -d rag_ai_read -c "CREATE EXTENSION IF NOT EXISTS vector;"
3. 后端部署
cd backend
conda create -n rag-env python=3.10 -y && conda activate rag-env
pip install -r requirements.txt
pip install torch --index-url https://download.pytorch.org/whl/cu121 # GPU 可选
python download_model.py
# 配置 .env 文件（见下方配置说明，必须设置 JWT_SECRET_KEY 和 ADMIN_PASSWORD）
alembic upgrade head # 数据库迁移
python main.py # http://127.0.0.1:8000
4. 前端部署
cd frontend
pnpm install && pnpm run dev # http://localhost:5173
配置说明
在 backend/ 目录下创建 .env 文件，核心配置项：
# LLM
MODEL_NAME=deepseek-chat
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_BASE_URL=https://api.deepseek.com
# 轻量大模型（用于复杂度/意图分类等轻量任务，可选，未配置时回退使用主模型）
# LIGHTWEIGHT_MODEL_NAME=deepseek-chat
# LIGHTWEIGHT_OPENAI_BASE_URL=https://api.deepseek.com
# LIGHTWEIGHT_OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
# 数据库
DATABASE_URL=postgresql+asyncpg://postgres:password@localhost:5432/rag_ai_read
# 认证（必须配置）
JWT_SECRET_KEY=your-secret-key-here
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-admin-password
# Agent 模式（可选，默认关闭，开启后启用 Agentic RAG 智能推理）
AGENT_ENABLED=true
# 跨语料库 Agentic RAG（可选，默认关闭，可按阶段、用户和 scope 灰度）
AGENT_ENABLE_CROSS_CORPUS=false
AGENT_CROSS_CORPUS_ROLLOUT_STAGE=off
AGENT_CROSS_CORPUS_ALLOWED_USER_IDS=
AGENT_CROSS_CORPUS_ALLOWED_SCOPES=current_document
完整配置参数说明请参阅 部署指南
项目结构
RAG_AI_READ/
├── backend/ # 后端代码
│ ├── auth/ # 认证授权模块（JWT + bcrypt）
│ │ ├── utils.py # 令牌生成/验证、密码哈希
│ │ ├── dependencies.py # FastAPI 依赖工厂
│ │ └── routers/auth_router.py # 注册/登录/me/改密码 API
│ ├── rag_core/ # RAG 核心模块
│ │ ├── agent/ # Agentic RAG 编排层（LangGraph）
│ │ │ ├── graph.py # 状态图组装（~185 行）
│ │ │ ├── state.py # Agent 状态定义 + create_initial_state()
│ │ │ ├── agent_config.py # AgentConfig 集中配置
│ │ │ ├── agent_service.py # Agent 服务层（流式 SSE + 降级容错）
│ │ │ ├── json_parser.py # 共享 JSON 解析（3 层回退）
│ │ │ ├── checkpoint_utils.py # 持久化 Checkpointer 工厂
│ │ │ ├── semantic_cache.py # Agent 语义缓存
│ │ │ ├── observability.py # 可观测性指标收集
│ │ │ ├── planner.py # 问题分解规划器（递归 + DAG 依赖）
│ │ │ ├── corpus_router.py # 跨语料库路由器
│ │ │ ├── query_rewriter.py # 跨库查询改写器
│ │ │ ├── judge.py # 检索充分性自动评估
│ │ │ ├── sufficient_context_gate.py # 充分性闸门
│ │ │ ├── citation_alignment.py # 引用-陈述对齐检查
│ │ │ ├── reflector.py # 自反思与自我纠错
│ │ │ ├── hallucination_checker.py # NLI 语义级幻觉检测
│ │ │ └── nodes/ # 独立节点模块
│ │ │ ├── base.py # NodeContext 依赖注入容器
│ │ │ ├── routes.py # 条件边路由函数
│ │ │ └── ... # 11 个节点文件
│ │ ├── tools/ # Agent 工具注册模块
│ │ │ ├── retrieval_tool.py # 文档检索工具
│ │ │ ├── generation_tools.py # 摘要/测验生成工具
│ │ │ └── external_tools.py # 外部工具（计算器、时间查询、Web 搜索）
│ │ ├── rag_manager.py # RAG 管理器（核心逻辑，含缓存）
│ │ ├── rag_facade.py # RAG 门面（统一接口层）
│ │ ├── rag_factory.py # RAG 工厂（组件初始化）
│ │ ├── retrieval_service.py # 检索服务（混合检索 + 查询扩展 + 画像融合 + 上下文扩展）
│ │ ├── cross_corpus_retrieval.py # 跨语料库检索服务
│ │ ├── cross_corpus_ranking.py # 跨库排序、归一化、source-aware MMR
│ │ ├── cross_corpus_citations.py # 跨库引用标准化
│ │ ├── generation_service.py # 生成服务（LLM + 画像注入）
│ │ ├── pdf_processor.py # PDF 处理器（文本归一化 + 页眉页脚检测 + 表格提取）
│ │ ├── chunking_strategies.py # 分块策略（可插拔 + Token 感知 + 内容类型检测 + 质量评估）
│ │ ├── hybrid_retriever.py # 混合检索策略（支持 BM25 独立查询）
│ │ ├── bm25_retriever.py # BM25 稀疏检索（jieba 中文分词 + 词元长度加权）
│ │ └── ...
│ ├── services/ # 业务服务层
│ │ ├── user_profile_service.py # 用户画像服务
│ │ ├── corpus_registry_service.py # Corpus Registry 服务
│ │ └── task_service.py # 任务服务
│ ├── routers/ # API 路由层
│ ├── database/ # 数据库模块
│ │ ├── config.py # 数据库连接配置
│ │ ├── session.py # 异步 Session 工厂
│ │ ├── models.py # SQLAlchemy ORM 模型
│ │ ├── repositories/ # Repository 抽象层
│ │ └── migrations/ # Alembic 迁移脚本
│ ├── evaluation/ # 评估模块
│ │ ├── run_baseline.py # Phase 0 单文档基线评估
│ │ └── run_cross_corpus_benchmark.py # 跨语料库 benchmark
│ ├── tests/ # 测试模块
│ │ ├── test_chunking_regression.py # 分块回归测试（26 项）
│ │ ├── test_data/ # 测试数据文档
│ │ └── snapshots/ # 分块快照
│ ├── main.py # FastAPI 主入口
│ └── rag.py # RAG 实例初始化
│
├── frontend/ # 前端代码
│ ├── src/
│ │ ├── components/ # Vue 组件
│ │ ├── composables/ # 组合式函数
│ │ ├── stores/ # Pinia 状态管理
│ │ ├── utils/ # 工具函数
│ │ │ ├── helpers.js # 通用工具函数（debounce、时间格式化等）
│ │ │ ├── logger.js # 日志工具
│ │ │ ├── storage.js # 存储工具
│ │ │ └── admin.js # 管理后台工具
│ │ ├── types/ # 类型定义
│ │ │ └── quiz.d.ts # 核心数据模型 JSDoc 类型
│ │ └── views/ # 页面视图
│ └── ...
│
└── docs/ # 项目文档
├── deployment.md # 部署指南
├── api-reference.md # API 接口文档
├── architecture.md # 系统架构
└── database-migration.md # 数据库迁移指南
功能演示
| 功能 | 说明 |
|---|---|
| 文档上传与解析 | PDF 上传、文本归一化、分块策略选择、表格提取、进度显示、切片缓存 |
| 智能问答 | 基于文档内容的精准问答，流式输出，多轮对话 |
| Agentic 智能推理 | LLM 自主编排检索策略：ReAct 多步推理、复杂问题分解与去重、Token 感知截断、迭代重检索、自反思纠错、NLI 幻觉检测、意图自适应检索、流式综合生成、语义缓存、持久化对话状态 |
| 跨语料库检索 | 支持当前文档、选定文档集、我的全部文档、自动跨库；展示路由、查询改写、fanout、充分性检查和跨库引用 |
| 流式综合生成 | 子问题并行检索完成后实时流式输出，TTFB 缩短至 3-5 秒，支持预编号引用去重 |
| 意图自适应检索 | 根据意图类型（事实查询/概念解释/对比分析等）动态调节 BM25/Dense 权重与 MMR 参数 |
| 全链路溯源 | 引用标记可点击跳转到 PDF 原文对应位置 |
| 动态难度调整 | CLI 驱动自动切换启蒙/标准/学术三级难度 |
| 用户画像 | 隐式行为采集 → 兴趣画像 → 检索/生成增强 |
| 用户反馈 | Agent 回答赞/踩显式反馈，连续负反馈自动微调检索策略 |
| 智能导读 | 自动生成文档概述、核心要点，支持三档难度 |
| 思维导图 | 基于文档内容自动生成，支持编辑和保存 |
| 智能笔记 | 从 PDF 划选文本添加笔记，自动记录来源位置 |
| 交互测验 | 自动生成测验题目，支持答题和错题分析 |
| 后台管理 | 仪表盘、配置、文档管理、日志、性能监控、画像管理 |
| 用户系统 | 注册登录、JWT 认证、角色管理、数据隔离 |
| 语音输入 | 基于 Web Speech API 的语音转文字，支持中文实时转写 |
| 消息引用回复 | 引用任意消息作为上下文前缀发送追问 |
| 对话分支 | 重新生成时保留历史版本，左右箭头切换对比不同回答 |
| 段落级追问 | 选中 AI 回答中的段落，弹出"针对此段追问"快捷入口 |
| 对话摘要生成 | 一键将整段对话压缩为要点列表，快速回顾核心内容 |
| 快捷短语模板 | 自定义常用提问模板（通俗解释、列出要点等），点击即发送 |
| 消息标记置顶 | 对重要回答添加星标，支持快速筛选和导航 |
| 导出为 Markdown | 对话记录可导出为格式化的 Markdown 文件，便于分享和整理 |
| 输入历史翻页 | 上下箭头翻阅历史发送过的问题，类似终端命令历史 |
| @提及文档章节 | 输入 @ 触发文档目录补全，指定章节范围提问 |
文档导航
| 文档 | 说明 |
|---|---|
| 部署指南 | 环境要求、数据库/后端/前端部署步骤、完整 .env 配置参考 |
| API 接口文档 | 所有 REST API 端点的详细说明 |
| 系统架构 | 混合检索策略、中文分词与查询扩展、缓存机制、用户画像系统架构 |
| 数据库设计 | 表结构、索引、Repository 抽象层、事务边界 |
优化方向
- 支持更多文档格式（Word、PPT、Markdown）
- 多语言支持
- 用户系统与权限管理（JWT 认证 + 数据隔离）
- 知识图谱可视化
- 离线模式支持
- 本地 LLM 支持（Ollama）
许可证
MIT License
Similar repos
Contributors
lidaixingchen
317 commits
Languages
Python
54.9%
Vue
30.9%
JavaScript
13.6%