基于机器学习的古籍文字识别与断句校正系统
1. 项目定位
本仓库实现一套面向古籍页面图像的端到端可复现流水线：从上传图卷、版面归一与预处理、深度学习文字识别（OCR）、文本整理、勘校与异体处理、句读标注（深度学习模型与规则后处理），到多格式导出与微调 / 标注数据闭环。系统以任务（卷宗）为粒度管理全流程状态；登录用户仅能访问本人任务（管理员可查看全部），便于课题演示、文章实验与多用户隔离。
模型与调优原则（本课题约定）
- 不自研 backbone 网络：识文、句读均依托第三方开源/预训练模型（PaddleOCR、HuggingFace 上的 BERT 类 TokenClassification 等）做推理。
- 线上系统：默认只做加载权重 + 前向推理；不在 Web 内嵌 GPU 训练作业。
- 后期调优：句读支持离线手动微调——由接口导出业务数据或管理员标注 JSONL，在独立 Python 环境中用仓库脚本继续训练，产出新目录后通过
MODU_SEGMENT_MODEL_DIR切换部署。
技术形态：Vue 3 单页应用调用Flask REST API（JWT 鉴权），数据落SQLite与本地uploads//outputs/；PaddleOCR、句读 Transformers 等按依赖与权重可选启用，缺失时走明确降级（例如无 Paddle 时可手改勘校正文继续后续步骤）。
2. 功能总览
2.1 用户与权限
| 能力 | 说明 |
|---|
| 注册 / 登录 | POST /api/v1/auth/register、/login；返回 JWT（Bearer） |
| 当前用户 | GET /api/v1/auth/me；前端启动时刷新is_admin等字段 |
| 任务隔离 | 普通用户仅见、仅改user_id为本人的任务 |
| 内置管理员 | 启动时写入 SQLite：默认admin/admin（可用MODU_ADMIN_*覆盖）；已存在则不重置密码 |
| 账号设置 | PUT /api/v1/auth/me：修改自己的用户名、密码 |
| 管理员 | 可访问全部任务；用户管理（授予/取消is_admin）、模型评估、数据集标注、微调导出 |
2.2 任务与资源管理
| 能力 | 说明 |
|---|
| 新建任务 | multipart上传 JPG/PNG；服务端压缩大图、图像预处理、预览与元数据落库 |
| 任务列表 | 卷宗页浏览；按status显示进度文案 |
| 任务详情 | GET /api/v1/tasks/:id；含preprocessed_text、勘校/句读元数据等 |
| 断点续作 | 卷宗「继续」按状态跳转对应步骤；刷新后通过sessionStorage+ 详情接口恢复 |
| 任务删除 | 删除记录及关联原图、预览文件 |
| 简易统计 | GET /api/v1/tasks/:id/stats：字数、行数、低置信字格等 |
任务状态（status）与续作路径
| status | 含义 | 续作默认进入 |
|---|
done/pending | 已上传，待识文 | 识别文字 |
ocr_done | 已识文，待整理 | 整理文本 |
preprocessed | 已整理，待改正 | 改正文字 |
corrected | 已改正，待加标点 | 加标点 |
segment_done | 可加标点或导出 | 导出 |
2.3 图像与版面（传统视觉）
| 能力 | 说明 |
|---|
| 上传压缩 | 过长边缩放、PNG 大图可转 JPEG，减小体积（upload_compress元数据写入预处理记录） |
| 图像增强 | 灰度、去噪、二值化、倾斜校正等 |
| 版式主向估计 | 粗判横排 / 竖排；竖排时旋转到统一处理空间 |
| 行级 / 字级分割 | 行带与单字条带（投影法；粘连字块为粗分割，文章中需说明局限） |
| 预处理元数据 | 行带、字框、预览文件等；导出 JSON 时一并携带 |
2.4 文字识别（机器学习）
| 能力 | 说明 |
|---|
| 深度学习 OCR | PaddleOCR（依赖paddlepaddle 2.6.2+ paddleocr 2.7.3）；未安装时paddle_ready: false，可手改勘校 |
| 置信度与存疑 | 字格级置信度；前端低置信高亮 |
| 行级坐标 | line_results含每行box与字符信息 |
| 识文后整理 | 识文成功且 Paddle 就绪时，可自动触发一次文本预处理 |
2.5 文本整理（预处理）
| 能力 | 说明 |
|---|
| 自动整理 | POST .../preprocess-text：Unicode 规范化、空白/换行规整等（TextPreprocessService） |
| 人工修订 | PUT .../preprocess-text保存preprocessed_text |
| 勘校输入优先级 | 自动勘校优先使用preprocessed_text，其次raw_text |
2.6 文本勘校（纠错子系统）
| 能力 | 说明 |
|---|
| 自动勘校 | 异体/混淆映射；可选 OpenCC 繁转简 |
| 人工勘校 | PUT .../corrections；无识文结果也可手输全文（适配 Paddle 未装场景） |
| 勘校事件 | 写入corrections；POST .../feedbacks合并用户反馈 |
2.7 句读（机器学习 + 规则）
| 能力 | 说明 |
|---|
| 深度句读模型 | 本地 HuggingFace 格式权重（默认models_weights/sikubert-segment）；否则降级并提示 |
| 规则后处理 | 标点校验与修正；环境变量控制后处理、七言节奏、标点风格等 |
| 自动 / 人工句读 | POST/PUT .../segmentation；手改非空时status置为segment_done |
| 句读元数据 | segment_meta：校验警告、模型是否加载等 |
2.8 导出与数据闭环
| 能力 | 说明 |
|---|
| 多格式导出 | TXT（句读稿优先）、DOCX、JSON（含preprocessed_text、坐标与元数据）；须带 JWT，前端 blob 下载 |
| 用户反馈 | POST .../feedbacks |
| 微调数据导出 | 管理员GET /api/v1/datasets/finetune（NDJSON）；参数limit、only_segmented |
| 标注数据导出 | 管理员GET /api/v1/admin/annotations/export（JSONL） |
2.9 管理员能力
| 能力 | 说明 |
|---|
| 模型效果评估 | POST /api/v1/admin/eval/run、GET .../eval/latest；结合data/eval_gold.jsonl与任务快照计算指标 |
| 断句数据集标注 | 样本 CRUD、POST .../annotations/from-task/:id从任务导入、筛选与导出 JSONL |
| 导航入口 | 顶栏「模型评估」「数据集标注」（仅is_admin） |
2.10 前端交互（六步流水线）
| 步骤 | 路由 | 说明 |
|---|
| ① 上传图片 | /upload | 拖拽/选择 JPG、PNG |
| ② 识别文字 | /recognize | Paddle OCR；低置信可视化 |
| ③ 整理文本 | /preprocess | 需已有识文结果（或测试种子数据） |
| ④ 改正文字 | /correct | 自动/人工勘校 |
| ⑤ 加标点 | /segment | 自动句读 + 人工修订 |
| ⑥ 导出 | /export | TXT / Word / JSON；管理员另可见「全部任务汇总」 |
另：卷宗/tasks、登录/注册、侧栏步骤导航（StepSidebar）。界面文案为简体中文；古籍正文可为繁体。
2.11 刻意不纳入当前版本（可作文章展望）
- Web 内一键 GPU 训练 / 自动调度微调（句读见
scripts/finetune_token_classification.py） - OCR 领域重训练（使用飞桨官方工具链，再改
app/ml/ocr_model.py加载逻辑） - 外置标注平台（如 Label Studio）；本系统采用内置 Vue 标注页
- 分语体多模型路由、与 Paddle 并行的 TrOCR 管线等
3. 技术栈与架构要点
| 层级 | 技术 | 职责 |
|---|
| 前端 | Vue 3、Vite、Pinia、Vue Router、Element Plus、Axios | 六步流水线、JWT 拦截器、卷宗与管理员页 |
| 后端 | Flask 3、SQLAlchemy、Flask-CORS、PyJWT | /api/v1、任务与用户 ORM、推理编排 |
| 图像 | OpenCV、Pillow | 预处理、上传压缩 |
| OCR | PaddleOCR（可选） | 行级文本与 box |
| 句读 | PyTorch、Transformers（可选） | TokenClassification |
| 勘校 | OpenCC、映射表 | 繁简与异体/混淆 |
| 评估 | scikit-learn 等 | EvalService指标 |
| 存储 | SQLite、本地目录 | users、tasks、annotation_samples、eval_report等 |
数据库升级：SQLite 无自动迁移脚本；app/__init__.py对旧库补列（如user_id、preprocessed_text）。结构大改时可删除modu.db后由create_all()重建。旧任务若user_id为空，仅管理员可访问。
4. 目录结构
python-gushici-corrective/ ├── 项目说明.md # 本文档 ├── 项目设计方案.md ├── scripts/ │ └── run_all_tests.sh # 一键：后端 pytest + 前端 E2E ├── mac/、windows/ # 部署手册、setup_and_run、模型下载步骤 ├── modu-backend/ │ ├── app.py # 启动入口（须在本目录执行） │ ├── requirements.txt │ ├── requirements-dev.txt # pytest 等 │ ├── tests/ # pytest；说明见 tests/README.md │ ├── scripts/ │ │ ├── run_tests.sh │ │ ├── e2e_server.sh # Playwright 临时后端 │ │ ├── README_FINETUNE.md │ │ ├── build_segment_train_jsonl.py │ │ └── finetune_token_classification.py │ ├── app/ │ │ ├── auth/ # JWT 签发与装饰器 │ │ ├── api/v1/ │ │ │ ├── auth.py │ │ │ ├── tasks.py │ │ │ ├── datasets.py │ │ │ ├── admin_eval.py │ │ │ └── admin_annotations.py │ │ ├── services/ # 导出、勘校、预处理、评估、压缩等 │ │ └── ml/ # OCR、句读模型封装 │ ├── data/eval_gold.jsonl │ ├── models_weights/ # 句读权重（不进 Git，见下载步骤 md） │ ├── uploads/、outputs/ │ └── modu.db └── modu-frontend/ ├── e2e/ # Playwright 用例 ├── src/views/ # 各流水线页 + 登录 + 管理员页 └── package.json # test:e2e
5. HTTP API 契约（摘要）
统一前缀/api/v1；除注册/登录外，业务接口需请求头Authorization: Bearer <token>。
5.1 认证
| 方法 | 路径 | 说明 |
|---|
| POST | /auth/register | 注册（普通用户；不可占用admin用户名） |
| POST | /auth/login | 登录 |
| GET | /auth/me | 当前用户（需 JWT） |
| PUT | /auth/me | 修改自己的用户名 / 密码 |
5.2 任务（须 JWT；任务按用户隔离）
| 方法 | 路径 | 说明 |
|---|
| GET/POST | /tasks | 列表 / 创建（multipart 上传） |
| GET/DELETE | /tasks/:id | 详情 / 删除 |
| GET | /tasks/:id/stats | 统计 |
| POST | /tasks/:id/ocr | 识文 |
| POST/PUT | /tasks/:id/preprocess-text | 自动/人工文本整理 |
| POST | /tasks/:id/corrections/auto | 自动勘校 |
| PUT | /tasks/:id/corrections | 人工勘校 |
| POST/PUT | /tasks/:id/segmentation | 自动/人工句读 |
| GET | /tasks/:id/export?format=txt|docx|json | 导出附件 |
| POST | /tasks/:id/feedbacks | 用户反馈 |
5.3 数据集与管理员（须 JWT + 管理员）
| 方法 | 路径 | 说明 |
|---|
| GET | /datasets/finetune | 任务快照 NDJSON；limit、only_segmented |
| POST | /admin/eval/run | 执行评估；body 可选scope: all|mine |
| GET | /admin/eval/latest | 最近一次评估报告 |
| GET/POST | /admin/annotations | 列表 / 新建样本 |
| POST | /admin/annotations/from-task/:task_id | 从任务导入 |
| GET/PUT/DELETE | /admin/annotations/:id | 单条 CRUD |
| GET | /admin/annotations/export | 标注 JSONL |
| GET | /admin/users | 用户列表 |
| PUT | /admin/users/:id | 设置is_admin（内置 admin 不可降权） |
5.4 静态资源
GET /uploads/<path>：预处理预览图等。
字段与请求体细节以《项目设计方案》及app/api/v1/*.py源码为准。
6. 配置与环境变量（后端）
| 变量 | 作用 |
|---|
MODU_PORT | HTTP 端口（默认与前端代理一致，如 8800） |
MODU_SECRET_KEY | Flask 密钥（生产务必覆盖） |
MODU_JWT_SECRET | JWT 签名密钥（默认同SECRET_KEY） |
MODU_JWT_EXPIRE_HOURS | Token 有效期（默认 168 小时） |
MODU_ADMIN_USERNAME | 内置管理员用户名（默认admin） |
MODU_ADMIN_PASSWORD | 内置管理员初始密码（仅首次创建账号时写入） |
MODU_DATABASE_URL | SQLAlchemy 连接串 |
MODU_SEGMENT_MODEL_DIR | 句读模型目录 |
MODU_FINETUNE_EXPORT_MAX | 微调导出单次上限（默认 5000） |
MODU_UPLOAD_MAX_EDGE | 上传压缩最长边像素 |
MODU_UPLOAD_JPEG_QUALITY | JPEG 质量 |
MODU_SEGMENT_POSTPROCESS | 句读后处理开关 |
MODU_POETRY_7_SPLIT | 七言节奏（如2_5） |
MODU_SEGMENT_PUNCT_MODE | 句读标点风格（如A） |
MODU_EVAL_GOLD_PATH | 评估 gold 文件路径 |
前端：VITE_BACKEND_URL（如.env.development）指向后端基址。
7. 自动化测试
业务功能以pytest（API/服务）与Playwright（浏览器 E2E）覆盖；不替代Paddle 识文准确率与离线微调脚本的现场验证。
7.1 一键自测（仓库根目录）
bashscripts/run_all_tests.sh
7.2 分模块
# 仅后端（约 23 项，mock OCR/句读，不依赖 Paddle）cdmodu-backend&&bashscripts/run_tests.sh# 仅前端 E2E（8 项，自动起临时后端 + Vite）cdmodu-frontend&&CI=1npmrun test:e2e
7.3 覆盖范围说明
| 类别 | 已覆盖（摘要） |
|---|
| 后端 | 注册/登录/鉴权、任务 CRUD/统计/反馈、全流程 API（mock ML）、导出三格式、管理员评估与标注、微调 NDJSON |
| 前端 | 注册登录、六步页与导出、卷宗删除、管理员页与权限拦截 |
| 未自动化 | Paddle 识文效果、20MB 超限/坏图、压测、finetune_*脚本执行 |
详细用例索引见modu-backend/tests/README.md。
TESTING=True时存在内部接口POST /tasks/:id/__test/seed（仅 pytest/E2E 后端），生产TESTING=False不注册。
8. 相关文档与操作指引
| 文档或入口 | 用途 |
|---|
项目设计方案.md | API 表、路由、数据模型 |
modu-backend/tests/README.md | 测试命令与功能对照表 |
modu-backend/scripts/README_FINETUNE.md | 句读微调数据格式与训练命令 |
mac/项目部署手册_macOS.md、windows/项目部署手册_Windows.md | 环境安装与启动 |
mac/必须执行__模型文件下载步骤.md、windows/… | 克隆后下载句读权重与 Paddle 缓存 |
mac/手动微调执行步骤.md、windows/… | 离线微调逐步命令 |
8.1 环境与安装提示（摘要）
- 推荐Python 3.12创建
modu-backend/.venv，安装requirements.txt；Windows 安装时勾选Add Python to PATH。 - 句读权重与 Paddle 按各平台「必须执行__模型文件下载步骤」操作；权重目录默认
modu-backend/models_weights/sikubert-segment。 - 前端：
cd modu-frontend && npm install；开发时npm run dev，代理/api与/uploads至后端。 - 句读微调建议在独立 venv 使用
requirements-train.txt，避免与 Paddle 包冲突。
本文档不展开逐条日常 shell 教程；命令级步骤以各平台部署手册与setup_and_run脚本为准。