# AutoGrating

**Repository Path**: guardianangel/auto-grating

## Basic Information

- **Project Name**: AutoGrating
- **Description**: 自动批改实验作业的系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

以下是为您编写的说明文档，使用 Markdown 格式，语言通俗易懂：

---

# 🎓 AI 自动化作业批改系统 (AI Grading System)

## 📖 项目简介

这是一款基于 Python 和 AI 大模型的自动化作业批改神器！它能把老师从繁琐的重复劳动中解放出来。

以前改作业：手动解压 -> 看代码 -> 运行 -> 填Excel分数 -> 下一个。  
现在：**上传全班压缩包 -> 系统自动解压 -> AI 自动看题、跑代码、对答案 -> 自动生成成绩单。**  

不仅支持传统的Python脚本批改，更集成了强大的 AI 能力，可以根据你的试卷和评分标准，**自动生成**专属的批改逻辑代码！

---

## ✨ 核心亮点

* **🤖 AI 帮你写代码**：不懂编程？没关系。你只需要上传“试卷文档”和“评分细则”，系统自动调用大模型（如 DeepSeek, ChatGPT, 豆包等）帮你写出一段 Python 批改脚本。
* **🔥 热重载技术**：生成的批改核心（Grader）即写即用，不需要重启服务器，立马就能去改学生的作业。
* **🧩 高度自由的 AI 配置**：支持多家 AI 厂商（OpenAI 协议、火山引擎等）。你可以自由配置用哪家的模型、用哪个版本、权重多少。想用便宜的模型跑简单题，聪明的模型跑难题？完全没问题！
* **📂 全自动流程**：
* **自动解压**：不管学生交的是 zip 还是 rar，系统统统解压好。
* **智能匹配**：自动根据文件名识别是哪个学生的作业。
* **一键重批**：觉得评分标准不合适？改一下核心，点一下重批，全班成绩秒更新。


* **📊 成绩一键导出**：批改完后，直接下载 Excel 成绩单，连“扣分详情”都给你列得清清楚楚。
* **🏠 数据安全**：代码完全开源，支持本地部署。所有学生作业、成绩数据都在你自己的电脑或服务器上，不用担心隐私泄露。

---

## 🎯 适用场景

* **计算机类课程**：非常适合批改 Python、C、Java 等编程作业（代码能否运行、输出是否正确）。
* **客观题批改**：如果学生提交的是文档，可以通过正则匹配或 AI 识别关键词来打分。
* **大作业评审**：检查文件结构、是否包含特定素材、文件命名规范等。

---

## 🛠️ 部署指南 (小白版)

### 1. 环境准备

确保你的电脑安装了：

* **Python 3.8+**
* **SQLite** (通常 Python 自带)

### 2. 安装依赖

在项目根目录下，打开终端（CMD 或 Terminal），运行：

```bash
pip install -r requirements.txt
```

### 3. 初始化配置

项目第一次运行时会自动创建数据库文件。
**重要**：第一次启动后，你需要先配置 AI 模型才能使用“自动生成核心”功能。  

### 4. 启动服务

运行后端：
```bash
python app.py
```

> 看到类似 ` * Running on http://127.0.0.1:5010` 的提示，说明启动成功了！


运行AI助手：
```bash
python ai_helper.py
```
> 看到 `[AI SERVER] 启动中... 监听 127.0.0.1:9011` 提示，说明 AI 助手启动成功。

---

## 🚀 详细使用说明

### 第一步：管理员配置 AI (至关重要!)

因为系统生成批改核心需要用到 AI，所以第一件事是告诉系统用谁家的 AI。

1. 浏览器访问后台管理地址：`http://127.0.0.1:5000/admin/login`
2. 默认账号密码：
   * 账号：`admin`
   * 密码：`admin123`
    > 也可以在 `config.py` 中找到 `ADMIN_PASSWORD` 修改初始密码  
   
