pdf_ocr_tool — PDF OCR 与总结工具集

从"判断 PDF 要不要 OCR"到"批量 OCR"到"派 subagent 总结"的完整工具链。

工具一览

pdf_ocr_tool/
├── pdf_detect.py            # 第 1 步：批量分类 PDF（TEXT / IMAGE）
├── pdf_sample.py            # 第 1.5 步：深度检查文本层质量
├── pdf_ocr.py               # 第 2 步：批量 OCR → Markdown
├── verify_output.py         # 校验：输入输出文件数量对齐、无缺失、无异常
├── summarize_prompt.md      # 总结规范模板（subagent 共享）
├── summarize_workflow.md    # 第 3 步：派 subagent 批量总结的工作流文档
├── requirements.txt         # Python 依赖
├── .gitignore
└── README.md                # 本文件

完整流程

一批 PDF
  │
  ▼
pdf_detect.py     ── 批量分类：哪些有文本层（TEXT），哪些是纯图片（IMAGE）
  │                   输出汇总表 + 需要 OCR 的数量
  │
  ├─ TEXT 型 ── pdf_sample.py ── 深度检查文本层质量
  │                                 如果质量好，可直接用，跳过 OCR
  │                                 如果质量差（幻灯片常见），仍需 OCR
  │
  ▼
pdf_ocr.py        ── 批量 OCR：每页渲染图片 → RapidOCR → Markdown
  │                   多进程并行，断点续跑
  │
  ▼
verify_output.py  ── 校验：OCR 产出数量对齐、无缺失、无异常小文件
  │
  ▼
summarize_workflow.md ── 派 background fixer 逐文件总结
                          共享 summarize_prompt.md 保证风格一致

安装

pip install -r requirements.txt

包	用于
pdfplumber	pdf_detect.py、pdf_sample.py（文本层抽取）
PyMuPDF (fitz)	pdf_ocr.py（PDF 渲染为图片）
rapidocr-onnxruntime	pdf_ocr.py（OCR 引擎，支持中文，无需 PaddlePaddle）
numpy	pdf_ocr.py（图片数组处理）

Python 3.8+。rapidocr-onnxruntime 在 Python 3.14 上也能装。

---

pdf_detect.py — 批量分类

判断哪些 PDF 有可用文本层、哪些需要 OCR。

# 分类当前目录所有 PDF
python pdf_detect.py

# 指定目录，抽样 5 页，阈值 200 字符
python pdf_detect.py -i ./pdfs --pages 5 --threshold 200

# 扫描全部页（更准但慢）
python pdf_detect.py --full

# 只列出需要 OCR 的（IMAGE 型）
python pdf_detect.py --only-image

# JSON 输出（便于管道处理）
python pdf_detect.py --json

参数	默认	说明
-i / --input	.	PDF 文件或目录
--pages	3	每个 PDF 抽样页数
--threshold	100	字符数阈值，低于此判定为 IMAGE
--full	关	扫描全部页
--only-image	关	只打印 IMAGE/ERROR 行
--json	关	JSON 输出

判断逻辑：抽样前 N 页，用 pdfplumber 抽文本层，总字符数 > 阈值 = TEXT，否则 = IMAGE。

---

pdf_sample.py — 深度检查文本层

pdf_detect.py 标为 TEXT 的不一定能用——幻灯片型 PDF 常有文本层但内容稀疏。用这个工具看实际抽取效果。

# 检查单个文件，预览前 600 字符
python pdf_sample.py -i report.pdf

# 多文件，预览 1000 字符
python pdf_sample.py -i a.pdf b.pdf --chars 1000

# 只看指定页
python pdf_sample.py -i report.pdf --pages 1,5,10

# 把全文导出为 .txt
python pdf_sample.py -i report.pdf --dump

参数	默认	说明
-i / --input	必填	PDF 文件（可多个）或目录
--chars	600	预览字符数
--pages	全部	指定页，如 1,3,5
--dump	关	同时导出全文到 <同名>.txt

输出：页数、总字符数、平均每页字符数、前 N 字符预览。

---

pdf_ocr.py — 批量 OCR

把每个 PDF 的每一页渲染成图片，跑 OCR，输出每页一节的 Markdown。对文本型和图片型 PDF 统一走图片 OCR 路径。

# OCR 当前目录所有 PDF -> ./ocr_output/
python pdf_ocr.py

# 单文件
python pdf_ocr.py -i report.pdf

# 指定输入输出、进程数、DPI
python pdf_ocr.py -i ./pdfs -o ./out -w 4 --dpi 300

# 强制重新 OCR
python pdf_ocr.py --force

# 同时写日志
python pdf_ocr.py --log run.log

参数	默认	说明
-i / --input	.	PDF 文件或目录
-o / --output	ocr_output	输出目录
-w / --workers	6	并行进程数
--dpi	200	渲染 DPI
--force	关	强制重新 OCR
--log	无	日志文件

也可作为库调用：

from pdf_ocr import ocr_pdfs

summary = ocr_pdfs(
    pdfs=["a.pdf", "b.pdf"],
    out_dir="./md_out",
    dpi=200,
    workers=4,
)

---

verify_output.py — 完整性校验

校验输出目录的每个 Markdown 是否都有对应输入，且无异常小文件。

# 基本校验
python verify_output.py ./ocr_output ./summaries

# 自定义最小文件阈值
python verify_output.py ./ocr_output ./summaries --threshold 1000

检查三项：数量对齐、无缺失、无异常小文件。退出码 0 = 全部正常，1 = 有问题。

---

summarize_workflow.md — Subagent 批量总结

OCR 完成后，派 background fixer 对每个 Markdown 做结构化总结。详见 summarize_workflow.md。

核心模式：共享 summarize_prompt.md 规范 + 一文件一 fixer + background 并行 + hook 回调收结果。

---

典型用法

# 0. 安装依赖
pip install -r requirements.txt

# 1. 先看哪些需要 OCR
python pdf_detect.py -i ./pdfs --only-image

# 2. 对 TEXT 型的抽查质量
python pdf_sample.py -i ./pdfs/某报告.pdf --chars 1000

# 3. 批量 OCR
python pdf_ocr.py -i ./pdfs -o ./ocr_output -w 6

# 4. 校验 OCR 产出
python verify_output.py ./pdfs ./ocr_output

# 5. 派 subagent 总结（见 summarize_workflow.md）