pdf-ocr-md — PDF → OCR → 结构化 Markdown

> 环境：

> - lit — LiteParse 快速文本层解析（~/.venvs/liteparse/，Rust 核心）

> - pdf2md — PaddleOCR 中文扫描件（~/.venvs/paddleocr/）

> - ocr6 — PP-OCRv6 三档模型（~/.venvs/ppocrv6/，ONNX Runtime），见 F 节

> - prep — 文档预处理（含倾斜/方向/展平），见 D 节

>

> 快速选择：不确定类型 → lit parse file.pdf --no-ocr，空结果再退到 prep + ocr6

>

> 曾用名：pdf2md（因 SkillHub/ClawHub 已被占用，v1.1.0 起更名）

>

> 一体化 skill：合并了原 opendataloader-pdf、paddleocr-chinese 和 pdf-ocr-md。

> 详见 references/opendataloader.md 和 references/paddleocr.md。

用法

快速选择（推荐）

# ① 先试试 LiteParse（文本层PDF秒出）
lit parse input.pdf --no-ocr -o output.txt

# ② 如果输出为空，说明是扫描件
#     按需选模型档位（速度从快到慢：tiny > small > medium）
python scripts/pdf_ocr_v6.py input.pdf --tier tiny -o ./output

直接指定

# 文本层PDF（电子合同/报表）
lit parse input.pdf --no-ocr -o output.txt

# 中文扫描件（合同/发票）— 先预处理
python scripts/pdf_preprocess.py input.pdf -o ./preprocessed --all
pdf2md ./preprocessed/input_p001.jpg -o ./output_dir

# 或快速跳过预处理（平整的扫描件）
pdf2md input.pdf -o ./output_dir

输出：

• LiteParse: output.txt — 纯文本（版面保持）
• pdf2md: output_dir/input.md — Markdown + input.json + input_images/
• 预处理: preprocessed/ — 经过校正/展平的图片

工作流总览

输入文档
  ├── 有文本层 → LiteParse 提取 (~0.9ms/页)
  │
  └── 无文本层（扫描件）
       ├── ① 选择模型档位
       │    ├── Tiny  (1.5 MB)  极速
       │    ├── Small (7.7 MB)  均衡
       │    └── Medium(34.5 MB) 高精度
       │
       ├── ② 预处理（根据文档状况）
       │    ├── --deskew    倾斜校正
       │    ├── --orient    方向校正
       │    ├── --unwarp    文档展平
       │    └── --all       全部
       │
       └── ③ PP-OCRv6 OCR → 文本 / JSON

> LiteParse 比 OpenDataLoader 快约 300 倍（0.9ms vs 300ms），且不用装 Java 11。

性能参考（CPU）

| 类型 | 引擎 | 单页耗时 | 17页合同 |

|------|------|---------|----------|

| 文本层 PDF | LiteParse --no-ocr | ~0.9ms | ~15ms |

| 文本层 PDF | OpenDataLoader（旧） | ~15ms | ~300ms |

| PP-OCRv6 Tiny | ONNX Runtime (CPU) | ~3-8s | ~1-2min |

| PP-OCRv6 Small | ONNX Runtime (CPU) | ~8-15s | ~2-4min |

| PP-OCRv6 Medium | ONNX Runtime (CPU) | ~15-30s | ~4-8min |

| 预处理-倾斜校正 | OpenCV Hough | ~300ms | ~5s |

| 预处理-文档展平 | OpenCV 透视变换 | ~500ms | ~8s |

| 扫描件（中文） | PaddleOCR PP-OCRv4（旧） | ~15s | ~4.5min |

| 扫描件（中文） | Tesseract chi_sim | ~170ms | ~3s |

| 扫描件（英文） | LiteParse 默认 | ~170ms | ~3s |

准确率

| 引擎 | 中文扫描件 |

|------|-----------|

| PP-OCRv6 Medium | ~0.425 ed (OmniDocBench) |

| PP-OCRv6 Small | ~0.443 ed |

| PP-OCRv6 Tiny | ~0.446 ed |

| Apple Vision (macOS) | ~0.448 ed |

| PaddleOCR PP-OCRv4 | ~97%+ |

