Files

T

aerospaceboy ebe33392ca fix: improve import, evidence indexing and material-scoped grading

Preserve document revisions and evidence, harden indexing and export behavior, add explicit material selection and direct-folder import, validate model JSON schemas with safe error messages, and retain student selection while loading scoring data.

2026-10-14 13:52:56 +08:00

46 KiB

Raw Permalink Blame History

WiseGrade（智评）项目指南

当前源码的索引版本为 5、证据政策为 2，最新迁移为 0009。解析与评分改进见第一轮优化说明，历史文档修订与失败恢复见第二轮优化说明，实际 PDF 流程发现的目录权限问题及最新升级边界见 PDF 实流程说明。旧部署记录不表示本轮改动已在正式环境应用。

本指南统一维护部署、教师使用、技术设计和开发说明；项目简介和快速启动见 README。整理日期：2026-09-30；会话实现说明沿用 2026-09-27 的记录。

部署与会话章节描述已有实现；“业务规则与技术设计”保留原始设计基线，其中标为初稿、建议或验收目标的内容不代表已全部实现。当前实现与验证边界见交接记录，具体接口以代码和运行中的 /docs 为准。开发任务提示词集中在 prompts，不作为功能完成证明。

部署与配置

WiseGrade 是单机单管理员教师端。Web 服务仅绑定 127.0.0.1，默认端口为 18080，可通过 .env 中的 WISEGRADE_WEB_PORT 修改。学生原件通过只读目录挂载进入容器，不经过浏览器上传。以下命令除明确切换目录外，均从仓库根目录执行。

准备

Docker Engine + Compose v2（Linux），或 Windows Docker Desktop（WSL2 后端，运行 Linux 容器）。
一个存放学生材料的宿主机目录；其下每个批次目录包含 学号_姓名_选题题目 子目录。
deepseek-flash 可访问的 OpenAI 兼容 API 地址和密钥；该端点必须支持文本、图片输入及原生 tool_calls。若只做评分而不使用对话，仍可沿用已有 JSON 调用。
离线嵌入模型包。默认使用 BAAI/bge-m3。内存不足时可改用 BAAI/bge-small-zh-v1.5。

仓库的 docs/ 同时存放项目文档与课程示例资料；其中 PDF、DOC、DOCX 是课程资料，不是待导入的学生原件。旧版 .doc 只用于课程模板，经 LibreOffice 转换；学生输入只接受 PDF、DOCX、PPTX。 LibreOffice 已安装在后端 Docker 镜像中。按本指南使用容器时，教师不需要在 Windows 或 Linux 宿主机单独安装 LibreOffice；仅在脱离容器运行后端时才需自行安装。

Linux 启动

cp .env.example .env
mkdir -p data/inbox data/processed data/exports models/bge-m3

编辑 .env：

WISEGRADE_DATA_DIR=/absolute/path/to/WiseGradeData
DEEPSEEK_API_KEY=your-key
WISEGRADE_SECRET_KEY=用随机值替换且至少32位
EMBEDDING_MODEL_PATH=/models/bge-m3

也可以启动后在“模型设置”页面填写 API Key。密钥由后端加密保存，浏览器不会直接调用模型服务。WISEGRADE_SECRET_KEY 一旦用于加密设置，不要随意更换，否则已保存的密钥将无法解密。

docker compose up
docker compose ps
curl http://127.0.0.1:18080/api/health

打开 http://127.0.0.1:18080。api 启动时执行 Alembic 迁移并创建初始课程、目标、指标点和规则。评分任务由 worker 容器处理。

如 18080 端口已被占用，在 .env 中将 WISEGRADE_WEB_PORT 改为其他空闲端口，重新运行 docker compose up -d，并使用对应端口访问。

Windows Docker Desktop 启动

