SkyLiCoder/WiseGrade

Fork 1

Files

T

SkyLiCoder f7a9091c86 docs: define WiseGrade technical specification

2026-09-25 00:44:32 +08:00

20 KiB

Raw Blame History

WiseGrade（智评）技术方案与开发规格

1. 项目概述

1.1 基本信息

英文名：WiseGrade
中文名：智评
当前服务课程：自动化专业综合实践
使用对象：教师
部署形态：个人电脑本地部署
当前开发环境：Linux
目标运行环境：Linux、Windows（Docker Desktop）
主要大模型：deepseek-flash
主要能力：课程材料管理、学生材料批量导入、RAG 辅助评分、教师复核、成绩和反馈导出

1.2 项目目标

构建一个前后端分离的自动评分系统，对自动化专业综合实践课程中的以下材料进行内容评分：

阶段报告 1
阶段报告 2
阶段报告 3
最终报告
汇报 PPT，或 PPT 导出的 PDF

系统输出可复核的逐项评分、原文证据、页码或幻灯片编号、缺失内容、评语和改进建议。

1.3 非目标

第一版不实现：

学生账号和在线提交
现场口头答辩、答辩视频和语音评分
学生个人贡献度自动识别
代码仓库自动审查
AI 生成内容检测
自动控制实验硬件的远程接入

课程评分表中的“汇报答辩 40 分”保留原名称，但本系统只依据 PPT 内容或 PPT PDF 内容评分，不评价现场口头答辩。

2. 已确定的业务规则

2.1 教师使用流程

系统只供教师使用，采用单机单管理员模式。教师不需要创建学生账号。

教师流程：

选择课程和学期
  -> 选择评分规则版本
  -> 选择挂载数据目录中的学生总文件夹
  -> 扫描学生子文件夹
  -> 自动识别学生信息和五类材料
  -> 教师确认导入结果
  -> 批量解析和评分
  -> 查看模型评分和证据
  -> 修改分数和评语
  -> 导出 Excel 成绩表和逐生 PDF 反馈

2.2 学生目录结构

宿主机数据目录示例：

WiseGradeData/
└── 2026春季第1批/
    ├── 1023009006_李傲琦_基于ROS2系统的自瞄移动机器人/
    │   ├── 阶段报告1.pdf
    │   ├── 阶段报告2.pdf
    │   ├── 阶段报告3.pdf
    │   ├── 自动化专业综合实践报告.pdf
    │   └── 汇报PPT.pptx
    └── 其他学生/

学生目录命名格式：

学号_姓名_选题题目

文件夹名称只用于初步识别。系统还要从文件首页、标题和正文中抽取姓名、学号、项目题目和选题方向，并在不一致时提醒教师确认。

2.3 支持文件

支持：

PDF
DOCX
PPTX
PPT 导出的 PDF

不支持旧版 .doc 作为学生输入。

PPT PDF 必须在导入确认阶段标记为“汇报材料”，以免与最终报告 PDF 混淆。

2.4 成绩结构

总评成绩：

总评 = 阶段报告1 × 10%
     + 阶段报告2 × 10%
     + 阶段报告3 × 10%
     + 期末成绩 × 70%

期末评分保持课程评分表结构：

评分项	分值
任务完成度	20
报告规范性	20
汇报答辩（系统仅按 PPT 内容评价）	40
结果分析	20

2.5 评分批次

每次评分创建独立批次。批次之间不覆盖、不替代，也不设置唯一“正式批次”。每个批次均可查看、复核和导出。

批次必须保存：

课程版本
评分规则版本
课程目标版本
deepseek-flash 模型配置快照
嵌入模型名称和版本
创建时间和结束时间
评分任务状态

3. 课程和评分依据

初始资料位于 docs/：

课程导学-自动化专业综合实践.pdf
自动化专业综合实践三融合选题课程概述.pdf
大作业评分表-自动化专业综合实践.docx
阶段报告1模板.doc
阶段报告2模板.doc
阶段报告3模板.doc
阶段报告1.pdf
阶段报告2.pdf
阶段报告3.pdf
自动化专业综合实践报告.pdf

3.1 课程目标和毕业要求指标点

系统初始知识库必须包含并建立关联：

课程目标 1：问题解决与研究能力
课程目标 2：知识运用与分析能力
课程目标 3：实验设计与操作能力
课程目标 4：数据处理与报告撰写能力
毕业要求指标点 2.3、2.4
毕业要求指标点 4.1、4.2、4.3、4.4
毕业要求指标点 11.1、11.2

