English | 中文
基于 RAG + LangGraph Agent 的苏格拉底式智能错题学习系统
TraceBack 是一个面向学习场景的 AI 智能体系统，核心理念是不直接给答案，而是通过苏格拉底式反问引导学生自主思考。系统基于 RAG（检索增强生成）技术从知识库中精准检索知识点，再由 LangGraph 编排的 Agent 结合对话上下文进行多轮引导，帮助学生深刻理解错题背后的知识本质。
- RAG 全链路 — 文档上传 → 智能切片 → 向量化 → Milvus 存储 → 混合检索 → 重排序 → LLM 生成，完整覆盖
- LangGraph 双模式 Agent — 普通问答模式直接回答，苏格拉底引导模式通过反问法多轮推导，均由 StateGraph 流程编排
- 向量知识库 — Milvus 1024 维向量存储，18 字段 Schema，支持权限隔离（私有/公共）、元数据筛选、按 knowledge_id 管理
- SSE 流式输出 — 逐 token 实时推送，基于
astream_events从 LangGraph 内部提取流式片段 - 错题本闭环 — 对话过程中自动提取错题信息，引导模式从缓存保存，普通模式由 Python 后端直接写入，支持复习状态管理
┌─────────────────────────────────────────────────────────────────────┐
│ Vue 3 前端 (Port 5173) │
│ Element Plus · Pinia · Vue Router · SSE Fetch │
└───────────────────────────┬─────────────────────────────────────────┘
│ Vite Proxy
┌───────────────┼───────────────┐
▼ ▼
┌─────────────────────┐ ┌─────────────────────────┐
│ Java 后端 (8081) │ │ Python 后端 (8000) │
│ Spring Boot 3.2.5 │◄────────│ FastAPI + LangGraph │
│ · 用户/会话/消息管理 │ HTTP │ · RAG 检索与知识管理 │
│ · 错题本 CRUD │ 调用 │ · Agent 对话编排 │
│ · 文件存储 │ │ · LLM 生成 (SSE) │
│ · 统计分析 │ │ · 向量化/重排/OCR │
└─────────┬───────────┘ └──────────┬──────────────┘
│ │
▼ ▼
┌────────────┐ ┌─────────────────────┐
│ MySQL 8.0 │ │ Milvus v2.6 (向量库) │
│ 关系型数据 │ │ + MinIO (对象存储) │
└────────────┘ └─────────────────────┘
请求路由规则（Vite Proxy）：
/api/users,/api/sessions,/api/messages,/api/mistakes,/api/files,/api/statistics→ Java 后端/api/chat,/api/knowledge→ Python 后端
| 格式 | 解析器 | 备注 |
|---|---|---|
| PyMuPDFReader | 按 10 页分组合并，扫描件回退 PaddleOCR | |
| DOCX | LlamaIndex DocxReader | 按 10 页分组 |
| TXT/Markdown | 直接读取 | — |
- 切片器：LlamaIndex
SentenceSplitter - chunk_size：2048 字符
- chunk_overlap：200 字符
- 段落分隔符：
\n\n - 元数据提取：从 Markdown 标题自动提取
chapter（二级标题）、tags（三级标题），关键词匹配检测difficulty
- Embedding 模型：DashScope
text-embedding-v4，1024 维 - 向量数据库：Milvus v2.6.12 Standalone
- 索引类型：
IVF_FLAT，度量IP（内积），nlist=128 - Collection Schema：18 个字段，含
vector(1024)、text、knowledge_id、user_id、is_private、chapter、difficulty、tags等 - 写入方式：原生 PyMilvus API 直接 insert，完全控制字段映射
- 权限过滤：
(user_id == '{uid}' || is_private == false)确保用户仅可见自己的私有知识 + 公共知识 - 向量检索：LlamaIndex Retriever，
similarity_top_k可配 - 重排序：DashScope
gte-rerank-v2精排 - 冗余去重：
SentenceEmbeddingOptimizer基于 Embedding 相似度去除冗余段落
- LLM：通义千问
qwen3-max，通过langchain_community.ChatTongyi调用 - temperature：0.7 | max_tokens：2048
- 流式：LangGraph
astream_events(version="v1")提取on_chat_model_stream事件，逐 token 推送 SSE
┌──────────────┐
User Query ──▶│ normal_answer │──▶ RAG 检索 ──▶ 构建知识上下文 ──▶ LLM 生成 ──▶ Response
└──────────────┘
单节点流程：检索知识库 → 拼装 Prompt → 生成回答，自动保存错题。
┌────────────────┐
User Query ──▶│ route_by_cache │
└───┬────────┬───┘
首次提问 │ │ 追问（有缓存）
▼ ▼
┌─────────────┐ ┌───────────────┐
│guide_with_rag│ │guide_with_cache│
│ RAG检索+缓存 │ │ 直接使用缓存 │
└──────┬──────┘ └──────┬────────┘
▼ ▼
生成引导问题 生成引导问题
（不给答案） （根据回答调整）
│
┌──────────┴──────────┐
▼ ▼
回答正确→深入 回答错误→温和引导
不完整→补充引导 说不知道→给予提示
│
▼
[完成学习] ──▶ 保存错题到错题本
设计亮点：引导模式仅在首轮执行一次 RAG 检索，将知识缓存在 Session.cache 中，后续追问直接复用缓存，避免重复检索开销。
| 层级 | 技术 |
|---|---|
| 前端 | Vue 3.5 · Vite 8 · Element Plus · Pinia · Vue Router · Axios · ECharts |
| Java 后端 | Spring Boot 3.2.5 · Spring Security · MyBatis-Plus · Flyway · MySQL Connector |
| Python 后端 | FastAPI · LangGraph · LangChain · LlamaIndex · DashScope · PyMilvus |
| 向量数据库 | Milvus v2.6.12 Standalone · MinIO · etcd |
| 关系数据库 | MySQL 8.0 |
| AI 模型 | LLM: 通义千问 qwen3-max · Embedding: text-embedding-v4 (1024d) · Rerank: gte-rerank-v2 |
| 文档处理 | PyMuPDF · python-docx · PaddleOCR（扫描件回退） |
| 部署 | Docker · Docker Compose · Nginx 反向代理 |
Trace-Back/
├── frontend/ # Vue 3 前端
│ └── trace-back/
│ └── src/
│ ├── api/ # API 封装（Java / Python 双实例）
│ ├── views/ # 页面组件
│ ├── stores/ # Pinia 状态管理
│ ├── components/ # 公共组件（Markdown渲染器、富文本编辑器等）
│ └── utils/ # 工具函数（请求封装、格式化）
├── java-backend/ # Spring Boot 后端
│ └── trace-back/src/main/java/com/traceback/
│ ├── controller/ # REST 接口
│ ├── service/ # 业务逻辑
│ ├── entity/ # 数据库实体
│ ├── mapper/ # MyBatis-Plus Mapper
│ └── config/ # 安全、CORS、Swagger 配置
├── python-backend/ # FastAPI + RAG 后端
│ └── app/
│ ├── api/ # 路由（chat.py, knowledge.py）
│ ├── services/ # 核心服务（agent、rag、llm、prompts）
│ ├── utils/ # 向量存储、检索器、文本处理
│ ├── models/ # Pydantic 请求/响应模型
│ └── config/ # 配置管理
├── doc/ # 项目文档（接口、数据库、架构、需求）
├── start.bat # 本地一键启动脚本
└── deploy.py # 远程部署脚本（.gitignore 已忽略）
- Java 17+
- Python 3.9+
- Node.js 18+
- Docker & Docker Compose
# 1. 克隆仓库
git clone https://github.com/<your-username>/Trace-Back.git
cd Trace-Back
# 2. 配置环境变量
# python-backend/.env
DASHSCOPE_API_KEY=your_dashscope_api_key
# 3. 一键启动（Windows）
start.bat
# 或手动逐个启动：
# 启动 MySQL（Docker）
docker run -d --name mysql-db -e MYSQL_ROOT_PASSWORD=root -e MYSQL_DATABASE=traceback -p 3306:3306 mysql:8.0
# 启动 Milvus（Docker Compose）
cd python-backend && docker compose up -d
# 启动 Java 后端
cd java-backend/trace-back && ./mvnw spring-boot:run
# 启动 Python 后端
cd python-backend && uvicorn app.main:app --host 0.0.0.0 --port 8000
# 启动前端
cd frontend/trace-back && npm install && npm run dev- 前端页面：
http://localhost:5173 - Java Swagger：
http://localhost:8081/swagger-ui.html - Milvus Attu：
http://localhost:8001
- 普通问答：基于知识库的 RAG 检索问答，自动保存错题
- 引导学习：苏格拉底式反问，多轮引导后保存错题与知识点总结
- 支持 SSE 流式输出，逐字显示
- 自动保存：引导模式从缓存提取，普通模式 Python 端直接写入
- 错题详情：题目、错误上下文、知识点总结、知识来源、章节、难度、标签
- 状态管理：待复习 / 已掌握，支持筛选和搜索
- 文件上传：PDF / DOCX / TXT / Markdown，支持元数据标注（标题、章节、难度、标签）
- 向量检索：基于语义相似度的知识搜索
- 权限隔离：私有知识仅自己可见，公共知识全员可见
- 支持删除（同步清理 Milvus 向量）
- 数据分析仪表盘（ECharts 可视化）
- 知识库管理
- 用户增长趋势、错题标签分布等统计
MIT
曾旭辉 — 中南林业科技大学涉外学院 · 软件工程