# auto-ocr

**Repository Path**: yeuimu/auto-ocr

## Basic Information

- **Project Name**: auto-ocr
- **Description**: AI自动化适配各种面单
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-13
- **Last Updated**: 2026-06-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OCR Pipeline for Shipping Labels

USPS + GOFO 面单 OCR 解析 + **轻量 SER 分类器**（ResNet18 / MobileNetV3）。
完整训练手册见 [`docs/train.md`](docs/train.md)。

## 项目最终目的

> **目标：让 AI 接管整套"新增面单 → 重训 → 部署"流水线，本人只需要不断提供新面单 PDF。**

- **建基阶段**：用 93 张 USPS + 200 张 GOFO 把整条流水线（数据准备 → 训练 → 评估 → 推理）跑通；过程中把每一步的命令、参数、踩坑、失败原因、决策理由全部写进 `docs/train.md`，细到「下次 AI 接过来能直接照着干、不需要再问人」的程度。
- **运维阶段**：用户只做一件事——把新 PDF 丢进 `laebls/`，AI 按文档自动跑 `prepare_data.py` → `tools/build_lines.py` → `tools/build_dataset.py` → `tools/train_classifier.py` → `tools/eval_classifier.py` → `tools/ab_compare.py`，产出新 `models/usps_ser_vN/` ckpt + 对比报告，告知精度 / 是否上线。
- **可观测 / 可回滚**：每次训练产物独立成目录 `models/usps_ser_vN/`，所有 metric / 混淆矩阵 / A/B 对比都进 `docs/` 和 `models/.../eval/`；出问题就 `git revert` ckpt + 文档回到上一个稳定版本。

## 当前能力

| 任务 | 状态 | 说明 |
|------|------|------|
| 字段提取（USPS/GOFO） | ✅ 正则解析 | 输出 18 字段 → `laebls.xlsx` |
| 行级 SER 分类 | ✅ 已训烟测 ckpt | 13 类，3 epoch CPU 烟测 macro-F1 = 0.7361 |
| `--use-ser` 集成 | ✅ parse_labels.py CLI | 可与 regex A/B 对比 |
| autoDL 真训 20 epoch | ⏳ 待跑 | 见 `tools/train_on_autodl.sh` |
| PaddleOCR VI-LayoutXLM | 📋 Phase 2 占位 | `docs/train.md` 第 10 章 |

## 目录结构

```
ocr/
├── parse_labels.py            # 入口（regex 或 SER 两种解析路径）
├── prepare_data.py            # PDF → 整页 + 行级 crops
├── pyproject.toml / uv.lock   # 依赖（uv 管理）
│
├── laebls/                    # 原始 PDF（输入，93 个 USPS）
├── annot/                     # 生成的数据
│   ├── pages/                 #   整页 PNG（300 DPI，93 张）
│   ├── crops/                 #   行级裁切 PNG（2823 张）
│   ├── manifest.json          #   crop 索引 + bbox
│   ├── lines/<pdf_stem>.json  #   每行 OCR 文本 + 字段归属（93 个）
│   ├── train.csv / val.csv    #   训练/验证集（按 PDF 分层）
│   ├── dataset.csv            #   全量
│   └── labels.txt             #   13 个 SER 类别
│
├── models/usps_ser_v1/        # 烟测 ckpt（autoDL 真训后覆盖）
│   ├── best.pt / last.pt
│   ├── class_list.txt
│   ├── metrics.json           # 训练曲线
│   └── eval/                  # 混淆矩阵 + per-class 指标
│
├── tools/                     # 数据/训练/评估工具
│   ├── build_lines.py         #   行级字段归属
│   ├── build_dataset.py       #   crops × lines → train/val CSV
│   ├── train_classifier.py    #   ResNet18 / MobileNetV3
│   ├── eval_classifier.py     #   评估 + 混淆矩阵
│   ├── predict_classifier.py  #   单 PDF / 批量推理
│   ├── ab_compare.py          #   regex vs SER A/B
│   └── train_on_autodl.sh     #   autoDL 一键脚本
│
├── docs/
│   ├── train.md               # 完整训练手册（10 章）
│   └── ab_compare.md          # 烟测 A/B 对比报告
│
├── logs/                      # 训练/评估日志（手动放）
├── laebls.xlsx                # 解析结果输出
└── README.md / AGENTS.md
```

## 快速上手

### 跑现有数据（regex 模式）

```bash
uv sync
uv run parse_labels.py         # 输出 laebls.xlsx
```

### 跑 SER 分类器（如果有 ckpt）

```bash
uv run parse_labels.py --use-ser        # 用 models/usps_ser_v1/best.pt
```

### 从头训（autoDL 推荐）

```bash
# 一键（autoDL 上）
bash tools/train_on_autodl.sh

# 显式
uv run prepare_data.py
uv run python tools/build_lines.py
uv run python tools/build_dataset.py --val-ratio 0.15
uv run python tools/train_classifier.py --device cuda --pretrained --epochs 20 --use-class-weights
uv run python tools/eval_classifier.py
uv run python tools/ab_compare.py --ckpt models/usps_ser_v1/best.pt --pdf laebls/<挑3张>
```

## 13 个 SER 类别

```
0  other               7  sender_address
1  service             8  sender_city_state_zip
2  mail_class_letter   9  recipient_name
3  tracking_number    10  recipient_address
4  mailed_from_zip    11  recipient_csz
5  created_date       12  bottom_text
6  sender_name
```

被 SER 排除、仍走 regex 的字段：`weight / rdc / reference / scan_date`。

## 文档

- **[docs/train.md](docs/train.md)** — 10 章训练手册，含 autoDL 跨机同步
- **[docs/ab_compare.md](docs/ab_compare.md)** — 3 PDF 的 regex vs SER 对比