3.2 阶段报告要求

阶段报告 1：复杂自动化工程问题解决方案论证报告

重点内容：

文献调研和技术现状
复杂工程问题分析
主方案和至少一套替代方案
方案原理、适用场景和优劣对比
数理或工程依据下的可行性论证
进度计划、资源配置、成本构成和经济性分析

初始评分框架：

评分项	分值
复杂工程问题和需求分析	25
文献调研和技术现状总结	20
主方案和替代方案设计	25
可行性、风险和合理性论证	15
工程管理、进度和成本分析	10
报告完整性和规范性	5
合计	100

阶段报告 2：实验系统设计与硬件搭建方案

重点内容：

硬件选型清单、参数和依据
系统架构图、硬件连接或接口关系
分步骤实验计划、测试方法和预期指标
安全风险、防护措施和操作规范

初始评分框架：

评分项	分值
系统架构和实现思路	20
硬件选型及选型依据	20
系统框图、连接关系和接口设计	20
实验方案、测试方法和预期指标	20
安全风险和防护措施	10
阶段进展及下一阶段计划	10
合计	100

阶段报告 3：软件设计与系统调试报告

重点内容：

软件逻辑、流程图或状态图
核心代码片段和实现说明
调试过程、故障现象、原因和解决方法
实验数据整理和初步分析
系统功能、性能指标和存在问题

初始评分框架：

评分项	分值
软件逻辑和系统实现	20
核心代码和功能说明	20
调试过程、问题分析和解决方法	20
实验数据和初步分析	20
功能和性能指标验证	15
下一阶段计划及报告规范性	5
合计	100

阶段评分框架必须作为可编辑的初始规则导入，不能写死在业务代码中。

4. 总体架构

React 前端
    |
FastAPI 后端
    |-- 课程、版本和规则管理
    |-- 挂载目录扫描和导入
    |-- 文档解析和事实抽取
    |-- RAG 检索
    |-- 评分编排和批次管理
    |-- 教师复核
    |-- Excel/PDF 导出
    |
PostgreSQL + pgvector
Redis + RQ
本地文件存储
本地 BGE-M3 嵌入模型
DeepSeek API（deepseek-flash）

采用模块化单体后端，不在第一版拆分成大量微服务。模块边界清晰，后续可以拆分。

4.1 推荐技术栈

前端：React、TypeScript、Vite、Ant Design
后端：Python、FastAPI、SQLAlchemy、Pydantic
数据库：PostgreSQL、pgvector
后台任务：Redis、RQ
PDF 解析：PyMuPDF
DOCX 解析：python-docx
PPTX 解析：python-pptx
页面转换：LibreOffice headless
OCR：PaddleOCR，扫描 PDF 时作为回退
本地嵌入：BAAI/bge-m3
模型调用：OpenAI 兼容客户端，统一模型名 deepseek-flash
Excel：openpyxl 或 pandas
PDF 反馈：HTML/CSS + WeasyPrint 或 Playwright
部署：Docker Compose

5. 宿主机目录挂载方案

原始学生材料不通过浏览器上传。前端只选择后端可见的挂载目录下的大文件夹，后端扫描和读取文件。

5.1 Docker 挂载

volumes:
  - ${WISEGRADE_DATA_DIR}:/data/inbox:ro
  - ./data/processed:/data/processed
  - ./data/exports:/data/exports
  - ./models:/models:ro

Linux 示例：

WISEGRADE_DATA_DIR=/home/teacher/WiseGradeData

Windows 示例：

WISEGRADE_DATA_DIR=D:/WiseGradeData

Windows 使用 Docker Desktop 时，教师需要允许 Docker Desktop 访问对应磁盘。

5.2 路径安全

后端只允许访问 /data/inbox
前端只提交挂载目录内的相对路径
禁止提交绝对路径
后端必须执行路径规范化和越界检查
原始输入目录只读挂载
解析结果、任务状态和导出文件写入独立目录

5.3 文件变更检测

导入时保存：

相对路径
文件大小
修改时间
SHA-256
MIME 类型
解析状态

若文件哈希未变化，不重复解析和向量化。源文件变化时提示重新导入。

6. 文档解析和结构化

6.1 统一文档对象

每个文档解析为：