安装并启动 Docker Desktop，启用 WSL2 后端，保持 Linux 容器模式。
在 PowerShell 中进入项目目录：Copy-Item .env.example .env。
编辑 .env 中的 WISEGRADE_DATA_DIR，使用正斜杠绝对路径，例如 D:/WiseGradeData。不要在 .env 中添加引号。
将离线模型目录放在 models/bge-m3，填写 API 配置和随机 WISEGRADE_SECRET_KEY。
运行 docker compose up，访问 http://127.0.0.1:18080。

如果挂载失败，先确认 WISEGRADE_DATA_DIR 存在、Docker Desktop 已取得对应磁盘访问权，再运行 docker compose config 查看展开后的挂载路径。首次启动后若修改了 .env 中的 API Key 等配置，运行 docker compose up -d --force-recreate api worker web，使容器读取新值。当前仓库尚未在 Windows 实机验证上述路径和文件挂载。

离线模型包

应用镜像不在启动时下载 BGE-M3。将独立模型包解压到 models/bge-m3/，目录应包含模型权重、config.json、分词器文件及 SentenceTransformers 配置。容器中该目录只读映射为 /models/bge-m3。替代模型需同时修改：

EMBEDDING_MODEL_NAME=BAAI/bge-small-zh-v1.5
EMBEDDING_MODEL_PATH=/models/bge-small-zh-v1.5
EMBEDDING_MODEL_VERSION=your-package-version

EMBEDDING_MODEL_VERSION 会写入每个评分批次快照。若模型目录缺失或内容不完整，导入仍可完成，知识库入库和评分会显示错误。可离线分发 docker save 生成的镜像包及单独的 models-bge-m3.tar.zst；目标机执行 docker load -i docker-images.tar 后解压模型包，运行相同的 Compose 配置。也可以把模型复制进后端镜像，但当前 Dockerfile 和 Compose 采用只读目录挂载；若改成镜像内置模型，须同时调整构建上下文，并移除会遮盖镜像内 /models 的挂载。本机 BGE-M3 必需文件约 2.29 GB，后端镜像当前约 1.08 GB；直接内置后镜像未压缩体积预计约 3.37 GB。API 与 worker 可以共用镜像层，不必各存一份模型。独立模型包便于单独更新和分发。

扫描 PDF 的 OCR 使用 PaddleOCR。离线 OCR 包放在 models/ocr/detection/ 和 models/ocr/recognition/，或修改 OCR_MODEL_DIR 指向包含这两个子目录的位置。没有 OCR 模型且 PDF 无可提取文字时，文件进入解析失败状态并显示原因；系统不会在解析时自动下载 OCR 模型。

下面这组 PP-OCRv5 mobile 中文识别模型已在 PaddleOCR 3.7.0 中验证。下载后将压缩包的顶层目录去掉，使 detection/ 和 recognition/ 内直接包含 inference.yml、inference.json 和 inference.pdiparams：

mkdir -p models/ocr/detection models/ocr/recognition
curl -fL -o models/ocr/PP-OCRv5_mobile_det_infer.tar https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv5_mobile_det_infer.tar
curl -fL -o models/ocr/PP-OCRv5_mobile_rec_infer.tar https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv5_mobile_rec_infer.tar
tar -xf models/ocr/PP-OCRv5_mobile_det_infer.tar --strip-components=1 -C models/ocr/detection
tar -xf models/ocr/PP-OCRv5_mobile_rec_infer.tar --strip-components=1 -C models/ocr/recognition

模型名称从各自的 inference.yml 读取，不能让 PaddleOCR 使用与离线权重不匹配的默认模型。模型目录经 Compose 只读挂载，放入权重后无需修改 .env。

教师使用

课程、导入、评分与导出

