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

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
POST	`/tasks/:id/feedbacks`	用户反馈

5.3 数据集与管理员（须 JWT + 管理员）

方法	路径	说明
GET	`/datasets/finetune`	任务快照 NDJSON；`limit`、`only_segmented`
POST	`/admin/eval/run`	执行评估；body 可选 `scope: all
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 复制代码

bash scripts/run_all_tests.sh

7.2 分模块

bash 复制代码

# 仅后端（约 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 脚本为准。