{
  "document_type": "stage1",
  "source_path": "...",
  "pages": [
    {
      "page_number": 1,
      "text": "...",
      "tables": [],
      "images": [],
      "rendered_image_path": "..."
    }
  ]
}

必须保留页码、章节名、表格和图片关联。

6.2 文件识别

支持通过以下信号识别材料类型：

文件名关键词
文件扩展名
文档标题
首页文本
章节标题
PPT 页数和标题

识别结果包括：

确定
不确定
缺失
重复
无法解析

不确定的文件进入教师确认界面。

6.3 PPT/PDF 视觉处理

提取 PPT 原生文字、表格和备注
将每一页渲染为图片
PDF 每页保存页面图像
评分相关页面连同文字一起发送给 deepseek-flash
图片证据必须关联页码或幻灯片编号

7. RAG 方案

7.1 知识库分层

公共课程知识库

课程导学
课程目标
毕业要求指标点
评分表
三个阶段模板
各选题方向要求
优秀报告
课程版本资料

学生项目知识库

每个学生独立命名空间：

course_2026/project_1023009006/
  stage1/
  stage2/
  stage3/
  final_report/
  presentation/

禁止评分时检索其他学生的材料。

7.2 文本切分

按标题和章节进行结构感知切分
普通文本块约 400～800 个中文字符
重叠约 80～120 个中文字符
表格单独保存
图片及图片说明单独保存
每块必须保留页码、章节、文档类型和评分指标关联

7.3 检索

采用混合检索：

PostgreSQL 全文检索
+ pgvector 向量检索
+ 课程版本过滤
+ 学生项目过滤
+ 报告类型过滤
+ 阶段过滤

默认每个评分项取 8～12 个候选证据块，去重后送入模型。

7.4 嵌入模型

默认：

BAAI/bge-m3

低配置电脑可配置：

BAAI/bge-small-zh-v1.5

模型通过独立离线包提供，不在应用镜像中强制在线下载。配置中保存模型名称、版本和本地路径。

8. DeepSeek 接入

8.1 统一模型

只使用一个模型配置：

provider: deepseek
base_url: https://api.deepseek.com
model: deepseek-flash

同一个模型负责：

文本理解
图像理解
事实抽取
评分
评语生成
PPT 分析
跨文档一致性检查

8.2 密钥管理

教师可以在设置页面配置：

API Key
Base URL
模型名
并发数
超时时间
重试次数

安全要求：

前端不直接调用 DeepSeek
API Key 只发送给后端
数据库保存加密后的密钥
日志禁止输出 API Key
支持环境变量初始化

8.3 发送数据范围

原始文件保存在本地。模型请求只发送当前评分项所需的：

文本证据块
表格内容
必要的页面图片
课程评分标准
已抽取的项目事实

不把全部报告无条件重复发送给每一个评分项。

9. 评分引擎

评分采用多阶段流程：

文件导入
  -> 文档解析
  -> 项目事实抽取
  -> 规则检查
  -> 指标级 RAG 检索
  -> 指标级评分
  -> 跨文档一致性检查
  -> 分数汇总
  -> 教师复核

9.1 事实抽取

抽取：

学号、姓名、项目名称
选题方向
功能目标
性能指标
硬件型号
软件技术
实验方案
实验数据
进度计划
成本信息
结论和改进方向

9.2 评分输出

每个评分项必须返回结构化 JSON：

{
  "criterion_id": "stage1.solution_design",
  "score": 17,
  "max_score": 20,
  "reason": "...",
  "evidence": [
    {
      "document": "阶段报告1",
      "page": 12,
      "quote": "..."
    }
  ],
  "missing_evidence": ["..."],
  "suggestion": "...",
  "confidence": 0.84
}

模型不得对没有证据的内容自行假设。结构化输出必须经过 Pydantic 校验；失败时自动重试或进入人工处理。

9.3 跨文档一致性

至少检查：

阶段 1 计划是否在阶段 2、3 中落实
各报告中的项目名称、硬件型号和技术路线是否一致
实验数据是否前后一致
最终报告和 PPT 是否描述同一成果
指标是否存在明显夸大或矛盾

10. 规则配置和版本管理

规则不能写死在 Prompt 或 Python 代码中。

10.1 评分指标结构

criterion_id: stage1.solution_feasibility
name: 方案合理性与可行性
max_score: 15
description: 评价方案是否具有工程依据、可实施性和风险分析
linked_outcomes: [2.3, 2.4, 4.1]
required_evidence:
  - 主方案
  - 替代方案
  - 方案比较
  - 风险分析