在“课程与规则”中查看初始课程版本和评分规则。已发布版本不能直接覆盖；复制草稿、编辑、保存并发布新版本。课程目标、指标点、选题方向、模板和三个 Prompt 都属于课程版本。
在“知识库资料”中选课程版本并入库课程资料。入库使用本地嵌入模型和 PostgreSQL pgvector。
在“目录扫描与导入”中浏览 /data/inbox 下的相对目录，选择学生总目录并扫描。修正学号、姓名、选题和材料类型；PPT 导出的 PDF 必须确认成“汇报PPT/PDF”。每类材料只选择一个文件。确认导入后，材料自动进入后台解析、必要 OCR 和索引任务；评分前即可检索已完成索引的报告。失败任务可从索引任务列表重试。
在“评分批次”中选择已发布课程和规则版本，创建并启动批次。每次评分建立独立批次；重试不会覆盖其他批次。
在“评分与复核”中查看逐项模型原始分、原文证据、页码、页面图像和异常。教师可逐项填写分数、评语和修改说明；修改历史单独保留。
在“导出任务”中按批次导出 Excel，按学生导出 PDF 反馈。缺失或无法评分的项目显示待处理，不自动补零。

成绩权重和评分依据见下文“业务规则与技术设计”。

会话、范围与操作确认

打开系统默认进入空白“会话”草稿，点击“新建”立即切换到另一空白草稿，不弹窗、不写数据库。可在输入区直接提问，并在首次发送前反复选择或清除课程版本、评分批次和学生项目。发送首条非空消息时，会话和消息在同一事务保存；此后范围固定且在界面显示为只读。旧版留下的空会话仍可编辑范围。选择批次或项目会自动带入所属课程版本，清除课程版本会同时清除下级选择。范围固定后，工具不能读取范围之外的对象。会话列表、消息、引用、待确认操作和运行状态保存在数据库，刷新后可查看历史会话；刷新或再次进入页面仍打开新草稿。

可先问“列出课程版本”“扫描 batch 目录”“查看批次 3 的失败评分项”“查询项目 12 的报告实验数据”。课程目标与规则来自数据库；指定批次时使用批次创建时的快照。课程资料和报告通过 BGE-M3/pgvector 检索，回答附资料名、页码或幻灯片编号、原文片段和来源链接。评分证据与 Agent 检索引用都使用 KnowledgeDocument 的文档 ID、页码，对应同一 KnowledgePage：/api/knowledge/documents/{id}/pages/{page} 返回该页完整提取文字，/image 返回存在的页面 PNG。评分引用另有“查看评分”链接。历史引用由迁移 0005 一次性改写为这些统一地址；会话读取不再猜测旧图像链接。实体 PDF、DOCX、PPTX 页面经解析后通常同时有文字和图像；数据库直接生成的课程目标、评分规则等虚拟资料没有实体页面图像，只提供文字。没有证据时应明确说明。正式回答上方的“工具调用”先整体折叠，展开后每次调用仍独立折叠，可逐项查看参数和结果；回答末尾的“引用”也默认整体折叠。会话页不显示全局后台进度卡片，正在运行的会话仍在列表中标记。

扫描只读，可直接执行。导入、课程资料入库、创建批次、启动或重试、教师复核、导出和索引重试会生成确认卡片。卡片列出目标、范围、现值、新值及异常；教师点击“确认执行”才写入。模型工具白名单没有确认工具，聊天文字也不能代替按钮。导入候选有重复、识别异常或待确认文件时，卡片禁用确认；教师在卡片中修正身份、类别和文件选择，再“更新预览”。导入确认同时授权后台解析、必要 OCR 和项目索引。

教师复核必须在当前消息明确写出分数，例如“给 8 分”。Agent 可草拟评语，确认卡片展示批次、学生、评分项、模型原分、教师原分、证据、异常、新分和修改原因。失败或无法评分的项也可人工复核；原始模型分、证据和教师修改历史保留。

业务规则与技术设计

以下保留初始业务约束、数据示例和设计要求。会话、持久任务及统一证据页的增量实现见会话与业务 Agent 实现；原始页面清单和 API 初稿仅供理解设计。

项目概述

项目目标

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

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

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

