# 智教一体化系统

**Repository Path**: elfbobo_admin_admin/Integrated-Smart-Teaching-System

## Basic Information

- **Project Name**: 智教一体化系统
- **Description**: 基于 Spring Cloud Alibaba 微服务架构的 AI 智慧教学平台，系统分为 5 个独立服务——用户服务、课程资源服务、AI智能服务、作业考试服务、学情分析服务，覆盖教学全流程。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-11
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智教一体化系统（Integrated Smart Teaching System）

一个面向培训机构管理的**微服务系统**，内置 **AI 助手**：可对话问答、多步编排查询业务数据、自动批改作业，并对检索与生成质量做了**量化评测闭环**。

> 核心亮点集中在 `ai-service`：Agent 编排 / RAG / 结构化输出 / 评测闭环 / MCP。

---

## 一、技术栈

| 层 | 技术 |
|---|---|
| 语言/框架 | Java 21 · Spring Boot 4.0 · Spring Cloud（Nacos / Sentinel / OpenFeign / Gateway） |
| AI | **Spring AI**（spring-ai-alibaba DashScope 通义千问）· **MCP Server** · Elasticsearch（向量库） |
| 数据 | MySQL（3 库 21 表）· MyBatis · PageHelper |
| 存储 | 阿里云 OSS（文件上传） |
| 安全 | JWT · BCrypt · 角色权限 AOP（`@RequireRole`） |
| 前端 | Vue 3 · Vite · Element Plus · Pinia · ECharts · marked |
| 中间件 | Nacos（注册发现）· Sentinel（熔断限流） |

---

## 二、系统功能概览

- 员工 / 部门 / 学科 / 课程 / 班级 / 学生管理
- 知识点 / 题库（5 种题型）/ 试卷组卷管理
- 作业下发、学生提交、AI 自动批改打分与反馈
- 数据大屏与学情分析（成绩趋势 / 知识点掌握 / 班级对比 / 预警 / 个人报告）
- AI 助手（对话问答 / 多步编排查询 / RAG 知识问答 / 自动批改）
- 三端登录（管理员 / 教师 / 学生）+ 角色权限控制

## 三、系统架构

```mermaid
graph LR
    F[前端 Vue3] -->|/api 代理| G[Gateway :8090]
    G --> U[user-service :8081<br/>员工/部门/学生/登录/文件]
    G --> C[course-service :8082<br/>学科/课程/班级/知识点/题库/试卷]
    G --> A[ai-service :8083<br/>AI助手/RAG/批改/MCP]
    G --> AS[assignment-service :8084<br/>作业/提交]
    G --> R[analytics-service :8085<br/>数据报表]
    A -->|Feign 写操作走业务鉴权| U
    A -->|混合检索| ES[(Elasticsearch :9202)]
    A -->|LLM 调用| DS[DashScope 通义千问]
    U & C & A & AS & R --> M[(MySQL · 3库21表)]
    G -.-> N[Nacos :8848]
    A -.-> S[Sentinel :8858]
```

服务端口与职责：

| 服务 | 端口 | 职责 |
|---|---|---|
| gateway-service | 8090 | 统一路由、鉴权拦截 |
| user-service | 8081 | 员工/部门/学生/登录/文件上传/日志 |
| course-service | 8082 | 学科/课程/班级/知识点/题库/试卷 |
| **ai-service** | 8083 | **AI 助手 / RAG / 自动批改 / MCP / 评测** |
| assignment-service | 8084 | 作业 / 提交 |
| analytics-service | 8085 | 数据报表 / 学情分析 |

---

## 四、AI 能力亮点（核心）

### 1. Agent 多步编排（Function Calling）

把业务查询封装成 `@Tool` 注解方法，LLM 自主决定调用哪些工具、编排多步链路：

- `ClazzTools`：查班级列表 → 定位班级 ID → 查班级学生名单
- `AnalyticsTools`：题库统计 / 查学生成绩 / 班级对比 / 预警学生
- `StudentTools`：新增学生（唯一写操作，走 Feign 复用业务鉴权）

**示例**：用户说「分析 3 班学情」，AI 自主走「查班级 → 查学生 → 查成绩/对比/预警 → 综合成报告」，且最终数字严格来自工具返回，配合 `system.st` 里的「事实锚定 / 多步编排 / 能力边界」反幻觉提示词。

### 2. 工具身份跨线程透传

工具调用发生在流式异步线程，`ThreadLocal` 会丢。用 Spring AI 的 **`ToolContext`** 显式注入 `userId/role`（`.toolContext(...)`），工具内再取回；写操作不裸调 mapper，而是经 Feign 转发到 user-service，复用其校验/加密/鉴权/日志。

### 3. RAG 三段式检索（BM25 + 向量 + RRF + Rerank）

知识点问答不走朴素向量检索，而是自建三段式召回：

1. **混合召回**：ES 同时做 BM25 关键词 + dense_vector 余弦相似（Painless `script_score`）
2. **RRF 融合**：两路结果融合排序
3. **精排**：DashScope `qwen3-rerank` cross-encoder 二次排序

- Embedding：`text-embedding-v2`（1536 维）
- 检索注入：`AiServiceimpl.buildDynamicContext` 把命中的知识点拼进 system prompt

### 4. 文档问答（长文档 chunking）