score_levels:
  - min: 12
    max: 15
    description: 论证充分，方案比较清晰，风险分析具体
  - min: 6
    max: 11
    description: 基本完成论证，但证据或分析不充分
  - min: 0
    max: 5
    description: 缺少核心论证

10.2 版本要求

课程、课程目标、毕业要求、模板、评分规则和 Prompt 都需要版本号。评分批次保存完整版本快照。

教师修改规则后创建新版本，不覆盖历史版本。

11. 核心数据表

建议至少包含：

courses
course_versions
course_objectives
graduation_indicators
topic_directions
rubric_versions
rubric_criteria
rubric_score_levels
knowledge_documents
knowledge_chunks
students
projects
submissions
submission_files
scoring_batches
criterion_scores
score_evidences
teacher_revisions
export_tasks
app_settings
audit_logs

11.1 评分批次

scoring_batches
  id
  course_version_id
  rubric_version_id
  model_name
  model_config_snapshot
  embedding_model_name
  embedding_model_version
  status
  created_at
  finished_at

11.2 评分项结果

criterion_scores
  id
  batch_id
  project_id
  criterion_id
  model_score
  teacher_score
  final_score
  model_comment
  teacher_comment
  confidence
  status

final_score = teacher_score（存在时）或 model_score

模型原始结果不得被教师修改覆盖。

12. 前端页面

第一版页面建议：

仪表盘
课程管理
课程版本和评分规则管理
课程资料/知识库管理
数据目录扫描与导入确认
学生项目列表
评分批次列表
批量评分进度
学生评分详情
证据和页码查看
教师复核
Excel/PDF 导出
模型和系统设置

13. 后端 API 初稿

课程和规则

GET    /api/courses
POST   /api/courses
GET    /api/courses/{id}/versions
POST   /api/courses/{id}/versions
GET    /api/rubrics/{version_id}
PUT    /api/rubrics/{version_id}
POST   /api/rubrics/{version_id}/publish

文件扫描和项目导入

GET    /api/storage/directories
GET    /api/storage/directories/{relative_path}/children
POST   /api/import/scan
POST   /api/import/confirm
GET    /api/projects
GET    /api/projects/{id}

评分

POST   /api/scoring-batches
GET    /api/scoring-batches
GET    /api/scoring-batches/{id}/progress
POST   /api/scoring-batches/{id}/start
GET    /api/scoring-batches/{id}/scores
GET    /api/projects/{id}/scores?batch_id={batch_id}
PUT    /api/criterion-scores/{id}/review

导出

POST   /api/exports/excel
POST   /api/exports/project-pdf
GET    /api/exports/{id}

14. 缺失和异常处理

材料状态：

已提交
缺失
重复
无法解析
内容不完整
待人工确认

处理原则：

缺失阶段报告：该阶段进入待人工处理，不默认静默给零分
缺失 PPT：汇报材料项显示无法评分
缺少章节：按照对应评分项判断并扣分
文件损坏：进入人工确认列表
DeepSeek 调用失败：自动有限重试，仍失败则标记评分项失败
评分批次允许部分完成，但导出时必须显示未完成项目

15. 模型离线分发

bge-m3 不依赖启动时在线下载。推荐单独提供模型包：

WiseGrade-release/
├── docker-images.tar
├── models-bge-m3.tar.zst
├── docker-compose.yml
├── .env.example
└── README.md

也支持将模型目录放在：

./models/bge-m3/

容器只读挂载：

volumes:
  - ./models:/models:ro

在线下载脚本是可选工具，不得成为系统正常启动的前置条件。

16. 测试要求

16.1 单元测试

目录扫描
学号/姓名/题目解析
文件类型识别
路径越界防护
文件哈希检测
规则权重计算
缺失材料处理
分数汇总
评分 JSON 校验
版本绑定

16.2 集成测试

从示例材料导入到项目生成
PDF/DOCX/PPTX 解析
PPT PDF 识别
知识库入库和检索
模型 API mock 调用
评分批次创建、运行和查询
教师修改分数
Excel 导出
PDF 反馈导出

16.3 验收测试

至少使用当前 docs/ 中的示例材料完成一次完整流程：

