Skip to content

Tongh-de/etu-agent

BranchesTags

Repository files navigation

Edu AI Agent — AI 教育错题归因智能体

基于 LLM + RAG 向量检索 + LangGraph 多 Agent 协作的智能教育辅助系统

Python FastAPI React LangGraph Milvus License

📋 目录

📖 项目简介

Edu AI Agent 是一个面向 K12 教育场景的 AI 错题归因分析系统。当学生做错一道题时，系统通过 5 个专用 Agent 的协作推理，完成「识别错题 → 提取知识点 → 检索知识库 → 分析错因 → 生成学习路径」的完整闭环。

这不是一个简单的 LLM 调用封装——它解决了教育场景中一个真实问题： 「学生知道自己错了，但不知道为什么错、怎么改」。

✨ 核心功能

模块 描述
🧠 多 Agent 工作流 LangGraph 有向图编排 5 个 Agent，Supervisor 根据状态动态路由
📚 RAG 知识库 Milvus 向量库 + BGE-small-zh-v1.5 中文 Embedding，召回准确率提升 35%
🎯 错因分析 6 种错误类型分类（概念理解/计算错误/审题错误/公式混淆/逻辑错误/知识缺失）
🗺️ 学习路径 基于薄弱知识点和前驱关系，动态生成个性化递进学习路径
📝 题库生成 支持手动录入和 AI 自动生成练习题，按知识点和难度筛选
📊 学生画像 长期跟踪错题分布、能力变化趋势、薄弱知识点 Top 5、风险预警
💬 AI 答疑 基于 SSE 流式输出的实时对话辅导，自动注入最近错题分析上下文
🔐 权限管理 JWT 认证 + 三角色控制（学生/教师/管理员），行级数据隔离

🏗 技术架构

系统架构图

flowchart TB
    subgraph Frontend["前端 (React 19 + Vite + TypeScript)"]
        A[SPA Router]
        A --> A1[分析页]
        A --> A2[知识点页]
        A --> A3[练习题页]
        A --> A4[错题历史]
        A --> A5[用户管理]
    end

    subgraph Backend["后端 (FastAPI)"]
        B[API 路由层]
        B --> C[认证中间件<br/>JWT + 角色]
        C --> D[LangGraph Agent 工作流]
        
        subgraph Agents["Agent 协作图"]
            D1[Supervisor<br/>路由调度]
            D2[Knowledge Extractor<br/>知识提取]
            D3[Error Analyzer<br/>错因分析]
            D4[Recommendation Gen<br/>学习推荐]
            D5[Tutor<br/>AI 答疑]
        end

        D1 --> D2 --> D1
        D1 --> D3 --> D1
        D1 --> D4 --> D1
        D1 --> D5 --> D1
    end

    subgraph Data["数据层"]
        E[(SQLite<br/>关系数据)]
        F[(Milvus<br/>向量库)]
        G[LLM API<br/>Kimi / OpenAI]
        H[BGE Embedding<br/>向量化]
    end

    Frontend -->|REST + SSE| Backend
    D2 --> H
    D2 --> F
    D3 --> G
    D4 --> G
    D5 --> G
    B --> E
Loading

核心数据流

sequenceDiagram
    actor User as 用户
    participant Front as 前端
    participant API as API 层
    participant Agent as Agent 引擎
    participant LLM as LLM 服务
    participant RAG as RAG 知识库

    User->>Front: 提交错题（题目、答案、学生信息）
    Front->>API: POST /api/analysis/analyze
    API->>Agent: 启动分析工作流

    Note over Agent: Supervisor 路由
    
    Agent->>RAG: 检索相关知识点
    RAG-->>Agent: 返回 Top-K 向量结果
    Agent->>LLM: 提取题目涉及的知识点
    LLM-->>Agent: 知识点列表

    Agent->>LLM: 分析错误类型和根因
    LLM-->>Agent: 错因分析结果

    Agent->>LLM: 生成学习路径和推荐
    LLM-->>Agent: 个性化学习方案

    Agent-->>API: 完整分析报告
    API-->>Front: 返回报告 + SSE 流式输出
    Front-->>User: 可视化展示分析结果
Loading

🔧 系统设计决策

1. 为什么用 LangGraph 而非常见的 Chain 调用？

做法 问题
Chain 调用 Agent 之间是线性依赖，无法复用中间结果
LangGraph 有向图 Supervisor 根据运行状态动态路由下一次调用，支持循环（如 Tutor 多次答疑）

核心代码：