支持把学生手册、校规等长文档切块（400 字窗口 + 句号边界 + 50 字重叠）、向量化入 ES，做混合检索问答，命中后返回对应 chunk 文本。

### 5. 结构化输出（BeanOutputConverter）

自动批改用 `BeanOutputConverter` + JSON Schema 约束，让 LLM 输出与 `GradeResult` 类型强一致，自动剥离 ```json 代码块并反序列化；保留 `0 ≤ score ≤ 满分` 业务越界校验。

### 6. 端到端生成评测（LLM-as-judge）

不止评测检索（hit@5/MRR），还评测**生成质量**：

- 规则指标：分数 MAE、完全一致率、越界率（零额外 LLM 调用）
- **LLM-as-judge**：二次调用评审「分数合理性 / 评语准确性 / 是否幻觉」

复用生产同一条 `gradeInternal` 纯生成链路（不落库），保证评测即生产。入口 `POST /ai/grading/eval`。

### 7. 流式输出（SSE）

`Flux<String>` 流式 + `SseEmitter` 桥接，前端打字机效果。

### 8. MCP Server

`@Tool` 工具统一注册为 `ToolCallbackProvider`，由 `spring-ai-starter-mcp-server-webmvc` 暴露成 MCP 协议（STREAMABLE，端点 `/mcp`），外部 AI 客户端可标准接入。

### 9. 可移植模型抽象 + 熔断兜底

换模型只换 starter（`spring-ai-alibaba-starter-dashscope`）不动业务代码；AI 接口挂 `@SentinelResource` 熔断兜底，限流时快速返回不再死等 LLM。

---

## 五、量化评测结果

### RAG 检索评测（42 题：easy 30 + hard 12 语义改写）

| 检索方案 | hit@5 | MRR |
|---|---|---|
| 纯向量 | 0.976 | 0.884 |
| 混合检索（BM25+向量+RRF） | 0.976 | 0.900 |
| **混合检索 + rerank 精排** | **1.0** | **0.984**（hard 0.944） |

> 演进价值：rerank 救回唯一 miss，并把正确知识点排名大幅前移（hard MRR 0.593 → 0.944）。评测 harness 支持三种方案对比，入口 `POST /ai/rag/eval/compare`。

### 生成评测（批改质量）

10 份作业（覆盖全对/部分对/全错/未作答），跑批改 → 算分数 MAE / 完全一致率 / 越界率 → LLM-as-judge 评反馈质量。入口 `POST /ai/grading/eval`（需 admin）。

| 指标 | 结果 |
|---|---|
| 分数 MAE（平均绝对分差） | 0.6 |
| 完全一致率 | 0.6 |
| 越界率（分数超出 [0,满分]） | 0 |
| judge 分数合理性 | 1.0 |
| judge 评语准确性 | 1.0 |
| judge 无幻觉率 | 1.0 |

---

## 六、目录结构

```
backend/
├── gateway-service/        # 网关 + 鉴权
├── user-service/           # 员工/部门/学生/登录
├── course-service/         # 学科/课程/班级/知识点/题库/试卷
├── assignment-service/     # 作业/提交
├── analytics-service/      # 报表/学情
├── ai-service/             # ★ AI 域
│   ├── service/impl/AiServiceimpl.java   # 对话编排 + 自动批改
│   ├── tool/               # @Tool 工具（班级/学生/数据）
│   ├── es/                 # 向量灌输 + 三段式检索 + 文档 chunking
│   ├── eval/               # RAG 评测 + 生成评测(LLM-as-judge)
│   └── config/McpConfig    # MCP Server
├── common/  common-dao/    # 公共模块 / 实体与 Mapper
└── sql/reset-data.sql      # 3 库 21 表全量种子数据
frontend/                   # Vue3 + Element Plus
```

---

## 七、快速开始

**前置**：JDK 21、Maven、MySQL、Elasticsearch（9202）、Nacos（8848）

1. 启动中间件：MySQL、Elasticsearch、Nacos
2. 建库：执行 `backend/sql/reset-data.sql`（3 库 21 表 + 种子数据）
3. 配置环境变量：`DASHSCOPE_API_KEY`、`DB_PASSWORD`
4. 依次启动：`gateway-service`、`user-service`、`course-service`、`assignment-service`、`analytics-service`、`ai-service`
5. 前端：`cd frontend && npm install && npm run dev`

**默认账号**：管理员 `admin / 123456`；学生/员工 `123456`（见 `reset-data.sql`）。

---

## 八、关键设计取舍

- **ES 当向量库**：ES 同时提供 dense_vector + BM25，天然适合混合检索；数据量小用不上 Milvus，换专用向量库属过度设计且需额外拼 BM25。
- **检索手写、编排用 Spring AI**：混合检索/rerank 无法用 `VectorStore` 单一抽象表达，故手写；对话编排、工具调用、结构化输出、MCP 用 Spring AI 原生能力。
- **写操作走 Feign 复用鉴权**：AI 工具不裸调 mapper，避免绕过业务校验/权限。
- **评测说明**：RAG 评测集为自建 42 题（样本偏小），满分 1.0 不代表泛化能力，重点是评测闭环方法论与 0.64 → 1.0 的量化演进过程，后续计划引入公开 benchmark。