扫描目录
  -> 导入学生项目
  -> 解析五类材料
  -> 创建评分批次
  -> mock 或真实调用 deepseek-flash
  -> 查看逐项证据
  -> 修改分数
  -> 导出 Excel
  -> 导出学生 PDF 反馈

不应在测试中提交真实 API Key。使用环境变量或 mock 服务。

17. Git 开发要求

开发前初始化 Git：

git init

必须创建合理的 .gitignore，至少忽略：

.env
data/processed/
data/exports/
models/
__pycache__/
.pytest_cache/
node_modules/
dist/
*.pyc

开发和测试过程中按阶段提交，推荐提交节点：

chore: initialize project structure
feat: add backend foundation
feat: add course and rubric versioning
feat: add mounted directory scanning
feat: add document parsing pipeline
feat: add knowledge base and hybrid retrieval
feat: add deepseek-flash adapter
feat: add scoring batch orchestration
feat: add teacher review workflow
feat: add excel and pdf exports
test: add integration coverage
docs: add deployment and usage guides

每个提交应保持可理解、可回退、尽量可运行。禁止把 API Key、真实学生隐私数据和模型权重提交到 Git。

18. 开发优先级

P0：可运行骨架

Git、README、Docker Compose
前端和后端健康检查
数据库迁移
单管理员设置

P1：课程和导入

课程版本和规则配置
挂载目录扫描
学生目录识别
文件识别和导入确认

P2：解析和知识库

PDF/DOCX/PPTX 解析
页面渲染
OCR 回退
BGE-M3 嵌入
pgvector 混合检索

P3：评分

事实抽取
指标级 RAG 评分
跨文档一致性检查
批次状态和失败重试

P4：复核和导出

教师修改分数和评语
Excel 成绩表
逐生 PDF 反馈
审计日志

P5：验收和部署

示例材料完整验收
Linux 部署文档
Windows Docker Desktop 部署文档
离线模型包说明

19. 完成标准

当以下条件全部满足时，第一版系统完成：

Linux 上可以通过 Docker Compose 启动
Windows Docker Desktop 有明确部署步骤
教师可以选择挂载目录下的大文件夹
系统可以识别每个学生目录
支持五类材料和 PPT PDF
规则、课程目标和课程版本可编辑
可创建独立评分批次
使用本地嵌入模型完成检索
使用 deepseek-flash 完成文本和图像评分
每项评分显示证据和页码/幻灯片编号
教师可以修改分数和评语
每个批次都可以导出 Excel 和逐生 PDF
示例材料可以完成端到端测试
Git 历史包含清晰的阶段提交

20 KiB Raw Blame History Unescape Escape

WiseGrade（智评）技术方案与开发规格

1. 项目概述

1.1 基本信息

1.2 项目目标

1.3 非目标

2. 已确定的业务规则

2.1 教师使用流程

2.2 学生目录结构

2.3 支持文件

2.4 成绩结构

2.5 评分批次

3. 课程和评分依据

3.1 课程目标和毕业要求指标点

3.2 阶段报告要求

阶段报告 1：复杂自动化工程问题解决方案论证报告

阶段报告 2：实验系统设计与硬件搭建方案

阶段报告 3：软件设计与系统调试报告

4. 总体架构

4.1 推荐技术栈

5. 宿主机目录挂载方案

5.1 Docker 挂载

5.2 路径安全

5.3 文件变更检测

6. 文档解析和结构化

6.1 统一文档对象

6.2 文件识别

6.3 PPT/PDF 视觉处理

7. RAG 方案

7.1 知识库分层

公共课程知识库

学生项目知识库

7.2 文本切分

7.3 检索

7.4 嵌入模型

8. DeepSeek 接入

8.1 统一模型

8.2 密钥管理

8.3 发送数据范围

9. 评分引擎

9.1 事实抽取

9.2 评分输出

9.3 跨文档一致性

10. 规则配置和版本管理

10.1 评分指标结构

10.2 版本要求

11. 核心数据表

11.1 评分批次

11.2 评分项结果

12. 前端页面

13. 后端 API 初稿

课程和规则

文件扫描和项目导入

评分

导出

14. 缺失和异常处理

15. 模型离线分发

16. 测试要求

16.1 单元测试

16.2 集成测试

16.3 验收测试

17. Git 开发要求

18. 开发优先级

P0：可运行骨架

P1：课程和导入

P2：解析和知识库

P3：评分

P4：复核和导出

P5：验收和部署

19. 完成标准

20 KiB

Raw Blame History