| + 预处理 | ~98%+ (歪斜/弯曲照片) |

注意事项

• 首次运行自动下载模型（版面分析 ~770 weights + OCR det/cls/rec ~17MB）
• 模型从 hf-mirror.com / modelscope.cn 下载，国内畅通
• 机器有 3.6GB 内存，PaddleOCR 冷启动 ~300MB 峰值可承受
• 中文 OCR 场景：LiteParse(Tesseract) ~80% → 退到 PaddleOCR ~97%+，准确率优先时用 pdf2md
• 英文 / Office 文档场景可优先试 LiteParse（见 C 节）
• 预处理能提升照片/弯曲文档的 OCR 准确率 1~5%，对平整扫描件效果不明显
• 结构化解析（doc-parsing）会额外增加版面分析时间, 但输出更结构化

A：OpenDataLoader — 文本层 PDF 解析

适用于有文本层的 PDF（电子合同、报表、PDF/A 文件）。支持的 CLI 和 Python SDK，完整用法详见 references/opendataloader.md。

快速启动

# 安装
python3 -m venv ~/.venvs/opendataloader
~/.venvs/opendataloader/bin/pip install -i https://pypi.tuna.tsinghua.edu.cn/simple opendataloader-pdf

# CLI
opendataloader-pdf input.pdf -f json,markdown -o ./output

# Python
from opendataloader_pdf import convert
convert("input.pdf", output_dir="./out", format="json,markdown")

关键特性

• 输出格式：JSON（含 bounding box/font/size）、Markdown、HTML、Text、Tagged PDF
• 表格检测：--table-method cluster 模式
• 脱敏：--sanitize 替换邮箱/电话/银行卡号
• 页码范围：--pages "1,3,5-7" 指定页
• 性能：~0.015s/页（纯 Java 本地模式，无网络）

环境前提

• Java 11+ (java -version)
• PyPI 官方源可能超时 → 用清华镜像 -i https://pypi.tuna.tsinghua.edu.cn/simple

B：PaddleOCR — 中文扫描件 OCR

适用于无文本层的扫描件 PDF（合同、发票、报纸）。详见 references/paddleocr.md。

快速启动

# 环境
python3 -m venv ~/.venvs/paddleocr
~/.venvs/paddleocr/bin/pip install paddlepaddle==2.6.2 "numpy<2" paddleocr==2.7.3

# CLI —— 逐张 OCR 图片
~/.venvs/paddleocr/bin/python -c "
from paddleocr import PaddleOCR
ocr = PaddleOCR(lang='ch')
result = ocr.ocr('page.png')
for line_info in result[0]:
    text = line_info[1][0]; conf = line_info[1][1]
    print(f'{conf:.2f} {text}')
"

关键特性

• PP-OCRv4 模型，简体中文 ~98%，繁体 ~95%
• 支持竖排文字、手写体
• 公章/签名基本可识别（Tesseract 在此场景乱码）
• 可配合 pdf2image 拆分扫描件 PDF

精度对比

| 引擎 | 简体中文 | 繁体中文 | 公章/签名 | 竖排 |

|------|---------|---------|-----------|------|

| Tesseract chi_sim | ~80% | ~60% | ❌ 乱码 | ❌ |

| PaddleOCR PP-OCRv4 | ~98% | ~95% | ✅ 基本正确 | ✅ |

常见问题

• 错字多：提高 DPI 到 400-600，降低过滤阈值到 0.3
• 表格差：对密集表格用 docling（pdf2md 集成管线）
• GPU 加速：pip install paddlepaddle-gpu==2.6.2 + use_gpu=True

Python 3.13 兼容性注意事项

> ⚠️ 重要：PaddleOCR 在 Python 3.13 环境下存在多个兼容性问题，需手动修复。

问题1：imghdr 模块缺失

现象：

ModuleNotFoundError: No module named 'imghdr'

原因： Python 3.13 移除了 imghdr 模块（原用于检测图像类型）

解决方案： 创建兼容 shim 模块

# 保存到 site-packages/imghdr.py
"""imghdr module shim for Python 3.13+ compatibility"""
def whatfile(f):
    return None

def what(buf, h=None):
    return None

问题2：np.sctypes 移除