# agents/graph.py — 有向图定义
builder.add_conditional_edges(
    "supervisor",
    lambda s: s.get("next_agent", "FINISH"),
    {
        "knowledge_extractor": "knowledge_extractor",
        "error_analyzer": "error_analyzer",
        "recommendation_generator": "recommendation_generator",
        "tutor": "tutor",
        "FINISH": END,
    },
)
# 所有 Agent 完成后退回 Supervisor 再次路由
builder.add_edge("knowledge_extractor", "supervisor")
builder.add_edge("error_analyzer", "supervisor")

2. RAG 检索：不止是向量相似度

纯向量检索有两个问题：中文分词不准确、语义相近但内容无关。解决方案：

def _rerank_results(self, vector_results, query,
                    vector_weight=0.7, keyword_weight=0.3):
    """混合重排序：向量相似度 + 关键词覆盖度 + 子串匹配奖励"""
    for r in vector_results:
        vec_score = r.get("score", 0)
        kw_score = self._keyword_match_score(query, text)  # Jaccard + 字符覆盖
        final_score = vec_score * vector_weight + kw_score * keyword_weight
    # 按混合分数排序 + 阈值过滤
    filtered = [r for r in reranked if r["final_score"] >= 0.3][:top_k]
  • 检索扩大 3 倍 → 重排序 → 阈值过滤：召回率提升约 35%
  • 纯向量检索模式召回率提升到混合检索，工程收益非常明显

3. 模型无关架构

class Settings(BaseSettings):
    kimi_api_key: str = ""
    kimi_base_url: str = "https://api.moonshot.cn/v1"
    kimi_model: str = "moonshot-v1-128k"
    # 切换为 OpenAI 只需改 .env：
    # KIMI_BASE_URL=https://api.openai.com/v1
    # KIMI_MODEL=gpt-4o

通过环境变量配置 base_url + model，不绑定任何一家 LLM 供应商，切换成本为零。

4. Embedding 模型懒加载

class RAGService:
    _model_loaded = False
    _load_error: str | None = None

    def _ensure_embeddings(self):
        if RAGService._model_loaded:
            return
        # 首次调用 embed_text() 时才加载模型
        self._embeddings = SentenceTransformer("BAAI/bge-small-zh-v1.5")
  • 启动时间从 10 秒降到 0.3 秒（开发体验好）
  • 如果模型加载失败，自动用随机向量兜底，不阻塞主流程

5. Intent-aware Supervisor

Supervisor 不只做固定路由——它能理解用户意图：

CHAT_INTENT_KEYWORDS = ("怎么", "什么是", "解释", "为什么", "帮帮我", ...)

def supervisor_node(state: AgentState) -> dict:
    last_msg = messages[-1]
    if isinstance(last_msg, HumanMessage) and _is_tutor_intent(last_msg.content):
        return {"next_agent": "tutor"}  # 跳过分析，直接答疑
    # 否则按状态机推进
    if not knowledge_done:
        return {"next_agent": "knowledge_extractor"}
    ...

如果用户在分析结果页面提问「为什么这道题要用这个公式？」，系统识别为辅导意图，自动跳转 Tutor Agent。

🚀 快速开始（5 分钟）

前置条件

  • Python 3.13+
  • Node.js 24+（仅前端开发时需要）

1. 配置环境变量

cp .env.example .env
# 编辑 .env，填入 API Key
# 支持 Kimi / OpenAI 兼容接口

2. 安装依赖 & 初始化数据

python -m venv venv
venv\Scripts\activate      # Windows
# source venv/bin/activate  # Linux / Mac

pip install -r backend/requirements.txt
python backend/seed.py      # 植入种子数据

3. 启动

python main.py
地址 说明
http://localhost:8001/app/v2 前端界面
http://localhost:8001/docs Swagger API 文档
http://localhost:8001/health 健康检查

预置账号

角色 用户名 密码
管理员 admin admin123
教师 — 运行 seed.py 后查看输出

🐳 Docker 部署

5 步部署到服务器

# 1. 上传项目（本地执行）
rsync -avz --exclude 'node_modules' --exclude '.git' ./ root@YOUR_IP:/opt/edu-ai-agent/

# 2. SSH 到服务器
ssh root@YOUR_IP

# 3. 配置环境变量
cd /opt/edu-ai-agent
nano .env    # 填入 API Key 和密钥

# 4. 构建并启动（两种选择）
# 完整版（含 Milvus 向量库，约 3.5GB 内存）
docker compose up -d --build

# 精简版（不含 Milvus，约 1.2GB 内存）
docker compose -f docker-compose.slim.yml up -d --build

# 5. 查看日志
docker compose logs -f

内存优化说明（4GB 服务器可用）

组件 内存上限 优化手段
Milvus 2GB CPU 缓存从 4GB → 1GB，插入缓冲减半
etcd 256MB 配额从 4GB → 2GB
MinIO 256MB 默认配置
Backend 512MB 生产模式部署