非目标

第一版不实现：

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

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

已确定的业务规则

教师使用流程

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

教师流程：

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

学生目录结构

宿主机数据目录示例：

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

学生目录命名格式：

学号_姓名_选题题目

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

支持文件

支持：

PDF
DOCX
PPTX
PPT 导出的 PDF

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

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

成绩结构

总评成绩：

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

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

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

评分批次

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

批次必须保存：

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

课程和评分依据

初始资料位于 docs/：

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

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

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

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

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

总体架构

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

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

宿主机目录挂载方案

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

挂载路径与平台配置统一见部署与配置。

路径安全

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

文件变更检测

导入时保存：

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

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

文档解析和结构化

统一文档对象

每个文档解析为：

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

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

文件识别

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

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

识别结果包括：

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

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

PPT/PDF 视觉处理

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

RAG 方案

知识库分层

公共课程知识库

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

学生项目知识库

每个学生独立命名空间：

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

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

文本切分

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

检索

采用混合检索：

pgvector 向量检索
+ 中文二元组关键词检索
+ 课程版本过滤
+ 学生项目过滤
+ 报告类型过滤
+ 阶段过滤
+ 页面类型过滤

过滤在取候选之前完成，两个召回各自独立进行，再按排名融合。默认每个评分项送模型 8～12 个候选证据块，跨目标合计上限 14 块。

嵌入模型

默认使用本地 BAAI/bge-m3；离线包、替代模型和版本配置见部署与配置。

DeepSeek 接入

统一模型

只使用一个模型配置：

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

同一个模型负责：

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

密钥管理

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

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

安全要求：

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

发送数据范围

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

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

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

评分引擎

评分采用多阶段流程：

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

事实抽取

抽取：

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

评分输出

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

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

模型不得对没有证据的内容自行假设。结构化输出必须经过 Pydantic 校验；失败时自动重试或进入人工处理。score 允许为 null：当规则要求正文证据而检索只能给出目录、摘要或章节标题时，模型必须返回 null，不得据此判断学生内容缺失。

每条引文必须通过三类校验：原文与页码一致、来源页面类型在该目标允许范围内、内容性判断不得只由目录、摘要或单独章节标题支撑。页面权限和状态转换由代码执行；模型的说明或推理不能改变它。

页面类型与证据政策

每份资料的每一页都带一个页面类型，随页面持久化并可供检索、评分、复核和会话查询：

页面类型	含义	能否作为内容证据
`cover`	封面、标题页	否（结构目标可用）
`abstract`	摘要、Abstract	否（结构目标可用）
`toc`	目录及其续页	否（结构目标可用）
`body`	正文	是
`appendix`	附录	是
`references`	参考文献、致谢	否（结构目标可用）
`unknown`	识别有疑义	否

判定结合页首标题、章节条目密度、点线与末尾页码、摘要／参考文献措辞、封面字段和页脚样式，并由文档级连续性识别跨页续目录、连续摘要和连续参考文献。它不依赖"目录"一词或固定页号；重复页眉页脚在建立索引前清理。识别依据（各项信号、置信度和分类器版本）与页面一起保存，便于教师核查。

目录与正文共处一页时标为混合页，只对该页按文本块区分：正文块仍作为正文检索，不被整页排除。

required_evidence 的目标带 use 属性，并随批次快照保存：

use: structure：封面、目录、参考文献等页面可以满足，例如"章节""参考文献"。
use: content：只允许正文和附录中的实质段落、数据或表格。

评分规则沿用历史上的字符串数组形式；读取时按下述语法转换，批次快照记录转换结果和 POLICY_VERSION，因此旧批次始终可按当时的规则重读。

检索

每个必备证据目标分别检索：先限定课程版本、学生项目、材料类别和允许的页面类型，再取候选。页面过滤发生在候选数量限制之前，目录页不会因为得分高而挤掉正文页。

