系列导读本文是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 一览Agent业务能力核心技术范式智能问答QA基于课程知识库实时答疑RAG 混合检索 BGE-M3 Reranker 精排 SSE 流式试卷批改Exam自动批改选择题 / 简答题 / 编程题三轨并行批改 HitL 教师确认环简历审查Resume六维度评分并给出改进建议PDF 解析 结构化抽取 多维度并行评分模拟面试Interview五阶段全程技术面试陪练状态机对话 Think Tool 双轨质量评估四个 Agent 之上由Orchestrator 编排层统一做意图路由与多 Agent 串联 Pipeline。三、技术栈选型层面选型开发语言Python 3.11严格锁定Web 框架FastAPI SSE-StarletteAgent 框架LangChain 1.2.10 LangGraph 1.0.9主力大模型DeepSeekOpenAI 兼容接口向量数据库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 FactoryLLM 统一封装 结构化输出 ├── 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 个工程范式读这个项目我建议重点留意下面五个贯穿全项目的模式后续文章会逐一展开Agent 四件套结构每个 Agent 都是graph.py state.py nodes.py prompts.py四个文件结构高度统一。state.py用TypedDict定义图的数据总线用Pydantic定义 LLM 结构化输出的 Schema。LLM 工厂模式所有 Agent 禁止直接调用init_chat_model必须通过LLMFactory按agent_type路由拿模型自带实例缓存和结构化输出绑定。三层兜底机制自动重试1s/3s 间隔→ Agent 级降级各业务有自己的兜底策略→ 系统级兜底永不抛异常给用户。单例模式 进程内模型三个本地模型全部get_instance()单例lifespan 里用asyncio.gather run_in_executor并行预热避免首个请求卡顿。HitLHuman-in-the-Loop试卷批改图执行到教师审核节点会interrupt()暂停教师确认后Command(resume...)恢复这是 LangGraph 最实用的能力之一。七、运行架构速览服务端口说明FastAPI 后端8000REST SSE 接口/docs查看 SwaggerVue3 前端3000学员 / 教师 / 管理员界面PostgreSQL5432关系数据库Milvus19530向量库Langfuse3100LLM 调用追踪与可观测性所有连接配置统一从.env.local读取禁止硬编码端口号——配置中心用pydantic-settings实现下一篇会讲。下篇预告下一篇《EduAgent 项目全解析二工程地基——配置中心、LLM 工厂与三层兜底》我们会深入config.py、llm_factory.py、retry.py三个文件看看一个生产级 AI 项目的地基是怎么打的如何用 pydantic-settings 管理配置、如何用工厂模式统一管理 LLM 实例、如何用装饰器实现三层兜底以及为什么trust_envFalse能解决代理导致的 SSL 报错。项目源码仅供教学参考欢迎 Star、转发、留言交流。有任何想深入拆解的模块评论区告诉我。