# thy-edu-agent

**Repository Path**: Leo_lqt/thy-edu-agent

## Basic Information

- **Project Name**: thy-edu-agent
- **Description**: 国内 IT 教育头部企业多智能体实战项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 23
- **Created**: 2026-10-27
- **Last Updated**: 2026-10-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EduAgent — AI 原生教学辅助系统

## 项目简介

EduAgent 是一套 AI 原生的教学辅助系统，将学员答疑、试卷批改、简历审查、模拟面试四类教学业务分别构建为四个专门的智能体（Agent）。每个 Agent 都融合了企业私有知识、内置了完整业务流程，并配备了工程化的容错机制，助力教学场景实现智能化升级。

## 系统架构

EduAgent 采用分层架构设计，各层职责清晰、协同高效：

```
┌─────────────────────────────────────────────────────────┐
│                    Web UI (User Interface)              │
└─────────────────────────────┬───────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────┐
│                    API Layer (FastAPI)                  │
│  Authentication / Request Routing / Streaming Response  │
└─────────────────────────────┬───────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────┐
│                        Orchestrator                     │
│ Intent Recognition / Multi-Agent Pipeline Orchestration │
└─────┬─────────────┬──────────────┬──────────────┬───────┘
      │             │              │              │
┌─────▼─────┐ ┌─────▼────┐  ┌──────▼─────┐ ┌──────▼──────┐
│    QA     │ │   Exam   │  │   Resume   │ │  Interview  │
└─────┬─────┘ └─────┬────┘  └──────┬─────┘ └──────┬──────┘
      │             │              │              │
┌─────▼─────────────▼──────────────▼──────────────▼───────┐
│                      Common Layer                       │
│ LLM Factory / Local Model / Memory Management / Retry   │
└────────────────────────────┬────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────┐
│                         MCP Layer                       │
│    Knowledge Base Retrieval Tool / Web Search Tool      │
└──────────────────┬───────────────────┬──────────────────┘
                   │                   │
          ┌────────▼──────┐    ┌───────▼────────┐
          │     Milvus    │    │   PostgreSQL   │
          └───────────────┘    └────────────────┘
```

## 核心特性

### 四大专业 Agent

| Agent | 业务场景 | 核心能力 |
|-------|---------|---------|
| **智能问答（QA）** | 学员答疑辅导 | RAG 检索增强生成，融合私有知识库，支持 BGE-M3 向量检索与 BGE-Reranker 精排，实现 SSE 流式输出 |
| **试卷批改（Exam）** | 自动批改试卷 | 三轨并行批改策略，HitL（Human-in-the-Loop）人在环机制，确保老师可最终确认批改结果 |
| **简历审查（Resume）** | 简历评估建议 | 结构化信息抽取，多维度并行评分，生成针对性优化建议 |
| **模拟面试（Interview）** | 技术面试陪练 | 状态机驱动的多阶段对话设计，双轨评估（知识掌握+表达能力），全程流式输出 |

### 技术亮点

- **意图路由智能调度**：基于本地轻量模型实现精准意图分类，自动将用户请求路由至对应的专业 Agent
- **本地化部署能力**：关键模型（BGE 系列、MiniLM）本地运行，保障数据隐私与响应速度
- **容错与降级机制**：三级降级重试策略，确保复杂场景下的服务稳定性
- **标准化 MCP 协议**：知识库检索与联网搜索采用 MCP 协议封装，便于扩展与集成

## 技术栈

| 分类 | 技术选型 |
|------|---------|
| **Web 框架** | FastAPI + Uvicorn + SSE（Server-Sent Events） |
| **Agent 框架** | LangGraph（状态图）+ LangChain |
| **大模型** | DeepSeek V4（Flash / Pro），通过 OpenAI 兼容 API 调用 |
| **本地模型** | BGE-M3（向量嵌入）、BGE-Reranker（精排）、all-MiniLM-L6-v2（意图分类） |
| **向量数据库** | Milvus 2.4（Standalone 模式） |
| **关系数据库** | PostgreSQL 15（通过 SQLAlchemy + asyncpg） |
| **MCP 协议** | MCP SDK（知识库检索 + DuckDuckGo 联网搜索） |
| **身份认证** | JWT（python-jose）+ bcrypt 密码哈希 |
| **文档解析** | PyMuPDF（PDF）+ python-docx（Word） |
| **基础设施** | Docker Compose（PostgreSQL + etcd + MinIO + Milvus + Attu） |
| **测试** | pytest + pytest-asyncio |

## 项目结构