语义匹配和中文关键词匹配各自召回候选池，再按排名倒数（RRF）融合；不对未归一化的语义分和关键词分直接相加。

关键词召回不使用 PostgreSQL 的 to_tsvector('simple', …)：该配置没有中文分词，整个中文串会成为一个词元。在课程报告上实测，查询"文献调研"无法命中含"第2章文献调研与技术现状"的页面，因此现有实现里关键词分长期接近零。现在改用字符二元组加 ASCII／数字整词的重叠度，无需扩展且在各数据库上行为一致。

名额分配优先分散到不同页面；有了可靠章节路径后对同一章节设软上限；名额不足时回填同页或同节的其他正文片段，但不会放宽证据类型。

内容目标在正文中没有命中时，利用目录标题匹配实际正文标题，补检该章节及其相邻正文页。目录只作导航，最终内容引文必须落在实际正文页。

评分发送给模型的页面图像优先选择相关的不同正文页，而不是目录页；评分最终送模型的片段数量保持受控，Agent 搜索同样受控。

待教师复核

"待教师复核"是与材料缺失、解析失败、模型调用失败并列的独立状态：

材料缺失、重复、待确认或解析失败 → unscorable
模型调用或校验失败 → failed
内容目标补检后仍只有目录或摘要命中 → needs_review

进入待复核时模型分为 null，总分保持待处理，系统不会自动给低分或断言学生未写。评分项记录缺失的正文证据目标和当时的检索范围，该记录在教师复核后仍然保留。批次状态为"已完成，有待复核项"（review_required），仪表盘的待处理数包含待复核项。

教师可对任何状态的评分项复核，包括待复核项；教师评分输入框不预填 0。

跨文档一致性

至少检查：

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

规则配置和版本管理

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

评分指标结构

criterion_id: stage1.solution_feasibility
name: 方案合理性与可行性
max_score: 15
description: 评价方案是否具有工程依据、可实施性和风险分析
linked_outcomes: [2.3, 2.4, 4.1]
required_evidence:
  - label: 主方案
    use: content          # 只能用正文或附录的实质段落证明
  - label: 替代方案
    use: content
  - label: 章节
    use: structure        # 目录即可证明章节存在
score_levels:
  - min: 12
    max: 15
    description: 论证充分，方案比较清晰，风险分析具体
  - min: 6
    max: 11
    description: 基本完成论证，但证据或分析不充分
  - min: 0
    max: 5
    description: 缺少核心论证

required_evidence 也接受历史上的字符串数组（required_evidence: [主方案, 替代方案]）。读取时按措辞判定 use：提到标题、封面、目录、章节、参考文献、格式、附录等报告包装字样的目标为 structure，其余为 content。判定结果与 POLICY_VERSION 一起写入批次快照，不修改已发布的规则文本。

版本要求

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

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

核心数据表

建议至少包含：

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

评分批次

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

评分项结果

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

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

前端页面

第一版页面建议：

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

后端 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}

缺失和异常处理

材料状态：

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

处理原则：

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

会话与业务 Agent 实现

会话交互及确认规则见教师使用。以下记录数据、模型边界、接口与运行恢复机制。

数据与任务

迁移 0003 添加会话、消息、运行、待确认操作、索引任务和批次固定项目清单；0004 添加首次请求幂等键与有界工具进度记录；0005 回填完整资料页文字与相对图像路径，并将历史会话中的引用一次性转换为统一页面链接；0006 为页面和检索片段添加页面类型、混合页标记、章节路径，为评分证据添加所属证据目标与历史标记，并新增评分项的缺证据记录。检索片段的文字和 1024 维向量保存在 PostgreSQL 的 knowledge_chunks；供教师核对的完整页文字单独保存在 knowledge_pages，避免以有重叠的检索片段拼接页面。PNG 文件位于共享 data/processed/，数据库只存相对于处理目录的路径；学生原件仍只读挂载在 /data/inbox。新批次在创建时保存项目 ID 列表；评分、结果查询和导出都使用该列表。旧批次该字段为 NULL，界面显示“历史项目清单未知”，只能按课程版本当前项目兼容读取，不能声称还原了创建时的范围。批次状态为 created、queued、running、partial、failed、completed、review_required；review_required 表示评分已结束但仍有待教师复核项，与部分完成不同。重复启动已入队或运行中的批次返回冲突。重试保留已评分项和教师复核。