现象：

AttributeError: module 'numpy' has no attribute 'sctypes'

原因： NumPy 2.0 移除了 np.sctypees 属性（imgaug 包使用了该属性）

解决方案： 修改 site-packages/imgaug/imgaug.py 第44-46行

# 原代码（不可用）：
# NP_FLOAT_TYPES = set(np.sctypes["float"])
# NP_INT_TYPES = set(np.sctypes["int"])
# NP_UINT_TYPES = set(np.sctypes["uint"])

# 修复后：
NP_FLOAT_TYPES = {np.float16, np.float32, np.float64}
NP_INT_TYPES = {np.int8, np.int16, np.int32, np.int64}
NP_UINT_TYPES = {np.uint8, np.uint16, np.uint32, np.uint64}

问题3：OpenCV 与 NumPy 2.x 不兼容

现象：

ImportError: numpy.core.multiarray failed to import

原因： opencv-python 4.6 是针对 NumPy 1.x 编译的，与 NumPy 2.x ABI 不兼容

解决方案： 改用 opencv-python-headless 4.13.0.92+

~/.venvs/paddleocr/bin/pip uninstall opencv-python -y
~/.venvs/paddleocr/bin/pip install opencv-python-headless --no-cache-dir

问题4：scikit-image DLL 加载失败（Windows）

现象：

ImportError: DLL load failed while importing _cython_blas

原因： Windows 安全策略阻止未签名的 C 扩展 DLL

解决方案：

• 方案A：使用预编译的 wheel（推荐）
• 方案B：临时关闭 Windows Defender 实时保护
• 方案C：使用 WSL2 或 Linux 环境

推荐的 Python 3.13 安装命令

# 环境
python3 -m venv ~/.venvs/paddleocr
source ~/.venvs/paddleocr/bin/activate

# 安装（使用 PaddlePaddle 3.0.0，支持 NumPy 2.x）
pip install paddlepaddle==3.0.0
pip install "numpy>=2" paddleocr==2.7.3
pip uninstall opencv-python -y
pip install opencv-python-headless --no-cache-dir

# 创建 imghdr shim
cat > ~/.venvs/paddleocr/lib/python3.13/site-packages/imghdr.py << 'EOF'
def whatfile(f):
    return None
def what(buf, h=None):
    return None
EOF

# 修补 np.sctypes 问题
# 手动编辑 ~/.venvs/paddleocr/lib/python3.13/site-packages/imgaug/imgaug.py

C：LiteParse — 文本层 PDF 快速解析（Rust）

LlamaIndex 出品（8k⭐），Rust 核心，轻量零依赖。

安装

# 已安装: ~/.venvs/liteparse/ + ~/.local/bin/lit
pip install liteparse              # Python
npm i @llamaindex/liteparse        # Node.js
cargo install liteparse            # Rust CLI

核心命令

# 文本层PDF → 文本（推荐 --no-ocr，跳过不必要的OCR）
lit parse input.pdf --no-ocr -o output.txt

# 扫描件PDF → 文本（内置Tesseract，中文用 --ocr-language chi_sim）
lit parse input.pdf --ocr-language chi_sim -o output.txt

# 批量处理
lit batch-parse ./input-dir ./output-dir

# 生成截图（用于LLM视觉分析）
lit screenshot input.pdf -o ./screenshots --dpi 200

关键特性

| 特性 | 说明 |

|------|------|

| 文本层提取 | PDFium，0.9ms/页，比 OpenDataLoader 快 300x |

| 多格式输入 | PDF / 图片（PNG/JPG） |

| OCR 引擎 | 内置 Tesseract；可接 HTTP OCR server（PaddleOCR/自定义） |

| 输出格式 | 纯文本 / JSON（含 bounding box） |

| 截图输出 | lit screenshot 生成整页 PNG（支持 --target-pages） |

| 语言绑定 | Python / Node.js / Rust CLI / WASM |

| 平台 | Linux / macOS / Windows |

| License | Apache 2.0 |

局限

| 局限 | 说明 | 替代方案 |

|------|------|---------|

| 中文 OCR 准确率差 | Tesseract chi_sim ~80% vs PaddleOCR ~97% | 退到 pdf2md（见 B 节） |