```
ThyEduAgent/
├── backend/                      # 后端服务核心代码
│   ├── main.py                   # 应用入口，启动 FastAPI 服务
│   ├── config.py                 # 配置管理（基于 pydantic-settings）
│   ├── dependencies.py           # FastAPI 依赖注入定义
│   ├── api/                      # API 路由层
│   │   ├── router.py             # 路由聚合入口
│   │   └── v1/                   # V1 版本接口
│   │       ├── auth.py           # 用户登录 / JWT 认证接口
│   │       ├── qa.py             # 智能问答接口
│   │       ├── exam.py           # 试卷批改接口
│   │       ├── interview.py      # 模拟面试接口
│   │       ├── resume.py         # 简历审查接口
│   │       └── unified_chat.py   # 统一对话入口（含意图路由）
│   ├── agents/                   # Agent 核心实现
│   │   ├── qa/                   # 问答 Agent
│   │   │   ├── graph.py          #   LangGraph 状态图定义
│   │   │   ├── nodes.py          #   图节点函数实现
│   │   │   ├── prompts.py        #   提示词模板
│   │   │   └── state.py          #   类型化状态 Schema
│   │   ├── exam/                 # 批改 Agent（结构同上）
│   │   ├── resume/               # 简历 Agent（结构同上）
│   │   └── interview/            # 面试 Agent（结构同上）
│   ├── core/                     # 核心公共组件
│   │   ├── llm/                  # 问答 Agent
│   │   │   ├── config.py         # 大模型相关配置
│   │   │   └── factory.py        # 大模型工厂类
│   │   ├── orchestrator.py       # Agent 编排调度器
│   │   ├── query_classifier.py   # 意图分类（基于 MiniLM）
│   │   ├── llm_factory.py        # LLM 工厂（DeepSeek 封装）
│   │   ├── knowledge_base.py     # 向量知识库（BGE-M3 + Milvus）
│   │   ├── reranker.py           # 重排序（BGE-Reranker）
│   │   ├── memory.py             # LangGraph MemorySaver
│   │   ├── retry.py              # 三级降级重试机制
│   │   ├── exceptions.py         # 自定义异常类
│   │   └── logger.py             # 日志配置
│   ├── mcp/                      # MCP 协议实现
│   │   ├── client.py             # MCP 协议客户端
│   │   ├── knowledge_base_server.py  # 知识库检索 MCP 工具
│   │   └── web_search_server.py  # 联网搜索 MCP 工具
│   └── db/                       # 数据库相关
│       └── migrations.py         # 数据库迁移脚本
├── models/                       # 本地模型文件（需单独下载，已 gitignore）
│   ├── classifier/               # 意图分类基座 + query-classifier 微调产物
│   ├── embedding/                # BGE-M3 嵌入模型
│   └── reranker/                 # BGE-Reranker 精排模型
├── samples/                      # 知识库示例讲义（sample2.md）
├── backend/training_data.jsonl   # 意图分类训练数据
├── scripts/                      # 实用脚本
│   ├── init_db.sql               # PostgreSQL 初始化脚本
│   ├── init_milvus.py            # Milvus 集合初始化
│   ├── build_knowledge_base.py   # 知识库文档导入
│   ├── seed_data.py              # 测试数据填充
│   └── verify_env.py             # 环境自检脚本
├── docker-compose.yml            # Docker 基础设施编排
└── requirements.txt              # Python 依赖清单
```

## 快速开始

### 环境要求

- **Python**: 3.12 或更高版本
- **Docker**: 29+ 及 Docker Compose
- **conda**: 推荐用于项目虚拟环境管理

### 步骤 1：克隆项目

```bash
git clone https://gitee.com/jackfrued/thy-edu-agent.git ThyEduAgent
cd ThyEduAgent
```

### 步骤 2：创建虚拟环境

```bash
# 使用 conda 创建
conda create -n edu_agent python=3.12
conda activate edu_agent

# 或使用 venv
python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt
```

### 步骤 3：启动基础设施

```bash
docker compose up -d
```

启动成功后，以下服务将运行在后台：

| 服务 | 端口 | 说明 |
|------|------|------|
| PostgreSQL | 5433 | 关系数据库 |
| Milvus | 19531 | 向量数据库 |
| Attu | 30000 | Milvus 可视化管理界面 |

> **说明**：PostgreSQL 没有使用默认端口 5432，改成了 5433，请在使用客户端工具接入时，记得修改端口设置。

### 步骤 4：下载本地模型

RAG 智能问答需要三个本地模型，放到 `models/` 下（目录已加入 `.gitignore`）：

| 模型 | 默认路径 | 用途 |
|------|---------|------|
| BAAI/bge-m3 | `models/embedding/bge-m3` | 稠密 + 稀疏双向量嵌入（约 2.3GB） |
| BAAI/bge-reranker-large | `models/reranker/bge-reranker-large` | CrossEncoder 精排（约 2.2GB） |
| sentence-transformers/all-MiniLM-L6-v2 | `models/classifier/all-MiniLM-L6-v2` | 意图分类基座（约 90MB） |

推荐使用 modelscope 命令行工具，下载时指定 `local_dir`：

```bash
modelscope download --model BAAI/bge-m3 --local_dir models/embedding/bge-m3
modelscope download --model BAAI/bge-reranker-large --local_dir models/reranker/bge-reranker-large
modelscope download --model sentence-transformers/all-MiniLM-L6-v2 --local_dir models/classifier/all-MiniLM-L6-v2
```