索引版本 0006 起为 3。分块方式已改变（目录页不再作为正文文本），因此旧版本的索引不会被就地当作已分类正文使用：文档保留原有 index_version，在重建完成前不参与检索，教师可先在上线前查看 /api/knowledge/stale/{course_version_id} 的待重建清单。重建任务类型为 reindex，只从已保存的解析结果重建，不重新读取或修改学生原件；重复执行会跳过已是最新版本和源文件已变化的文档，并记录到审计日志。

导入后的每个待解析文件对应持久 IndexTask。worker 复用评分的解析和 RAG 入库代码；同一文件用共享处理目录中的文件锁串行化，避免自动索引与评分竞争写入。任务有 queued/running/completed/failed 状态、错误和重试入口。课程资料入库在会话中也作为索引任务执行。若 Redis 不可用，导入数据仍保存，索引任务标记失败并可重试。原始学生文件只从只读 /data/inbox 读取，文件 SHA-256 在预览和确认时复查。

待确认操作保存不可变参数、20 分钟有效期、幂等键和预期数据状态。确认时再次比对课程发布状态、规则与项目范围、批次状态、成绩与文件哈希。状态变化返回“重新预览”；重复确认已完成操作返回原结果。执行与会话 ID 写入审计日志。服务异常的操作标记失败，需重新准备；若进程在执行中崩溃，卡片保留 executing 状态，管理员应先核查实际业务记录再处理，不应直接重复写入。

批次汇总从数据库和现有权重规则计算完成数、未完成数、状态数量、分布、模型原始分均值和教师最终分均值。只有完整项目参与成绩均值及分布；失败、无法评分和待处理项不补零。详情仍可按学生、批次和评分项状态筛选。

模型与安全边界

会话使用模型设置页的 OpenAI 兼容 /chat/completions 地址、模型和后端 API Key。适配层按 DeepSeek 原生工具调用文档发送 tools，在每轮前用不含学生资料的 wisegrade_ping 最小探针验证端点会返回 tool_calls。当前 deepseek-flash 端点支持自动工具选择，但拒绝强制 tool_choice="required"，因此探针采用 auto 并检查返回结构。模型不支持时会显示明确配置错误，不会伪装工具已执行。既有评分 json_call 保持原有 JSON 行为。

内容检索和结构查询使用与评分相同的证据政策。search_project_material 只返回正文和附录片段，search_project_structure 返回目录条目与章节结构并明确说明这些信息不能证明章节内容，get_document_pages 列出各页的页码、页面类型和章节，search_document 在单份资料内检索正文。工具返回页面类型和稳定的引用标识（citation_id），每项标注 source_role 为 content 或 structure。评分工具返回的旧引文标记为历史评分引用（source 为 historical_score_evidence），不会被当作报告正文证据。

工具输入由 Pydantic 校验，后端再校验课程、批次和项目关系。每条教师消息默认最多调用工具 32 次，成功、失败与跳过的尝试均计数；模型最多请求 33 轮，以便用完工具次数后还能生成回答。同一轮中工具名和经校验的参数（含默认分页值）完全相同时，后续调用会标为“已跳过”，模型收到前次调用标识并使用此前结果，不再执行工具；不同查询词、筛选或分页偏移仍会正常执行。可在 .env 中通过 CHAT_MAX_TOOL_CALLS 调整工具上限（1–64），修改后重新创建 API 容器。get_scores 每次最多返回一个项目的六项评分，响应给出 next_criterion_offset 和 next_project_offset 供继续查询；长结果保留结构化评分数据，不再变成无内容的截断提示。检索工具的运行记录保留每次调用找到的有界原文片段；回答引用对各次调用的证据去重后保存，不再只取前 20 条。工具没有任意 SQL、任意文件路径、HTTP 请求、代码执行或确认能力。检索片段只作为数据，不作为工具指令。模型只收到当前问题所需的规则摘要、检索片段或紧凑统计；API Key 不写入日志或会话表。

