543 lines
14 KiB
Markdown
543 lines
14 KiB
Markdown
# PaddleOCR-VL-1.6 本地 OCR
|
||
|
||
本项目使用 PaddleOCR-VL-1.6 实现统一的图片 OCR、批量图片 OCR 和 PDF 识别，CPU/GPU 环境完全隔离，并通过根目录唯一入口 `ocr.py` 调用。
|
||
|
||
PDF 默认使用 **文本提取 + OCR 混合模式**：优先提取 PDF 原始文本层，仅当页面没有有效文本层或文本质量不足时才加载 PaddleOCR-VL 并 OCR。
|
||
|
||
> 当前开发机器只有集成显卡。CPU 功能已验证；GPU 代码已实现，但必须在 NVIDIA CUDA GPU 机器上安装和测试。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
ocr-VL1.6/
|
||
├── ocr.py # 唯一用户入口，自动选择 CPU/GPU 子环境
|
||
├── benchmark.py # data 参数矩阵测试与 Markdown 报告
|
||
├── ocr_app/ # CPU/GPU 共享业务代码
|
||
│ ├── cli.py # image/batch/pdf/verify 命令
|
||
│ ├── commands.py # 命令实现
|
||
│ ├── runtime.py # 设备验证、模型延迟加载
|
||
│ ├── pdf.py # 混合 PDF、断点续传、导出
|
||
│ ├── pdf_text.py # 文本层提取与质量评估
|
||
│ ├── output.py # 图片/PDF/批次统一输出路径和保存
|
||
│ └── logging_utils.py # UTF-8 结构化日志
|
||
├── cpu/
|
||
│ ├── pyproject.toml # CPU 独立依赖
|
||
│ ├── uv.lock # CPU 独立锁文件
|
||
│ ├── .python-version # Python 3.13
|
||
│ └── runner.py # 统一入口的 CPU 执行器
|
||
├── gpu/
|
||
│ ├── pyproject.toml # GPU 独立依赖
|
||
│ ├── .python-version # Python 3.11
|
||
│ ├── setup_env.py # CUDA Wheel 安装脚本
|
||
│ └── runner.py # 统一入口的 GPU 执行器
|
||
├── data/
|
||
│ ├── images/ # 测试图片
|
||
│ └── documents/ # 测试 PDF
|
||
├── outputs/ # PDF 输出（git ignored）
|
||
├── benchmarks/ # 单图 Benchmark JSON
|
||
├── logs/ # UTF-8 运行日志
|
||
└── tests/ # 共享逻辑测试
|
||
```
|
||
|
||
根目录不再保存 Paddle 虚拟环境或 Python 项目依赖。CPU 与 GPU 分别使用 `cpu/.venv` 和 `gpu/.venv`。
|
||
|
||
## 安装
|
||
|
||
### CPU
|
||
|
||
```bash
|
||
uv sync --project cpu
|
||
```
|
||
|
||
### GPU
|
||
|
||
根据目标机器 CUDA/驱动和 PaddlePaddle 官方兼容表选择 Wheel：
|
||
|
||
```bash
|
||
python gpu/setup_env.py --cuda cu118 --dry-run
|
||
python gpu/setup_env.py --cuda cu118
|
||
```
|
||
|
||
也支持：
|
||
|
||
```bash
|
||
python gpu/setup_env.py --cuda cu126
|
||
```
|
||
|
||
安装成功后脚本生成 `gpu/.gpu-ready`。统一入口只会调用已安装的 `gpu/.venv`，不会从默认 PyPI 误装 GPU 包，也不会回退到 CPU。
|
||
|
||
## 简化统一入口
|
||
|
||
主用法只有一种：
|
||
|
||
```bash
|
||
python ocr.py <文件或目录> --device cpu|gpu
|
||
```
|
||
|
||
程序自动判断输入类型：
|
||
|
||
| 输入 | 自动路由 |
|
||
|------|----------|
|
||
| `.png/.jpg/.jpeg/.bmp/.tif/.tiff/.webp` | 图片 OCR + Benchmark |
|
||
| `.pdf` | PDF 混合文本提取/OCR |
|
||
| 目录 | 发现其中的图片和 PDF，逐个调用同一个单文件路由器 |
|
||
|
||
不支持的文件后缀会给出明确错误；目录模式会自动忽略不支持的文件。
|
||
|
||
### 验证环境
|
||
|
||
```bash
|
||
python ocr.py verify --device cpu
|
||
python ocr.py verify --device gpu
|
||
```
|
||
|
||
### 单张图片
|
||
|
||
```bash
|
||
python ocr.py data/images/手写01.png --device cpu
|
||
```
|
||
|
||
多轮 Benchmark：
|
||
|
||
```bash
|
||
python ocr.py data/images/手写01.png \
|
||
--device cpu \
|
||
--warmup 1 \
|
||
--rounds 3
|
||
```
|
||
|
||
图片识别结果和 Benchmark 默认一起写入：
|
||
|
||
```text
|
||
outputs/images/<图片名_扩展名>/
|
||
```
|
||
|
||
### 单个 PDF
|
||
|
||
```bash
|
||
python ocr.py data/documents/sample.pdf --device cpu
|
||
```
|
||
|
||
PDF 默认使用混合模式。强制模式：
|
||
|
||
```bash
|
||
python ocr.py sample.pdf --pdf-mode text --device cpu
|
||
python ocr.py sample.pdf --pdf-mode ocr --device cpu
|
||
```
|
||
|
||
`--mode` 仍作为 `--pdf-mode` 的简写别名保留。
|
||
|
||
### 批量目录
|
||
|
||
```bash
|
||
# 扫描当前目录层级中的图片和 PDF
|
||
python ocr.py data/ --device cpu
|
||
|
||
# 递归扫描所有子目录
|
||
python ocr.py data/ --recursive --device cpu
|
||
```
|
||
|
||
目录模式的底层就是重复调用同一个单文件路由器，因此：
|
||
|
||
- 图片使用与单图片相同的 Benchmark 和日志逻辑
|
||
- PDF 使用与单 PDF 相同的混合路由、断点和导出逻辑
|
||
- 所有文件共享同一个延迟加载模型实例
|
||
- 电子 PDF 不会触发模型加载；首张图片或首个 OCR 页面才加载模型
|
||
- 保持串行处理，避免此前多进程造成卡顿、无响应和黑屏
|
||
|
||
递归目录的图片和 PDF 输出都会保留相对目录结构，避免不同子目录下同名文件相互覆盖。
|
||
|
||
## 统一输出目录
|
||
|
||
图片和 PDF 现在都会写入 `--output` 指定目录，默认是 `outputs/`：
|
||
|
||
```text
|
||
outputs/
|
||
├── images/
|
||
│ └── <相对目录>/<图片名_扩展名>/
|
||
│ ├── result.md # Markdown 结果
|
||
│ ├── result.txt # 纯文本结果
|
||
│ ├── result.json # PaddleOCR 结构化结果
|
||
│ ├── benchmark.json # 模型/推理/导出耗时
|
||
│ └── assets/ # 识别结果中的图片资源（如有）
|
||
├── pdfs/
|
||
│ └── <相对目录>/<PDF名>/
|
||
│ ├── manifest.json
|
||
│ ├── document.md
|
||
│ ├── document.json
|
||
│ └── pages/
|
||
└── batches/
|
||
└── <目录名>-<时间戳>.json # 批量任务汇总
|
||
```
|
||
|
||
例如：
|
||
|
||
```bash
|
||
python ocr.py data/images/名片01.jpg --device cpu
|
||
```
|
||
|
||
会生成：
|
||
|
||
```text
|
||
outputs/images/名片01_jpg/result.md
|
||
outputs/images/名片01_jpg/result.txt
|
||
outputs/images/名片01_jpg/result.json
|
||
outputs/images/名片01_jpg/benchmark.json
|
||
```
|
||
|
||
图片目录名包含扩展名，避免 `same.png` 与 `same.jpg` 相互覆盖。
|
||
|
||
重构前生成的 PDF 结果可能仍直接位于 `outputs/<PDF名>/`。这些旧结果不会自动删除；新任务统一写入 `outputs/pdfs/<PDF名>/`，确认不再需要后可手动迁移或清理。
|
||
|
||
目录任务再次运行时：
|
||
|
||
- 已存在的 PDF manifest 自动断点续传
|
||
- 新加入的 PDF 自动创建新任务
|
||
- 图片重新识别，并使用原子写入覆盖对应输出文件
|
||
- `--overwrite` 会强制 PDF 重新处理
|
||
- 每次目录任务都会生成新的 `outputs/batches/*.json` 汇总
|
||
|
||
旧命令前缀 `image`、`pdf`、`batch` 暂时兼容，例如 `python ocr.py image a.png`，但推荐直接传入路径。
|
||
|
||
## PDF 混合模式
|
||
|
||
### 默认：hybrid
|
||
|
||
```bash
|
||
python ocr.py data/documents/sample.pdf --device cpu
|
||
```
|
||
|
||
每页流程：
|
||
|
||
```text
|
||
读取 PDF 文本层
|
||
↓
|
||
文本质量评估
|
||
┌────┴────┐
|
||
│ │
|
||
有效文本 无效/不足
|
||
│ │
|
||
直接保存 渲染页面 → PaddleOCR-VL
|
||
└────┬────┘
|
||
↓
|
||
逐页 Markdown/JSON + 合并文档
|
||
```
|
||
|
||
如果整份 PDF 都具有有效文本层，模型完全不会加载。实测项目中的电子合同 PDF，单页混合处理约 `0.06s`，且 `model_used=false`。
|
||
|
||
### 强制文本模式
|
||
|
||
```bash
|
||
python ocr.py data/documents/sample.pdf \
|
||
--device cpu \
|
||
--pdf-mode text
|
||
```
|
||
|
||
所有页面只提取 PDF 文本层，不执行 OCR。扫描页可能得到空文本。
|
||
|
||
### 强制 OCR 模式
|
||
|
||
```bash
|
||
python ocr.py data/documents/sample.pdf \
|
||
--device cpu \
|
||
--pdf-mode ocr
|
||
```
|
||
|
||
所有页面都渲染后交给 PaddleOCR-VL，适合模型一致性 Benchmark。
|
||
|
||
## 文本层质量判定
|
||
|
||
混合模式默认要求：
|
||
|
||
| 参数 | 默认值 | 含义 |
|
||
|------|-------:|------|
|
||
| `--text-min-chars` | 50 | 非空白字符最小数量 |
|
||
| `--text-min-printable-ratio` | 0.85 | 可打印字符最低比例 |
|
||
| `--text-min-content-ratio` | 0.60 | 字母、数字、CJK 字符最低比例 |
|
||
| `--text-max-replacement-ratio` | 0.02 | Unicode 替换字符最高比例 |
|
||
| `--text-min-density` | 25 | 页面文本密度最低值 |
|
||
|
||
例如某些扫描 PDF 只有页码或隐藏乱码层，混合模式会因为 `too_few_characters`、`low_content_ratio` 或 `high_replacement_ratio` 自动回退 OCR。
|
||
|
||
每页的判定结果会写入日志和 manifest：
|
||
|
||
```json
|
||
{
|
||
"source_type": "ocr",
|
||
"routing_reason": "too_few_characters",
|
||
"text_layer": {
|
||
"usable": false,
|
||
"non_whitespace_chars": 8,
|
||
"printable_ratio": 1.0,
|
||
"content_ratio": 0.75
|
||
}
|
||
}
|
||
```
|
||
|
||
## PDF 页码与恢复
|
||
|
||
```bash
|
||
# 第 1～5 页、第 8 页、第 10 页到末页
|
||
python ocr.py sample.pdf --pages "1-5,8,10-" --device cpu
|
||
|
||
# 中断后继续
|
||
python ocr.py sample.pdf --resume --device cpu
|
||
|
||
# 删除旧输出并重做
|
||
python ocr.py sample.pdf --overwrite --device cpu
|
||
```
|
||
|
||
`--resume` 会校验：
|
||
|
||
- PDF SHA-256
|
||
- PDF 处理模式
|
||
- DPI
|
||
- 文本层判定阈值
|
||
- manifest 版本
|
||
|
||
旧纯 OCR manifest（版本 1）不能直接用于新混合模式，请使用 `--overwrite` 重新生成。
|
||
|
||
## PDF 输出
|
||
|
||
```text
|
||
outputs/pdfs/<PDF名>/
|
||
├── manifest.json
|
||
├── document.md
|
||
├── document.json
|
||
├── pages/
|
||
│ ├── page-0001.md
|
||
│ ├── page-0001.json
|
||
│ └── ...
|
||
├── assets/
|
||
└── rendered/ # 仅 --keep-rendered 时存在
|
||
```
|
||
|
||
合并 Markdown 标题会标明页面来源：
|
||
|
||
```markdown
|
||
## Page 1 (text)
|
||
## Page 2 (ocr)
|
||
```
|
||
|
||
Manifest 汇总包括：
|
||
|
||
```json
|
||
{
|
||
"text_pages": 8,
|
||
"ocr_pages": 2,
|
||
"model_used": true,
|
||
"model_initialized_during_task": true,
|
||
"timing": {
|
||
"text_extract_total_seconds": 0.15,
|
||
"render_total_seconds": 0.8,
|
||
"ocr_total_seconds": 324.5,
|
||
"model_init_seconds": 40.0,
|
||
"task_total_seconds": 366.0
|
||
}
|
||
}
|
||
```
|
||
|
||
## PDF 常用参数
|
||
|
||
```bash
|
||
python ocr.py sample.pdf \
|
||
--device cpu \
|
||
--pdf-mode hybrid \
|
||
--pages "1-10" \
|
||
--dpi 144 \
|
||
--threads 18 \
|
||
--keep-rendered \
|
||
--log-file logs/pdf-sample.log
|
||
```
|
||
|
||
DPI 建议：
|
||
|
||
| 文档 | DPI |
|
||
|------|----:|
|
||
| 普通打印文字 | 120～144 |
|
||
| 小字号 | 150～200 |
|
||
| 手写/低质量扫描件 | 200～250 |
|
||
|
||
DPI 只影响需要 OCR 的页面，不影响直接提取文本层的页面。
|
||
|
||
## 日志
|
||
|
||
统一日志格式：
|
||
|
||
```text
|
||
2026-07-16 15:07:45 | INFO | pid=33552 | PAGE_ROUTED page=1 source=text reason=usable_text_layer
|
||
```
|
||
|
||
默认目录：
|
||
|
||
```text
|
||
logs/input/
|
||
logs/verify/
|
||
logs/legacy/
|
||
```
|
||
|
||
主要事件：
|
||
|
||
- `RUNTIME_PREPARED`
|
||
- `MODEL_INITIALIZED`
|
||
- `FILE_ROUTED`
|
||
- `PAGE_ROUTED`
|
||
- `PAGE_FINISHED`
|
||
- `TASK_COMPLETED`
|
||
- `IMAGE_COMPLETED`
|
||
- `DIRECTORY_SUMMARY`
|
||
- `VERIFY_COMPLETED`
|
||
|
||
日志使用 UTF-8。Windows 控制台即使显示乱码，日志文件中的中文仍正常。
|
||
|
||
## 参数矩阵性能测试
|
||
|
||
新增 `benchmark.py`，会对 `data/` 中的图片和 PDF 按多组参数运行，统计速度并增量生成 Markdown 报告。
|
||
|
||
也可通过统一入口调用：
|
||
|
||
```bash
|
||
python ocr.py benchmark --profile smoke --device cpu
|
||
```
|
||
|
||
默认报告：
|
||
|
||
```text
|
||
benchmarks/parameter-comparison.md
|
||
```
|
||
|
||
每个用例的日志、输出和批次 manifest 保存在：
|
||
|
||
```text
|
||
benchmarks/runs/<运行时间>/<case-id>/
|
||
```
|
||
|
||
### 预设矩阵
|
||
|
||
```bash
|
||
# 较快：图片 token=64/128、PDF hybrid/text
|
||
python ocr.py benchmark --profile smoke --device cpu
|
||
|
||
# 常用对比：增加 CPU 线程、默认 token、PDF 阈值和 OCR DPI
|
||
python ocr.py benchmark --profile standard --device cpu
|
||
|
||
# 完整矩阵：更多线程、token 和 DPI，耗时最长
|
||
python ocr.py benchmark --profile full --device cpu
|
||
```
|
||
|
||
真实 CPU OCR 很慢，`standard/full` 可能运行数小时。建议先运行 `smoke`，或通过 `--case` 单独运行：
|
||
|
||
```bash
|
||
python ocr.py benchmark \
|
||
--profile standard \
|
||
--case image-threads-8 \
|
||
--case image-threads-safe \
|
||
--device cpu
|
||
```
|
||
|
||
查看用例列表而不执行：
|
||
|
||
```bash
|
||
python ocr.py benchmark --profile standard --list-cases
|
||
```
|
||
|
||
仅生成计划和空报告：
|
||
|
||
```bash
|
||
python ocr.py benchmark --profile standard --dry-run
|
||
```
|
||
|
||
### 自定义参数矩阵
|
||
|
||
示例配置：
|
||
|
||
```text
|
||
benchmarks/parameter-matrix.example.json
|
||
```
|
||
|
||
运行：
|
||
|
||
```bash
|
||
python ocr.py benchmark \
|
||
--config benchmarks/parameter-matrix.example.json \
|
||
--device cpu \
|
||
--report benchmarks/custom-comparison.md
|
||
```
|
||
|
||
每个 case 支持统一入口中的参数，例如：
|
||
|
||
```json
|
||
{
|
||
"id": "image-threads-8",
|
||
"title": "图片 8 线程",
|
||
"group": "image-threads",
|
||
"kind": "image",
|
||
"params": {
|
||
"threads": 8,
|
||
"max_new_tokens": 64,
|
||
"rounds": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### Markdown 报告统计
|
||
|
||
报告按参数组比较：
|
||
|
||
- 系统、CPU、逻辑核心和内存信息
|
||
- 测试文件清单、类型和大小
|
||
- Wall time
|
||
- 模型初始化耗时
|
||
- 图片核心推理 / PDF OCR 总耗时
|
||
- 平均每文件耗时
|
||
- 每分钟处理文件数
|
||
- 相对基准加速比
|
||
- 输出文本字符数
|
||
- 文本 SHA-256 是否一致
|
||
- PDF Text/OCR 页数
|
||
- PDF 路由原因统计
|
||
- 完整命令、日志和输出路径
|
||
|
||
报告每完成一个 case 就原子更新；按 `Ctrl+C` 中断时，已经完成的结果不会丢失。
|
||
|
||
其他参数：
|
||
|
||
```text
|
||
--data PATH 测试数据目录
|
||
--report PATH Markdown 报告位置
|
||
--run-root PATH 详细运行数据目录
|
||
--timeout SEC 单个用例超时
|
||
--case ID 只执行指定用例，可重复使用
|
||
```
|
||
|
||
## 自动化测试
|
||
|
||
```bash
|
||
uv run --project cpu pytest -q
|
||
```
|
||
|
||
当前测试覆盖：
|
||
|
||
- 页码范围解析
|
||
- 文本标准化
|
||
- 有效文本层判定
|
||
- 空文本/短文本自动回退条件
|
||
- 根入口设备解析
|
||
|
||
当前结果：
|
||
|
||
```text
|
||
21 passed
|
||
```
|
||
|
||
## 已验证状态
|
||
|
||
- CPU `verify`：通过
|
||
- 单图统一入口：假模型端到端通过，原真实模型能力此前已验证
|
||
- 批量统一入口：假模型端到端通过
|
||
- PDF `hybrid` 电子文本页：真实 PDF 验证通过，未加载模型
|
||
- PDF 扫描页自动回退 OCR：假模型端到端通过
|
||
- PDF `text` / `ocr` 强制模式：通过
|
||
- GPU 环境路由：无环境时安全提示，不回退 CPU
|
||
- GPU 实机推理：尚未验证
|