| Office 文档 | DOCX/XLSX/PPTX 需 LibreOffice 转换 | 暂不支持，需时再装 |

| 表格识别 | 无版面分析，纯坐标提取 | 退到 pdf2md（docling 版面分析） |

机器资源

• 内存：LiteParse 进程 ~50MB（含 Tesseract 模型）
• 磁盘：~/.venvs/liteparse/ ~35MB + tessdata ~15MB
• 安装：pip install liteparse 一行即可

D：文档预处理 — 扫描件 OCR 增强

适用于质量不佳的扫描件（手机拍照、弯曲书页、倾斜/倒置的文档）。

预处理后 PaddleOCR 的中文准确率可从 ~97% 提升到 ~98%+。

安装

pip install opencv-python-headless numpy Pillow pdf2image

CLI 命令

# 全部预处理（推荐）
python scripts/pdf_preprocess.py input.pdf -o ./preprocessed --all

# 仅倾斜校正
python scripts/pdf_preprocess.py input.jpg -o ./output --deskew

# 仅方向校正
python scripts/pdf_preprocess.py input.jpg -o ./output --orient

# 仅文档展平（弯曲/透视照片）
python scripts/pdf_preprocess.py input.jpg -o ./output --unwarp

# PDF 全页 + 高DPI
python scripts/pdf_preprocess.py input.pdf -o ./preprocessed --all --dpi 400

# 预览模式（显示对比图，不保存）
python scripts/pdf_preprocess.py input.jpg --preview --all

预处理项说明

| 预处理 | CLI 参数 | 适用场景 | 效果 |

|--------|---------|---------|------|

| 倾斜校正 (deskew) | --deskew | 扫描件轻微歪斜 (<15°) | 自动检测角度并旋转正位 |

| 方向校正 (orient) | --orient | 页面旋转/倒置 | 检测文本方向并自动旋转到正位 |

| 文档展平 (unwarp) | --unwarp | 手机拍的弯曲/透视变形的文档 | 自动检测边界, 透视变换展平 |

工作流集成

# 完整管线: 预处理 → pdf2md
python scripts/pdf_preprocess.py input.pdf -o ./preprocessed --all
pdf2md ./preprocessed/input_p001.jpg -o ./output_dir

# 对于平整扫描件, 预处理效果不大, 可跳过
pdf2md input.pdf -o ./output_dir

预处理效果预测

| 文档类型 | 建议 | 预期提升 |

|---------|------|---------|

| 平整扫描件 (A4 扫描仪) | 跳过预处理 | OCR 已很好, 无明显提升 |

| 轻微歪斜 (< 15°) | --deskew | 准确率 +1~2% |

| 照片 (手机拍文档) | --deskew --unwarp | 准确率 +3~5% |

| 页面倒置/旋转 | --orient | 从乱码到正常识别 |

| 弯曲书页 | --unwarp | 准确率 +2~4% |

脚本参考

预处理脚本位于 scripts/pdf_preprocess.py，支持作为 Python 模块导入使用：

from scripts.pdf_preprocess import preprocess_image, deskew_image, unwarp_image
import cv2

img = cv2.imread('scan.jpg')
processed = preprocess_image(img, deskew=True, orient=True, unwarp=True)
cv2.imwrite('corrected.jpg', processed)

---

## E：结构化文档解析 — 版面分析 + 表格提取

利用 docling 进行深度版面分析, 输出结构化 Markdown 和 JSON。
保留文档的标题层级、表格、列表、图片标注等逻辑结构。

### 安装

pip install docling

docling 2.97+ 会自动安装版面分析模型

### CLI 命令

结构化解析为 Markdown + JSON

python scripts/pdf_parse_structured.py input.pdf -o ./output

禁用 OCR (文本层 PDF, 更快)

python scripts/pdf_parse_structured.py input.pdf -o ./output --no-ocr

仅输出 Markdown

python scripts/pdf_parse_structured.py input.pdf -o ./output --md-only

仅输出 JSON (含完整版面坐标)

python scripts/pdf_parse_structured.py input.pdf -o ./output --json-only

仅前3页

python scripts/pdf_parse_structured.py input.pdf -o ./output --pages "1-3"