API 与故障恢复

草稿仅存在于浏览器；POST /api/conversations/first-message 以 UUID 请求键原子创建会话、首条教师消息及运行，重复请求返回同一 ID。POST /api/conversations 保留给旧客户端。GET /api/conversations 返回列表和各会话运行标识；GET /api/conversations/{id} 恢复消息、卡片、工具记录和运行状态；PUT /api/conversations/{id}/scope 仅允许首条教师消息前编辑范围；DELETE /api/conversations/{id} 删除非运行中的会话。删除会话会清理消息、运行与待确认卡片，不回滚已经确认的业务操作，相关业务审计仍保留。POST /api/conversations/{id}/messages/start 在提交消息后启动独立后台运行；GET /api/conversations/{id}/runs/{run_id}/events 可按运行 ID 订阅持久 SSE 事件。旧版 POST /api/conversations/{id}/messages 继续提供 SSE 的 run、tool、message、error、done 事件。确认、取消和导入编辑分别为 POST /api/conversations/{id}/actions/{action_id}/confirm|cancel|edit-import。索引任务可通过 GET /api/index-tasks、GET /api/index-tasks/{id} 查询，失败任务可重试。Nginx 对消息流关闭代理缓冲并设置 900 秒读取超时。

回答生成由后台线程执行，页面切换或 SSE 断开不会停止运行；前端按运行 ID 订阅 SSE，并轮询列表和当前会话详情恢复进度，可同时运行多个不同会话。同一会话仍拒绝并发发送。刷新后默认打开新草稿，点击历史会话即可查看正在运行的工具状态或最终结果。运行中的会话删除返回冲突，应待完成后重试。服务进程异常留下的 running 记录超过 15 分钟，在读取会话时标为中断。模型失败时，已提交的教师消息仍保留，可在同一会话继续提问。工具记录保存有界查询词、筛选、分页及必要标识；教师复核评语和原因只显示省略标记，未知字段与密钥不保存。旧记录中未保存的检索查询词无法还原，界面明确标明；旧评分记录可从工具结果恢复实际分页偏移。检索工具记录有界原文片段，评分工具记录有界评分行，其他工具记录结构摘要。回答按安全 Markdown 渲染，HTML 不执行，链接仅允许 HTTP(S)；工具过程在回答上方，引用在回答最后，二者默认折叠。待确认卡片始终独立显示。若嵌入模型或 OCR 缺失，任务保留具体失败原因；补齐离线模型后重试。若课程资料缺失、原件哈希变化、课程或批次状态变化，应重新预览。

开发与测试

本地开发和测试命令

Python 依赖由 backend/pyproject.toml 管理：

cd backend
uv sync --extra ocr --group dev
uv run alembic upgrade head
uv run uvicorn wisegrade.main:app --reload

测试从仓库根目录运行：

docker compose --profile test run --build --rm test

先验证无需真实 API Key 的测试可运行：docker compose --profile test run --build --rm test pytest -q -m 'not integration'。宿主机运行同一测试时，须把 TEST_DATABASE_URL 指向独立 PostgreSQL 测试库，并将 EMBEDDING_MODEL_PATH 指向本机离线模型目录。完整集成测试会访问真实模型，应单独执行和记录。

