基于机器学习的古籍文字识别与断句校正系统

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 一键自测（仓库根目录）

bash scripts/run_all_tests.sh

7.2 分模块

# 仅后端（约 23 项，mock OCR/句读，不依赖 Paddle）
cd modu-backend && bash scripts/run_tests.sh

# 仅前端 E2E（8 项，自动起临时后端 + Vite）
cd modu-frontend && CI=1 npm run 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 脚本为准。