系列导读：本文是 EduAgent 项目全解析 系列的第一篇。EduAgent 是一个基于 LangGraph + FastAPI 构建的 AI 教育多智能体平台，完整实现了四个业务 Agent（智能问答 / 试卷批改 / 简历审查 / 模拟面试）。本系列共 7 篇，从工程地基讲到编排集成，全程结合真实源码讲解，适合想学习 LangGraph 多智能体工程化实践的同学。
- 第一篇（本文）：项目概览与系统架构
- 第二篇：工程地基——配置中心、LLM 工厂与三层兜底
- 第三篇：RAG 智能问答 Agent——混合检索、HyDE 与 Multi-Query
- 第四篇：简历审查 Agent——PDF 解析与六维并行评分
- 第五篇：试卷批改 Agent——三轨并行与人在环中（HitL）
- 第六篇：模拟面试 Agent——五阶段状态机
- 第七篇：系统集成——Orchestrator 编排与统一 SSE 入口
一、项目背景：教培机构的四类重复性业务
IT 教培机构每天面对四类重复性高、耗费师资的业务：
| 学员答疑 | 同类问题反复出现，老师精力有限 |
| 试卷批改 | 量大、主观题评分容易不一致 |
| 简历审查 | 老师无暇逐份精读打分 |
| 技术面试 | 缺少随时可陪练并给出专业反馈的「面试官」 |
EduAgent 将这四类业务分别封装为独立的 AI Agent，每个 Agent 融合企业私有知识、内置完整业务流程、配备工程化容错机制。
二、四大核心 Agent 一览
| 智能问答（QA） | 基于课程知识库实时答疑 | RAG 混合检索 + BGE-M3 + Reranker 精排 + SSE 流式 |
| 试卷批改（Exam） | 自动批改选择题 / 简答题 / 编程题 | 三轨并行批改 + HitL 教师确认环 |
| 简历审查（Resume） | 六维度评分并给出改进建议 | PDF 解析 + 结构化抽取 + 多维度并行评分 |
| 模拟面试（Interview） | 五阶段全程技术面试陪练 | 状态机对话 + Think Tool 双轨质量评估 |
四个 Agent 之上由 Orchestrator 编排层 统一做意图路由与多 Agent 串联 Pipeline。
三、技术栈选型
| 开发语言 | Python 3.11（严格锁定） |
| Web 框架 | FastAPI + SSE-Starlette |
| Agent 框架 | LangChain 1.2.10 + LangGraph 1.0.9 |
| 主力大模型 | DeepSeek（OpenAI 兼容接口） |
| 向量数据库 | Milvus |
| 关系数据库 | PostgreSQL + SQLAlchemy（全异步） |
| 嵌入模型 | BGE-M3（进程内，dense + sparse 双输出） |
| 精排模型 | BGE-Reranker-large（进程内） |
| 意图分类 | MiniLM-L6-v2（进程内） |
| 前端 | Vue3 + TypeScript + Element Plus |
这里有一个值得注意的工程决策：BGE-M3、BGE-Reranker、MiniLM 三个本地模型都是进程内调用，不单独起服务，在后端启动时并行预热。相比把模型部署成独立推理服务，这种方案在中小规模场景下更简单、省资源。
四、系统整体架构
┌─────────────────────────────────────────────────┐
│ 前端层 Vue3 SPA (:3000) │
└────────────────────┬────────────────────────────┘
│ HTTP / SSE
┌────────────────────▼────────────────────────────┐
│ API 层 FastAPI (:8000) │
│ JWT 鉴权 / SSE 流式 / 文件上传 │
└────────────────────┬────────────────────────────┘
│
┌────────────────────▼────────────────────────────┐
│ 编排层 Orchestrator │
│ 规则拦截 → LLM 意图识别 → 单 Agent / Pipeline │
└──────┬───────────┬───────────┬───────────┬──────┘
│ │ │ │
┌────▼───┐ ┌───▼────┐ ┌───▼────┐ ┌───▼──────┐
│ QA │ │ Exam │ │Resume │ │Interview │ ← LangGraph StateGraph × 4
│ Agent │ │ Agent │ │ Agent │ │ Agent │
└────────┘ └────────┘ └────────┘ └──────────┘
公共层
├── LLM Factory（LLM 统一封装 + 结构化输出）
├── BGE-Reranker / MiniLM / MemorySaver
└── MCP Server（知识库检索 + Web 搜索）
│
┌────────────────────▼────────────────────────────┐
│ 数据层 PostgreSQL · Redis · Milvus · MinIO │
└─────────────────────────────────────────────────┘
数据流大致是：前端（Vue3）通过 HTTP/SSE 调 FastAPI → API 层做 JWT 鉴权后交给编排层 → 编排层按意图把请求分发到某个 Agent 的 LangGraph 图 → 图内各节点读写 PostgreSQL / Milvus，调用 LLM → 结果经 SSE 流式推回前端。
五、目录结构导读（后端视角）
backend/
├── main.py # FastAPI 入口 & lifespan（模型预热 + DB 迁移）
├── config.py # pydantic-settings 配置中心
├── dependencies.py # JWT 鉴权依赖 + AsyncSessionLocal
├── langfuse_handler.py # Langfuse 可观测性回调
├── api/
│ └── v1/ # 业务接口（auth/qa/exam/resume/interview/unified_chat）
├── agents/ # ★ 四大 Agent（每个含 graph/nodes/state/prompts 四件套）
│ ├── qa/ # RAG 智能问答
│ ├── exam/ # 试卷批改 HitL
│ ├── resume/ # 简历审查 fan-out
│ └── interview/ # 模拟面试状态机
├── core/ # ★ 公共核心模块
│ ├── llm_factory.py # LLM 统一工厂
│ ├── orchestrator.py # 编排器
│ ├── knowledge_base.py # BGE-M3 向量检索（Milvus）
│ ├── reranker.py # BGE-Reranker 精排
│ ├── query_classifier.py # 意图分类器
│ ├── memory.py # MemorySaver + 对话记忆
│ ├── retry.py # 三层兜底重试
│ ├── exceptions.py # 统一异常体系
│ └── logger.py # structlog 日志
├── db/migrations.py # 数据迁移
└── mcp_server/ # MCP Server（知识库检索 + Web 搜索）
六、最值得学习的 5 个工程范式
读这个项目，我建议重点留意下面五个贯穿全项目的模式（后续文章会逐一展开）：
七、运行架构速览
| FastAPI 后端 | 8000 | REST + SSE 接口，/docs 查看 Swagger |
| Vue3 前端 | 3000 | 学员 / 教师 / 管理员界面 |
| PostgreSQL | 5432 | 关系数据库 |
| Milvus | 19530 | 向量库 |
| Langfuse | 3100 | LLM 调用追踪与可观测性 |
所有连接配置统一从 .env.local 读取，禁止硬编码端口号——配置中心用 pydantic-settings 实现，下一篇会讲。
下篇预告
下一篇《EduAgent 项目全解析（二）：工程地基——配置中心、LLM 工厂与三层兜底》，我们会深入 config.py、llm_factory.py、retry.py 三个文件，看看一个生产级 AI 项目的地基是怎么打的：如何用 pydantic-settings 管理配置、如何用工厂模式统一管理 LLM 实例、如何用装饰器实现三层兜底，以及为什么 trust_env=False 能解决代理导致的 SSL 报错。
项目源码仅供教学参考，欢迎 Star、转发、留言交流。有任何想深入拆解的模块，评论区告诉我。