> 如果模型已经存在于其他目录，也可以直接创建目录联接（Windows，无需管理员权限）：
> `mklink /J models\embedding\bge-m3 <已有模型目录>`。Linux/macOS 用 `ln -s`。

微调意图分类器（生成 `models/classifier/query-classifier`，只需运行一次）：

```bash
python scripts/train_query_classifier.py
```

未训练时会自动退化为关键词规则，问答链路仍可运行。

### 步骤 5：初始化数据库和知识库

```bash
# 建表 + 填充测试用户（student01 / Student@123456）
python scripts/seed_data.py

# 创建 Milvus 集合 knowledge_domain（会清空旧集合）
python scripts/init_milvus.py

# 导入知识库文档（示例讲义 + 跳过 Contextual RAG 以节省 LLM 配额）
python scripts/build_knowledge_base.py --file samples/sample2.md --no-context

# 正式导入时可启用 Contextual RAG（需要有效 DEEPSEEK_API_KEY）
python scripts/build_knowledge_base.py --file samples/sample2.md
```

`build_knowledge_base.py` 支持 PDF / Markdown；更新同一文档时请保留上次输出的 `--doc-id`，实现幂等覆盖。

### 步骤 6：配置环境变量

新建一个 `.env` 文件并向其中填入必要的配置信息，部分内容如下所示：

```
MILVUS_HOST=localhost
MILVUS_PORT=19531

DEEPSEEK_API_KEY=sk-xxxxxx
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL_CHAT=deepseek-flash
DEEPSEEK_MODEL_CODER=deepseek-flash
```

### 步骤 7：启动服务

```bash
python backend/main.py
```

服务启动后，API 文档可访问：`http://localhost:8000/docs`

### 步骤 8：环境自检（可选）

```bash
python scripts/verify_env.py
```

该脚本将检查所有依赖服务状态、模型文件完整性以及环境变量配置。

## API 接口概览

| 接口路径 | 方法 | 功能说明 |
|---------|------|---------|
| `/api/v1/auth/login` | POST | 用户登录，获取 JWT Token |
| `/api/v1/auth/refresh` | POST | 使用 Refresh Token 续签 Access Token |
| `/api/v1/auth/logout` | POST | 退出登录（Access Token 加入黑名单） |
| `/api/v1/auth/me` | GET | 获取当前登录用户信息 |
| `/api/v1/chat` | POST | 统一对话入口，由 Orchestrator 自动路由到对应 Agent（待接入） |
| `/api/v1/qa/chat` | POST | 知识库问答（RAG / HyDE / Multi-Query / Web 兜底） |
| `/api/v1/qa/chat/stream` | POST | 知识库问答（SSE 流式：progress / token / meta / done） |
| `/api/v1/qa/sessions/{session_id}/history` | GET | 查看会话消息历史与学习摘要 |
| `/api/v1/exam/grade` | POST | 提交试卷图片/文档进行智能批改（待接入） |
| `/api/v1/resume/review` | POST | 提交简历 PDF，后台异步执行审查 |
| `/api/v1/resume/reviews` | GET | 查看当前用户/租户的简历审查记录 |
| `/api/v1/resume/reviews/{id}` | GET | 查看单份简历审查状态与结果 |
| `/api/v1/interview/start` | POST | 开始一轮模拟面试会话（待接入） |
| `/api/v1/interview/respond` | POST | 面试过程中提交回答，继续对话（待接入） |
| `/mcp/kb/mcp` | POST | 知识库检索 MCP Server（JSON-RPC 2.0） |
| `/mcp/search/mcp` | POST | 联网搜索 MCP Server（JSON-RPC 2.0） |
| `/health` | GET | 服务健康检查 |

> **当前进度**：登录鉴权、简历审查、RAG 智能问答（离线建库 + 混合检索 + 精排 + 意图分类 + 多轮记忆 + MCP 工具 + SSE）已实现；Exam / Interview / 统一对话的请求契约与鉴权已就位，Agent 接入前返回 `501 Not Implemented`。
>
> ⚠️ **运行前提**：问答 / 简历 / 批改 / 面试的生成步骤都需要有效的大模型 Key。虽然变量名是 `DEEPSEEK_*`，但本质是 OpenAI 兼容接口，可接入任意兼容服务。默认 DeepSeek 官方配置：
>
> ```ini
> DEEPSEEK_API_KEY=sk-xxxxxx
> DEEPSEEK_BASE_URL=https://api.deepseek.com
> DEEPSEEK_MODEL_CHAT=deepseek-flash
> DEEPSEEK_MODEL_REASONER=deepseek-v4-pro
> ```
>
> 也可切换到阿里云百炼 / 通义千问（已验证）：
>
> ```ini
> DEEPSEEK_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
> DEEPSEEK_MODEL_CHAT=qwen-plus
> DEEPSEEK_MODEL_REASONER=qwen-max
> ```
>
> Key 无效或不可用时接口不会 500，而是返回兜底话术（`fallback_used=true`），便于先验证检索和流程。

## 使用限制

本项目仅用于黑马程序员内部学习和研究目的。