测试使用独立的 PostgreSQL 16 + pgvector 容器和 test-redis，不连接业务数据库或业务任务队列。每个数据库测试创建临时数据库，执行 Alembic 迁移后运行，结束时删除；test-db 的数据目录为 tmpfs，不会写入业务数据卷。测试会从 .env 读取真实 DeepSeek API Key，并加载 models/bge-m3 和 models/ocr 中的离线模型；完整流程测试会发起真实模型请求。在宿主机直接运行 uv run pytest 时，需先设置指向专用 wisegrade_tests 数据库的 TEST_DATABASE_URL（使用 postgresql+psycopg 驱动，账号需有创建数据库的权限），并提供可用的模型配置。

本地开发需提供 PostgreSQL、Redis 和与容器路径一致的挂载目录；可用 Compose 启动 db 和 redis。Vite 前端：

cd frontend
npm install
npm run dev

开发服务器将 /api 代理到 localhost:8000。集成测试从仓库 docs/ 复制阶段报告 1、2、3 与最终报告，并生成一份汇报 PDF 测试材料。

测试要求

单元测试

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

集成测试

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

验收测试

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

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

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

Git 开发约定

必须创建合理的 .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。

原始开发阶段（历史规划）

以下优先级保留为初始实施顺序，不是当前待办清单；接手事项见 HANDOFF。

P0：可运行骨架

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

P1：课程和导入

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

P2：解析和知识库

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

P3：评分

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

P4：复核和导出

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

P5：验收和部署

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

第一版验收目标

以下是验收目标，不代表所有平台和场景已实测。

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

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

故障定位与恢复

docker compose logs api worker 查看迁移、解析和任务异常。日志不输出 API Key。
模型请求失败后按配置有限重试，评分项显示失败原因；可修复配置后重试该批次。
对话若提示端点或模型不支持 tool_calls，在“模型设置”中选择支持工具调用的 OpenAI 兼容端点和模型。探针不发送课程或学生资料；普通模型对话仍有调用次数和超时限制。
导入后索引任务若显示失败，查看 /api/index-tasks/{id} 的错误并修复 Redis、离线 BGE-M3 或 OCR，再重试。批次若已入队或运行，重复点击启动会返回冲突。
原件哈希变化后必须重新扫描并确认导入，否则解析会报“源文件已变化”。
源文件和模型目录为只读挂载；解析产物在 data/processed/，导出在 data/exports/，均被 Git 忽略。

会话运行中断、待确认操作卡在 executing、旧批次范围兼容等情况，见会话与业务 Agent 实现。

46 KiB Raw Permalink Blame History Unescape Escape

WiseGrade（智评）项目指南

目录

部署与配置

准备

Linux 启动

Windows Docker Desktop 启动

离线模型包

教师使用

课程、导入、评分与导出

会话、范围与操作确认

业务规则与技术设计

项目概述

项目目标

非目标

已确定的业务规则

教师使用流程

学生目录结构

支持文件

成绩结构

评分批次

课程和评分依据

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

阶段报告要求

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

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

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

总体架构

推荐技术栈

宿主机目录挂载方案

路径安全

文件变更检测

文档解析和结构化

统一文档对象

文件识别

PPT/PDF 视觉处理

RAG 方案

知识库分层

公共课程知识库

学生项目知识库

文本切分

检索

嵌入模型

DeepSeek 接入

统一模型

密钥管理

发送数据范围

评分引擎

事实抽取

评分输出

页面类型与证据政策

检索

待教师复核

跨文档一致性

规则配置和版本管理

评分指标结构

版本要求

核心数据表

评分批次

评分项结果

前端页面

后端 API 初稿

课程和规则

文件扫描和项目导入

评分

导出

缺失和异常处理

会话与业务 Agent 实现

数据与任务

模型与安全边界

API 与故障恢复

开发与测试

本地开发和测试命令

测试要求

单元测试

集成测试

验收测试

Git 开发约定

原始开发阶段（历史规划）

P0：可运行骨架

46 KiB

Raw Permalink Blame History