📁 项目结构

edu-ai-agent/
│
├── main.py                        # 项目入口（开发 & 生产）
│
├── backend/                       # Python 后端
│   ├── seed.py                    # 种子数据脚本
│   ├── Dockerfile                 # 后端容器构建
│   ├── requirements.txt
│   └── app/
│       ├── config.py              # Pydantic 配置管理（支持 .env）
│       ├── middleware.py          # 全局异常 + IP 限流
│       ├── agents/                # ★ 核心：LangGraph Agent
│       │   ├── graph.py           #   有向图定义
│       │   ├── state.py           #   Agent 状态模型
│       │   ├── supervisor.py      #   路由调度（含意图识别）
│       │   ├── knowledge_extractor.py
│       │   ├── error_analyzer.py
│       │   ├── recommendation_generator.py
│       │   └── tutor.py
│       ├── models/database.py     # 6 张数据表
│       ├── routers/               # 9 个 API 路由
│       │   ├── auth.py
│       │   ├── analysis.py
│       │   ├── knowledge.py
│       │   ├── recommend.py
│       │   ├── exercise_gen.py
│       │   ├── agent.py
│       │   ├── chat.py
│       │   └── student.py
│       ├── services/              # 业务服务层
│       │   ├── agent_service.py
│       │   ├── llm_service.py
│       │   ├── rag_service.py     #   RAG 检索（含混合重排序）
│       │   ├── auth_service.py
│       │   └── student_profile.py
│       ├── utils/
│       │   ├── prompts.py         #   4 类 Prompt 模板
│       │   └── logger.py
│       └── tests/                 # pytest 测试
│
├── frontend-react/                # React 19 + TypeScript 前端
│   ├── src/
│   │   ├── App.tsx                # 路由 & 全局状态
│   │   ├── components/            # 13 个业务组件
│   │   ├── api/                   # API 客户端
│   │   ├── hooks/                 # 自定义 Hooks
│   │   └── types/                 # TS 类型
│   ├── vite.config.ts
│   └── package.json
│
├── docker-compose.yml             # 完整编排（Milvus + etcd + MinIO）
├── docker-compose.slim.yml        # 精简编排（无向量库）
├── Dockerfile                     # 多阶段构建（Node → Python）
├── deploy.sh                      # 服务器一键部署脚本
├── upload.bat                     # Windows 上传工具
└── .env.example                   # 环境变量模板

📡 API 接口一览

方法 路径 功能 认证
POST /api/auth/register 用户注册 ❌
POST /api/auth/login 登录 → 返回 JWT Token ❌
GET /api/auth/me 当前用户信息 ✅
POST /api/analysis/analyze Agent 错题分析（核心接口） ✅
GET /api/analysis/mistakes/{id} 学生错题历史 ✅
POST /api/knowledge/ 添加知识点 ✅ (admin/teacher)
POST /api/knowledge/search 混合检索（向量 + 关键词） ✅
GET /api/students/ 学生列表 ✅
GET /api/students/{id}/report 学情报告 ✅
GET /api/recommend/path/{id} 学习路径 ✅
POST /api/exercises/generate AI 自动生成练习题 ✅
POST /api/agent/chat SSE 流式 AI 答疑 ✅

完整 API 文档：启动后访问 /docs（Swagger UI）

👣 演示流程

登录后用以下步骤体验完整功能链：

步骤 操作 预期结果
1 用 admin / admin123 登录 进入系统首页，看到学生选择器
2 选择学生 张三 右侧显示学情卡片（错题统计 + 薄弱知识点）
3 输入错题 → 点击提交分析 实时展示 Agent 5 步推理过程（动画）
4 查看分析结果 错误类型、根因、学习建议、递进路径
5 切换到知识点页面 预置的 8 个知识点（含 RAG 向量检索）
6 切换到练习题页面 预置的 6 道练习题，可展开答案
7 切换到错题历史 张三的 3 条错题记录，支持展开学习建议
8 在分析页面底部的聊天框提问 体验 SSE 流式 AI 答疑

🧪 测试

# 后端（pytest）
cd backend
pytest -v --tb=short
# 
# 前端（vitest）
cd frontend-react
npm test

⚠️ 注意事项

事项 说明
API Key 运行前必须在 .env 中配置有效的 Kimi API Key（申请地址）
Milvus Docker 版本已包含 Milvus，本地开发如不需要可跳过 RAG 模块
Embedding 模型 首次调用 RAG 会下载 BAAI/bge-small-zh-v1.5（约 100MB）
数据库 默认 SQLite，如需切换为 PostgreSQL 只需改 .env 中的 DATABASE_URL

📄 License

MIT

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages