WiseGrade（智评）部署与使用

WiseGrade 是单机单管理员教师端。Web 服务仅绑定 127.0.0.1:8080。学生原件通过只读目录挂载进入容器，不经过浏览器上传。

准备

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

仓库的 docs/ 是课程资料，不是学生原件。旧版 .doc 只用于课程模板，经 LibreOffice 转换；学生输入只接受 PDF、DOCX、PPTX。

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 --build -d
docker compose ps
curl http://127.0.0.1:8080/api/health

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

Windows Docker Desktop 启动

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

如果挂载失败，先确认 WISEGRADE_DATA_DIR 存在、Docker Desktop 已取得对应磁盘访问权，再运行 docker compose config 查看展开后的挂载路径。

离线模型包

应用镜像不在启动时下载 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 配置。

扫描 PDF 的 OCR 使用 PaddleOCR；需在离线环境准备其运行所需的 OCR 模型缓存。没有 OCR 模型且 PDF 无可提取文字时，文件进入解析失败状态并显示原因。

教师操作

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

成绩为阶段报告 1、2、3 各占 10%，期末占 70%。期末四项为任务完成度 20、报告规范性 20、汇报答辩 40、结果分析 20。系统的“汇报答辩”只评价 PPT 或 PPT PDF 页面内容，不评价口头答辩。

开发与测试（uv）

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

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

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

cd frontend
npm install
npm run dev

开发服务器将 /api 代理到 localhost:8000。测试中的 DeepSeek 请求使用 mock，不会使用真实 API Key。集成测试从仓库 docs/ 复制阶段报告 1、2、3 与最终报告，并生成一份汇报 PDF 测试材料。

故障定位

docker compose logs api worker 查看迁移、解析和任务异常。日志不输出 API Key。
模型请求失败后按配置有限重试，评分项显示失败原因；可修复配置后重试该批次。
原件哈希变化后必须重新扫描并确认导入，否则解析会报“源文件已变化”。
源文件和模型目录为只读挂载；解析产物在 data/processed/，导出在 data/exports/，均被 Git 忽略。

5.7 KiB Raw Blame History Unescape Escape