### 输出说明

output/

├── input.md ← 结构化 Markdown (标题层级/表格/列表)

└── input.json ← 完整解析结果 (含版面坐标、表格网格、元数据)

### JSON 数据结构

{

"metadata": {

"file": "合同.pdf",

"pages": 17,

"has_ocr": true

},

"items": [

{ "type": "heading", "text": "第一章 总则", "bbox": {...} },

{ "type": "paragraph", "text": "根据《中华人民共和国...", "bbox": {...} },

{ "type": "list", "text": "甲乙双方应遵守..." }

],

"tables": [

{

"page": 3,

"grid": [["项目", "金额"], ["服务费", "10000"]],

"markdown": "| 项目 | 金额 |\n| --- | --- |\n| 服务费 | 10000 |"

}

]

}

### 工作流集成

完整管线: 预处理 → 结构化解析

python scripts/pdf_preprocess.py input.pdf -o ./preprocessed --all

python scripts/pdf_parse_structured.py ./preprocessed/input_p001.jpg -o ./output

也可直接解析

python scripts/pdf_parse_structured.py input.pdf -o ./output

### 关键特性

| 特性 | 说明 |
|------|------|
| 版面分析 | docling 深度学习版面分析, 识别标题/段落/表格/列表 |
| 表格提取 | 自动检测表格边界, 输出 Markdown 表格 + JSON 网格 |
| 标题层级 | 保留文档逻辑结构 |
| 元数据 | 页数、页码、元素统计 |
| 结构化 JSON | 含 bbox 坐标, 可用于后续处理 |
| 预处理兼容 | 可与 D 节预处理管线串联 |

---

## F：PP-OCRv6 — 三档模型 OCR（ONNX Runtime + GPU 加速）

PaddleOCR 最新 v6 模型家族，使用 ONNX Runtime + DirectML 本地推理。
默认 GPU 加速，Intel/AMD/NVIDIA GPU 均支持（需 ）。
三档可选：**Tiny (1.5MB) / Small (7.7MB) / Medium (34.5MB)**。

### 安装

创建虚拟环境并安装

python3 -m venv ~/.venvs/ppocrv6

~/.venvs/ppocrv6/bin/pip install onnxruntime opencv-python-headless numpy Pillow pdf2image

下载模型（从 GitHub Releases）

项目: https://github.com/andyhuo520/ppocrv6-studio

### CLI 命令

Tiny 模型（极速，1.5MB，可浏览器运行）

python scripts/pdf_ocr_v6.py input.jpg --tier tiny -o output.txt

Small 模型（均衡，7.7MB）

python scripts/pdf_ocr_v6.py input.jpg --tier small -o output.txt

Medium 模型（高精度，34.5MB）

python scripts/pdf_ocr_v6.py input.pdf --tier medium -o ./output

指定最低置信度

python scripts/pdf_ocr_v6.py input.jpg --tier medium --min-conf 0.6 -o output.txt

### 输出

output/

├── input.txt ← 纯文本（每页分段）

└── input.json ← 完整结果（含置信度、文本框坐标）

### 模型档位对比

| 档位 | 参数量 | 模型大小 | 适用场景 |
|------|--------|---------|---------|
| Tiny | 极轻量 | **1.5 MB** | 快速预览、可浏览器端运行 |
| Small | 轻量 | **7.7 MB** | 日常使用，性能均衡 |
| Medium | 标准 | **34.5 MB** | 高精度场景（合同/发票/复杂文档） |

### 文档类型建议

| 文档类型 | 推荐档位 | 理由 |
|---------|---------|------|
| 平整扫描件 | Tiny 或 Small | 速度优先，Tiny 效果已足够 |
| 手机拍照件 | Small | 平衡速度与准确率 |
| 复杂文档/小字 | **Medium** | 精度优先 |
| 批量处理 | Tiny | 优先速度 |

### 迁移说明

> PP-OCRv6 是比 PP-OCRv4 更轻量、效果更好的新一代模型。
> 默认 GPU 加速（DirectML），CPU 6-9x 提速。无 GPU 时自动回退 CPU。
> 旧版 PaddleOCR（PP-OCRv4）管线保留为备选。