SKILL.md
pdf-ocr-md — PDF → OCR → 结构化 Markdown [v3.4.0]#
v3.4.0：SKILL.md 精简至 ~120 行（原 578 行），详细教程移至 references/，按需加载。对标 OpenAI 上下文压缩策略。
环境#
| 工具 | 用途 | 虚拟环境 |
|---|---|---|
lit | 文本层 PDF 快速解析（Rust，~0.9ms/页） | ~/.venvs/liteparse/ |
ocr6 | PP-OCRv6 三档 OCR | ~/.venvs/ppocrv6/ |
pdf2md | PaddleOCR 中文扫描件（旧版 v4） | ~/.venvs/paddleocr/ |
prep | 文档预处理（倾斜/方向/展平） | (同 ocr6) |
快速选择（必读）#
# ① 先试 LiteParse（文本层 PDF 秒出）
lit parse input.pdf --no-ocr -o output.txt
# ② 空结果 = 扫描件，按需选模型档位
# tiny(1.5MB 极速) | small(7.7MB 均衡) | medium(34.5MB 高精度)
python scripts/pdf_ocr_v6.py input.pdf --tier small -o ./output
# ③ 低质量文档先预处理（deskew倾斜/orient方向/unwarp展平/--all全部）
python scripts/pdf_preprocess.py input.pdf -o ./preprocessed --all
python scripts/pdf_ocr_v6.py ./preprocessed/input_p001.jpg --tier medium -o ./output工作流#
输入文档
├── 有文本层 → lit parse --no-ocr（0.9ms/页）
└── 扫描件 → 先预处理(倾斜/方向/展平) → ocr6(tiny|small|medium)
性能速查#
| 类型 | 引擎 | 单页 | 17 页合同 |
|---|---|---|---|
| 文本层 PDF | LiteParse | ~0.9ms | ~15ms |
| 扫描件(极速) | PP-OCRv6 Tiny | ~3-8s | ~1-2min |
| 扫描件(均衡) | PP-OCRv6 Small | ~8-15s | ~2-4min |
| 扫描件(高精度) | PP-OCRv6 Medium | ~15-30s | ~4-8min |
| 中文旧版 | PaddleOCR v4 | ~15s | ~4.5min |
准确率：PP-OCRv6 ~97%+，预处理后 ~98%+。公章/签名场景必须用 PaddleOCR（Tesseract 会乱码）。
按需加载的参考文档#
所有详细教程已移至 references/，需要时读取：
| 场景 | 参考文件 |
|---|---|
| LiteParse 完整用法（Rust CLI/截图/批量） | references/liteparse-usage.md |
| PaddleOCR 旧版（v4，Python 3.13 兼容修复） | references/paddleocr.md + references/paddleocr-py313-compat.md |
| 文档预处理详解（倾斜/方向/展平/效果预测） | references/pdf-preprocessing.md |
| 结构化解析（版面分析+表格提取+JSON） | references/structured-parsing.md |
| PP-OCRv6 完整指南（模型选择/GPU加速/迁移） | references/ppocrv6-guide.md |
| 完整原版 SKILL.md（v3.3.0 全部内容） | references/full-guide.md |
| OpenDataLoader（纯 Java，已不推荐） | references/opendataloader.md |
注意事项#
- 首次运行自动下载模型（~17MB，从 hf-mirror/modelscope 国内镜像）
- 机器 3.6GB 内存，PaddleOCR 冷启动 ~300MB 峰值可承受
- 预处理对平整扫描件效果不明显，对手机拍照/弯曲文档提升 1~5%
用途与依赖
作者没写，这些是平台读文件后整理的，以文件为准。
使用示例
请求：帮我把这份扫描的合同 PDF 转成文字，有几页是手机拍的，有点歪。
预期
先尝试用 lit parse --no-ocr 读取文本层，若为空则判定为扫描件；随后运行 pdf_preprocess.py --all 做方向校正、透视展平和倾斜校正，再用 pdf_ocr_v6.py --tier small（或 medium）逐页 OCR，最后输出每页分段的纯文本和含置信度、文本框坐标的 JSON，并报告识别到的文本块数量和平均置信度。
- 适用场景
- 从电子合同、报表等有文本层的 PDF 中快速提取文字
- 识别中文扫描件（合同、发票、报告）中的文字
- 处理手机拍照、页面弯曲或歪斜的文档，先校正再 OCR
- 把扫描件 PDF 转成 Markdown 或带文本框坐标的 JSON
- 提取文档中的表格并转成 Markdown 表格
- 识别倒置或侧向的页面并自动转正
- 按速度或精度需求选择 OCR 模型档位（极速/均衡/高精度）
- 对文档做版面分析，保留标题、段落、列表等结构
- 输入
- 要处理的 PDF 或图片文件路径
- 是否需要预处理（倾斜/方向/展平）及文档状况
- OCR 模型档位选择（tiny/small/medium）
- 是否需要结构化输出（Markdown/JSON）及是否提取表格
- 页码范围（可选，如 1-5,10）
- 最低置信度阈值（可选）
- PDF 转图片的 DPI（可选，默认 300）
- 输出
- 纯文本文件（按页分段）
- 含置信度和文本框坐标的 JSON 结果
- 结构化 Markdown（标题层级、列表、表格）
- 含版面坐标和表格网格的 JSON
- 预处理后的图片文件
- 识别统计（文本块数量、平均置信度、耗时）
- 运行环境
- Python 3；另需 Bash 运行 .sh 包装脚本；LiteParse 为 Rust CLI
- 依赖
- onnxruntime（GPU 加速需 onnxruntime-directml，Apple Silicon 可用 onnxruntime-silicon）
- opencv-python-headless
- numpy
- Pillow
- pdf2image（PDF 转图片，另需系统安装 poppler）
- liteparse（提供 lit 命令）
- paddlepaddle 与 paddleocr（旧版中文 OCR 管线）
- docling（结构化版面分析与表格提取）
- opendataloader-pdf（可选，需 Java 11+）
- tesseract-ocr-chi-sim（LiteParse 中文 OCR 语言包，可选）