3. **添加服务商 (Provider)**：
   * 点击“新增服务商”。
   * **厂商名称**：随便填，比如 `DeepSeek` 或 `火山引擎`。
   * **协议类型**：
   * `OpenAI Compatible`：适用于 DeepSeek, ChatGPT, Moonshot 等大多数模型。
   * `Volcengine`：适用于字节跳动的豆包模型。

   * **API Key**：填你在官网申请的 Key。
   * **Base URL**：如果是 OpenAI 协议，记得填转发地址（例如 DeepSeek 是 `https://api.deepseek.com`）。

4. **添加模型 (Model)**：
   * 在刚添加的厂商卡片里，点击“添加模型”。
   * **模型真实 ID**：填模型官网给的代码名（例如 `deepseek-chat` 或 `doubao-pro-32k`）。
   * **能力类型**：
   * `Thinking` (深度思考)：用来**生成批改核心代码**（推荐选这个，逻辑更强）。
   * `Standard` (通用对话)：用来做简单的辅助。
   * `Vision` (视觉)：留作备用，暂未启用。

   * **权重**：默认 50，如果有多个模型，权重高的会被优先调用。



### 第二步：生成你的“批改核心”

这是最神奇的一步！

1. 回到前台首页：`http://127.0.0.1:5000`
2. 点击 **"AI 核心生成工坊"**。
3. 填写信息：
   * **核心名称**：例如“2025春季Python期末考试”。
   * **上传试卷**：把你的题目文档传上去。
   * **上传评分细则**：告诉 AI 怎么扣分（例如“没写注释扣5分，运行报错0分”）。
   * **严格度**：选“严格”还是“宽松”。

4. 点击生成。系统会调用你刚才配置的 AI，帮你写出一个 Python 脚本（`xxx.py`），并自动加载到系统中。
5. 生成成功后，你可以在列表中看到它，甚至点击进去**查看和修改源码**。

### 第三步：创建班级并批改

1. **新建班级**：
   * 在首页点击“新建班级/任务”。
   * 上传**学生名单**（Excel表，必须包含“学号”和“姓名”列）。
   * 选择刚才生成的“批改策略”（核心）。

2. **上传作业**：
   * 进入班级页面。
   * 点击“上传作业包”，把全班学生的压缩包（zip/rar）一股脑拖进去。

3. **开始批改**：
   * 点击“运行自动批改”。
   * 系统会自动解压，匹配学号，调用那个 AI 生成的脚本去跑每个学生的作业。
   * 几秒钟后，分数和扣分原因就出来了！



### 第四步：查看结果与导出

* **查看详情**：点击某个学生，可以看到他提交的文件列表、解压后的代码，甚至手动帮他改分。
* **一键清空**：如果发现评分标准错了（比如 AI 写的代码太严了），你可以去修改核心代码，然后点击“清空数据”，重新跑一遍批改。
* **导出成绩**：点击“导出 Excel”，一份完美的成绩单就到手了。

---

## 📡 接口说明 (API)

虽然主要是界面操作，但如果你想二次开发，这些核心接口可能有用：

* **管理端接口 (`/admin/...`)**:
* `/provider/add`: 添加 AI 厂商。
* `/model/add`: 添加具体的模型配置。
* `/provider/toggle/...`: 快速开关某个厂商（例如欠费了暂时关掉）。

* **核心功能接口**:
* `/api/create_grader_task`: 提交试卷和标准，触发 AI 生成核心代码。
* `/api/save_grader_code`: 手动修改并保存核心代码（支持热更）。
* `/run_grading_logic/<class_id>`: 触发某班级的批量批改任务。

---

## ❓ 常见问题 (Q&A)

**Q: AI 生成的代码不准怎么办？**
A: 你可以在生成页面的“额外指令”里多写点要求，或者生成后直接点击核心，手动修改 Python 代码。系统支持你改完代码直接点保存，不用重启就能生效。

**Q: 学生文件名乱七八糟怎么办？**
A: 系统内置了智能匹配逻辑，只要文件名里包含“学号”或“姓名”，一般都能识别出来。

**Q: 为什么第一次进去不能生成核心？**
A: 一定要先去 `/admin` 配置 AI 模型！没有模型，系统就没有“脑子”去写代码。