跳到主要内容

PDF识别提取专家

收藏0

PDF/图片/扫描件 OCR 提取文字转 Markdown。支持 PP-OCRv6 三档模型,适合合同、发票、中文扫描件等。灵栈搬运自 SkillHub pdf-ocr-md v3.4.0。

让 AI 安装

Minsaroun最新版本 0.1.0更新于 2026-11-04下载 0 次

references/full-guide.md

18.3 KB查看排版效果
1---
2name: pdf-ocr-md
3version: 3.3.0
4description: 当用户需要从 PDF、图片、扫描件中提取文字内容时使用。适合处理合同、发票、报告等文档,尤其是中文扫描件、手机拍照的弯曲页面、歪斜的文档。支持 PP-OCRv6 三档模型 (Tiny/Small/Medium)。
5related_skills:
6 - ocr-and-documents
7---
8
9# pdf-ocr-md — PDF → OCR → 结构化 Markdown
10
11> **环境**:
12> - `lit` — LiteParse 快速文本层解析(`~/.venvs/liteparse/`,Rust 核心)
13> - `pdf2md` — PaddleOCR 中文扫描件(`~/.venvs/paddleocr/`)
14> - `ocr6` — **PP-OCRv6** 三档模型(`~/.venvs/ppocrv6/`,ONNX Runtime),见 F 节
15> - `prep` — 文档预处理(含倾斜/方向/展平),见 D 节
16>
17> **快速选择**:不确定类型 → `lit parse file.pdf --no-ocr`,空结果再退到 `prep` + `ocr6`
18>
19> **曾用名**:`pdf2md`(因 SkillHub/ClawHub 已被占用,v1.1.0 起更名)
20>
21> **一体化 skill**:合并了原 `opendataloader-pdf`、`paddleocr-chinese` 和 `pdf-ocr-md`。
22> 详见 `references/opendataloader.md` 和 `references/paddleocr.md`。
23
24---
25
26## 用法
27
28### 快速选择(推荐)
29
30```bash
31# ① 先试试 LiteParse(文本层PDF秒出)
32lit parse input.pdf --no-ocr -o output.txt
33
34# ② 如果输出为空,说明是扫描件
35# 按需选模型档位(速度从快到慢:tiny > small > medium)
36python scripts/pdf_ocr_v6.py input.pdf --tier tiny -o ./output
37```
38
39### 直接指定
40
41```bash
42# 文本层PDF(电子合同/报表)
43lit parse input.pdf --no-ocr -o output.txt
44
45# 中文扫描件(合同/发票)— 先预处理
46python scripts/pdf_preprocess.py input.pdf -o ./preprocessed --all
47pdf2md ./preprocessed/input_p001.jpg -o ./output_dir
48
49# 或快速跳过预处理(平整的扫描件)
50pdf2md input.pdf -o ./output_dir
51```
52
53输出:
54- LiteParse: `output.txt` — 纯文本(版面保持)
55- pdf2md: `output_dir/input.md` — Markdown + `input.json` + `input_images/`
56- 预处理: `preprocessed/` — 经过校正/展平的图片
57
58## 工作流总览
59
60```
61输入文档
62 ├── 有文本层 → LiteParse 提取 (~0.9ms/页)
63 │
64 └── 无文本层(扫描件)
65 ├── ① 选择模型档位
66 │ ├── Tiny (1.5 MB) 极速
67 │ ├── Small (7.7 MB) 均衡
68 │ └── Medium(34.5 MB) 高精度
69 │
70 ├── ② 预处理(根据文档状况)
71 │ ├── --deskew 倾斜校正
72 │ ├── --orient 方向校正
73 │ ├── --unwarp 文档展平
74 │ └── --all 全部
75 │
76 └── ③ PP-OCRv6 OCR → 文本 / JSON
77```
78> **LiteParse 比 OpenDataLoader 快约 300 倍**(0.9ms vs 300ms),且不用装 Java 11。
79
80## 性能参考(CPU)
81
82| 类型 | 引擎 | 单页耗时 | 17页合同 |
83|------|------|---------|----------|
84| 文本层 PDF | LiteParse --no-ocr | **~0.9ms** | **~15ms** |
85| 文本层 PDF | OpenDataLoader(旧) | ~15ms | ~300ms |
86| **PP-OCRv6 Tiny** | ONNX Runtime (CPU) | **~3-8s** | **~1-2min** |
87| **PP-OCRv6 Small** | ONNX Runtime (CPU) | **~8-15s** | **~2-4min** |
88| **PP-OCRv6 Medium** | ONNX Runtime (CPU) | **~15-30s** | **~4-8min** |
89| **预处理-倾斜校正** | OpenCV Hough | **~300ms** | **~5s** |
90| **预处理-文档展平** | OpenCV 透视变换 | **~500ms** | **~8s** |
91| 扫描件(中文) | PaddleOCR PP-OCRv4(旧) | ~15s | ~4.5min |
92| 扫描件(中文) | Tesseract chi_sim | ~170ms | ~3s |
93| 扫描件(英文) | LiteParse 默认 | ~170ms | ~3s |
94
95## 准确率
96
97| 引擎 | 中文扫描件 |
98|------|-----------|
99| PP-OCRv6 Medium | **~0.425 ed** (OmniDocBench) |
100| PP-OCRv6 Small | **~0.443 ed** |
101| PP-OCRv6 Tiny | **~0.446 ed** |
102| Apple Vision (macOS) | ~0.448 ed |
103| PaddleOCR PP-OCRv4 | **~97%+** |
104| + 预处理 | **~98%+** (歪斜/弯曲照片) |
105
106## 注意事项
107
108- 首次运行自动下载模型(版面分析 ~770 weights + OCR det/cls/rec ~17MB)
109- 模型从 hf-mirror.com / modelscope.cn 下载,国内畅通
110- 机器有 3.6GB 内存,PaddleOCR 冷启动 ~300MB 峰值可承受
111- 中文 OCR 场景:**LiteParse(Tesseract) ~80% → 退到 PaddleOCR ~97%+**,准确率优先时用 `pdf2md`
112- 英文 / Office 文档场景可优先试 LiteParse(见 C 节)
113- **预处理能提升照片/弯曲文档的 OCR 准确率 1~5%**,对平整扫描件效果不明显
114- **结构化解析**(doc-parsing)会额外增加版面分析时间, 但输出更结构化
115
116---
117
118## A:OpenDataLoader — 文本层 PDF 解析
119
120适用于有文本层的 PDF(电子合同、报表、PDF/A 文件)。支持的 CLI 和 Python SDK,完整用法详见 `references/opendataloader.md`。
121
122### 快速启动
123
124```bash
125# 安装
126python3 -m venv ~/.venvs/opendataloader
127~/.venvs/opendataloader/bin/pip install -i https://pypi.tuna.tsinghua.edu.cn/simple opendataloader-pdf
128
129# CLI
130opendataloader-pdf input.pdf -f json,markdown -o ./output
131
132# Python
133from opendataloader_pdf import convert
134convert("input.pdf", output_dir="./out", format="json,markdown")
135```
136
137### 关键特性
138- **输出格式**:JSON(含 bounding box/font/size)、Markdown、HTML、Text、Tagged PDF
139- **表格检测**:`--table-method cluster` 模式
140- **脱敏**:`--sanitize` 替换邮箱/电话/银行卡号
141- **页码范围**:`--pages "1,3,5-7"` 指定页
142- **性能**:~0.015s/页(纯 Java 本地模式,无网络)
143
144### 环境前提
145- Java 11+ (`java -version`)
146- PyPI 官方源可能超时 → 用清华镜像 `-i https://pypi.tuna.tsinghua.edu.cn/simple`
147
148---
149
150## B:PaddleOCR — 中文扫描件 OCR
151
152适用于无文本层的扫描件 PDF(合同、发票、报纸)。详见 `references/paddleocr.md`。
153
154### 快速启动
155
156```bash
157# 环境
158python3 -m venv ~/.venvs/paddleocr
159~/.venvs/paddleocr/bin/pip install paddlepaddle==2.6.2 "numpy<2" paddleocr==2.7.3
160
161# CLI —— 逐张 OCR 图片
162~/.venvs/paddleocr/bin/python -c "
163from paddleocr import PaddleOCR
164ocr = PaddleOCR(lang='ch')
165result = ocr.ocr('page.png')
166for line_info in result[0]:
167 text = line_info[1][0]; conf = line_info[1][1]
168 print(f'{conf:.2f} {text}')
169"
170```
171
172### 关键特性
173- PP-OCRv4 模型,简体中文 ~98%,繁体 ~95%
174- 支持竖排文字、手写体
175- 公章/签名基本可识别(Tesseract 在此场景乱码)
176- 可配合 `pdf2image` 拆分扫描件 PDF
177
178### 精度对比
179
180| 引擎 | 简体中文 | 繁体中文 | 公章/签名 | 竖排 |
181|------|---------|---------|-----------|------|
182| Tesseract chi_sim | ~80% | ~60% | ❌ 乱码 | ❌ |
183| **PaddleOCR PP-OCRv4** | **~98%** | **~95%** | ✅ 基本正确 | ✅ |
184
185### 常见问题
186- **错字多**:提高 DPI 到 400-600,降低过滤阈值到 0.3
187- **表格差**:对密集表格用 docling(pdf2md 集成管线)
188- **GPU 加速**:`pip install paddlepaddle-gpu==2.6.2` + `use_gpu=True`
189
190### Python 3.13 兼容性注意事项
191
192> ⚠️ **重要**:PaddleOCR 在 Python 3.13 环境下存在多个兼容性问题,需手动修复。
193
194#### 问题1:imghdr 模块缺失
195
196**现象:**
197```
198ModuleNotFoundError: No module named 'imghdr'
199```
200
201**原因:** Python 3.13 移除了 `imghdr` 模块(原用于检测图像类型)
202
203**解决方案:** 创建兼容 shim 模块
204
205```python
206# 保存到 site-packages/imghdr.py
207"""imghdr module shim for Python 3.13+ compatibility"""
208def whatfile(f):
209 return None
210
211def what(buf, h=None):
212 return None
213```
214
215#### 问题2:np.sctypes 移除
216
217**现象:**
218```
219AttributeError: module 'numpy' has no attribute 'sctypes'
220```
221
222**原因:** NumPy 2.0 移除了 `np.sctypees` 属性(`imgaug` 包使用了该属性)
223
224**解决方案:** 修改 `site-packages/imgaug/imgaug.py` 第44-46行
225
226```python
227# 原代码(不可用):
228# NP_FLOAT_TYPES = set(np.sctypes["float"])
229# NP_INT_TYPES = set(np.sctypes["int"])
230# NP_UINT_TYPES = set(np.sctypes["uint"])
231
232# 修复后:
233NP_FLOAT_TYPES = {np.float16, np.float32, np.float64}
234NP_INT_TYPES = {np.int8, np.int16, np.int32, np.int64}
235NP_UINT_TYPES = {np.uint8, np.uint16, np.uint32, np.uint64}
236```
237
238#### 问题3:OpenCV 与 NumPy 2.x 不兼容
239
240**现象:**
241```
242ImportError: numpy.core.multiarray failed to import
243```
244
245**原因:** `opencv-python` 4.6 是针对 NumPy 1.x 编译的,与 NumPy 2.x ABI 不兼容
246
247**解决方案:** 改用 `opencv-python-headless` 4.13.0.92+
248
249```bash
250~/.venvs/paddleocr/bin/pip uninstall opencv-python -y
251~/.venvs/paddleocr/bin/pip install opencv-python-headless --no-cache-dir
252```
253
254#### 问题4:scikit-image DLL 加载失败(Windows)
255
256**现象:**
257```
258ImportError: DLL load failed while importing _cython_blas
259```
260
261**原因:** Windows 安全策略阻止未签名的 C 扩展 DLL
262
263**解决方案:**
264- 方案A:使用预编译的 wheel(推荐)
265- 方案B:临时关闭 Windows Defender 实时保护
266- 方案C:使用 WSL2 或 Linux 环境
267
268#### 推荐的 Python 3.13 安装命令
269
270```bash
271# 环境
272python3 -m venv ~/.venvs/paddleocr
273source ~/.venvs/paddleocr/bin/activate
274
275# 安装(使用 PaddlePaddle 3.0.0,支持 NumPy 2.x)
276pip install paddlepaddle==3.0.0
277pip install "numpy>=2" paddleocr==2.7.3
278pip uninstall opencv-python -y
279pip install opencv-python-headless --no-cache-dir
280
281# 创建 imghdr shim
282cat > ~/.venvs/paddleocr/lib/python3.13/site-packages/imghdr.py << 'EOF'
283def whatfile(f):
284 return None
285def what(buf, h=None):
286 return None
287EOF
288
289# 修补 np.sctypes 问题
290# 手动编辑 ~/.venvs/paddleocr/lib/python3.13/site-packages/imgaug/imgaug.py
291```
292
293---
294
295## C:LiteParse — 文本层 PDF 快速解析(Rust)
296
297LlamaIndex 出品(8k⭐),Rust 核心,轻量零依赖。
298
299### 安装
300
301```bash
302# 已安装: ~/.venvs/liteparse/ + ~/.local/bin/lit
303pip install liteparse # Python
304npm i @llamaindex/liteparse # Node.js
305cargo install liteparse # Rust CLI
306```
307
308### 核心命令
309
310```bash
311# 文本层PDF → 文本(推荐 --no-ocr,跳过不必要的OCR)
312lit parse input.pdf --no-ocr -o output.txt
313
314# 扫描件PDF → 文本(内置Tesseract,中文用 --ocr-language chi_sim)
315lit parse input.pdf --ocr-language chi_sim -o output.txt
316
317# 批量处理
318lit batch-parse ./input-dir ./output-dir
319
320# 生成截图(用于LLM视觉分析)
321lit screenshot input.pdf -o ./screenshots --dpi 200
322```
323
324### 关键特性
325
326| 特性 | 说明 |
327|------|------|
328| 文本层提取 | PDFium,**0.9ms/页**,比 OpenDataLoader 快 300x |
329| 多格式输入 | PDF / 图片(PNG/JPG) |
330| OCR 引擎 | 内置 Tesseract;可接 HTTP OCR server(PaddleOCR/自定义) |
331| 输出格式 | 纯文本 / JSON(含 bounding box) |
332| 截图输出 | `lit screenshot` 生成整页 PNG(支持 --target-pages) |
333| 语言绑定 | Python / Node.js / Rust CLI / WASM |
334| 平台 | Linux / macOS / Windows |
335| License | Apache 2.0 |
336
337### 局限
338
339| 局限 | 说明 | 替代方案 |
340|------|------|---------|
341| 中文 OCR 准确率差 | Tesseract chi_sim ~80% vs PaddleOCR ~97% | 退到 `pdf2md`(见 B 节) |
342| Office 文档 | DOCX/XLSX/PPTX 需 LibreOffice 转换 | 暂不支持,需时再装 |
343| 表格识别 | 无版面分析,纯坐标提取 | 退到 `pdf2md`(docling 版面分析) |
344
345### 机器资源
346
347- 内存:LiteParse 进程 ~50MB(含 Tesseract 模型)
348- 磁盘:`~/.venvs/liteparse/` ~35MB + tessdata ~15MB
349- 安装:`pip install liteparse` 一行即可
350
351---
352
353## D:文档预处理 — 扫描件 OCR 增强
354
355适用于质量不佳的扫描件(手机拍照、弯曲书页、倾斜/倒置的文档)。
356预处理后 PaddleOCR 的中文准确率可从 ~97% 提升到 ~98%+。
357
358### 安装
359
360```bash
361pip install opencv-python-headless numpy Pillow pdf2image
362```
363
364### CLI 命令
365
366```bash
367# 全部预处理(推荐)
368python scripts/pdf_preprocess.py input.pdf -o ./preprocessed --all
369
370# 仅倾斜校正
371python scripts/pdf_preprocess.py input.jpg -o ./output --deskew
372
373# 仅方向校正
374python scripts/pdf_preprocess.py input.jpg -o ./output --orient
375
376# 仅文档展平(弯曲/透视照片)
377python scripts/pdf_preprocess.py input.jpg -o ./output --unwarp
378
379# PDF 全页 + 高DPI
380python scripts/pdf_preprocess.py input.pdf -o ./preprocessed --all --dpi 400
381
382# 预览模式(显示对比图,不保存)
383python scripts/pdf_preprocess.py input.jpg --preview --all
384```
385
386### 预处理项说明
387
388| 预处理 | CLI 参数 | 适用场景 | 效果 |
389|--------|---------|---------|------|
390| **倾斜校正** (deskew) | `--deskew` | 扫描件轻微歪斜 (<15°) | 自动检测角度并旋转正位 |
391| **方向校正** (orient) | `--orient` | 页面旋转/倒置 | 检测文本方向并自动旋转到正位 |
392| **文档展平** (unwarp) | `--unwarp` | 手机拍的弯曲/透视变形的文档 | 自动检测边界, 透视变换展平 |
393
394### 工作流集成
395
396```bash
397# 完整管线: 预处理 → pdf2md
398python scripts/pdf_preprocess.py input.pdf -o ./preprocessed --all
399pdf2md ./preprocessed/input_p001.jpg -o ./output_dir
400
401# 对于平整扫描件, 预处理效果不大, 可跳过
402pdf2md input.pdf -o ./output_dir
403```
404
405### 预处理效果预测
406
407| 文档类型 | 建议 | 预期提升 |
408|---------|------|---------|
409| 平整扫描件 (A4 扫描仪) | 跳过预处理 | OCR 已很好, 无明显提升 |
410| 轻微歪斜 (< 15°) | `--deskew` | 准确率 +1~2% |
411| 照片 (手机拍文档) | `--deskew --unwarp` | 准确率 +3~5% |
412| 页面倒置/旋转 | `--orient` | 从乱码到正常识别 |
413| 弯曲书页 | `--unwarp` | 准确率 +2~4% |
414
415### 脚本参考
416
417预处理脚本位于 `scripts/pdf_preprocess.py`,支持作为 Python 模块导入使用:
418
419```python
420from scripts.pdf_preprocess import preprocess_image, deskew_image, unwarp_image
421import cv2
422
423img = cv2.imread('scan.jpg')
424processed = preprocess_image(img, deskew=True, orient=True, unwarp=True)
425cv2.imwrite('corrected.jpg', processed)
426
427---
428
429## E:结构化文档解析 — 版面分析 + 表格提取
430
431利用 docling 进行深度版面分析, 输出结构化 Markdown 和 JSON。
432保留文档的标题层级、表格、列表、图片标注等逻辑结构。
433
434### 安装
435
436```bash
437pip install docling
438# docling 2.97+ 会自动安装版面分析模型
439```
440
441### CLI 命令
442
443```bash
444# 结构化解析为 Markdown + JSON
445python scripts/pdf_parse_structured.py input.pdf -o ./output
446
447# 禁用 OCR (文本层 PDF, 更快)
448python scripts/pdf_parse_structured.py input.pdf -o ./output --no-ocr
449
450# 仅输出 Markdown
451python scripts/pdf_parse_structured.py input.pdf -o ./output --md-only
452
453# 仅输出 JSON (含完整版面坐标)
454python scripts/pdf_parse_structured.py input.pdf -o ./output --json-only
455
456# 仅前3页
457python scripts/pdf_parse_structured.py input.pdf -o ./output --pages "1-3"
458```
459
460### 输出说明
461
462```
463output/
464├── input.md ← 结构化 Markdown (标题层级/表格/列表)
465└── input.json ← 完整解析结果 (含版面坐标、表格网格、元数据)
466```
467
468### JSON 数据结构
469
470```json
471{
472 "metadata": {
473 "file": "合同.pdf",
474 "pages": 17,
475 "has_ocr": true
476 },
477 "items": [
478 { "type": "heading", "text": "第一章 总则", "bbox": {...} },
479 { "type": "paragraph", "text": "根据《中华人民共和国...", "bbox": {...} },
480 { "type": "list", "text": "甲乙双方应遵守..." }
481 ],
482 "tables": [
483 {
484 "page": 3,
485 "grid": [["项目", "金额"], ["服务费", "10000"]],
486 "markdown": "| 项目 | 金额 |\n| --- | --- |\n| 服务费 | 10000 |"
487 }
488 ]
489}
490```
491
492### 工作流集成
493
494```bash
495# 完整管线: 预处理 → 结构化解析
496python scripts/pdf_preprocess.py input.pdf -o ./preprocessed --all
497python scripts/pdf_parse_structured.py ./preprocessed/input_p001.jpg -o ./output
498
499# 也可直接解析
500python scripts/pdf_parse_structured.py input.pdf -o ./output
501```
502
503### 关键特性
504
505| 特性 | 说明 |
506|------|------|
507| 版面分析 | docling 深度学习版面分析, 识别标题/段落/表格/列表 |
508| 表格提取 | 自动检测表格边界, 输出 Markdown 表格 + JSON 网格 |
509| 标题层级 | 保留文档逻辑结构 |
510| 元数据 | 页数、页码、元素统计 |
511| 结构化 JSON | 含 bbox 坐标, 可用于后续处理 |
512| 预处理兼容 | 可与 D 节预处理管线串联 |
513
514---
515
516## F:PP-OCRv6 — 三档模型 OCR(ONNX Runtime + GPU 加速)
517
518PaddleOCR 最新 v6 模型家族,使用 ONNX Runtime + DirectML 本地推理。
519默认 GPU 加速,Intel/AMD/NVIDIA GPU 均支持(需 )。
520三档可选:**Tiny (1.5MB) / Small (7.7MB) / Medium (34.5MB)**。
521
522### 安装
523
524```bash
525# 创建虚拟环境并安装
526python3 -m venv ~/.venvs/ppocrv6
527~/.venvs/ppocrv6/bin/pip install onnxruntime opencv-python-headless numpy Pillow pdf2image
528
529# 下载模型(从 GitHub Releases)
530# 项目: https://github.com/andyhuo520/ppocrv6-studio
531```
532
533### CLI 命令
534
535```bash
536# Tiny 模型(极速,1.5MB,可浏览器运行)
537python scripts/pdf_ocr_v6.py input.jpg --tier tiny -o output.txt
538
539# Small 模型(均衡,7.7MB)
540python scripts/pdf_ocr_v6.py input.jpg --tier small -o output.txt
541
542# Medium 模型(高精度,34.5MB)
543python scripts/pdf_ocr_v6.py input.pdf --tier medium -o ./output
544
545# 指定最低置信度
546python scripts/pdf_ocr_v6.py input.jpg --tier medium --min-conf 0.6 -o output.txt
547```
548
549### 输出
550
551```
552output/
553├── input.txt ← 纯文本(每页分段)
554└── input.json ← 完整结果(含置信度、文本框坐标)
555```
556
557### 模型档位对比
558
559| 档位 | 参数量 | 模型大小 | 适用场景 |
560|------|--------|---------|---------|
561| Tiny | 极轻量 | **1.5 MB** | 快速预览、可浏览器端运行 |
562| Small | 轻量 | **7.7 MB** | 日常使用,性能均衡 |
563| Medium | 标准 | **34.5 MB** | 高精度场景(合同/发票/复杂文档) |
564
565### 文档类型建议
566
567| 文档类型 | 推荐档位 | 理由 |
568|---------|---------|------|
569| 平整扫描件 | Tiny 或 Small | 速度优先,Tiny 效果已足够 |
570| 手机拍照件 | Small | 平衡速度与准确率 |
571| 复杂文档/小字 | **Medium** | 精度优先 |
572| 批量处理 | Tiny | 优先速度 |
573
574### 迁移说明
575
576> PP-OCRv6 是比 PP-OCRv4 更轻量、效果更好的新一代模型。
577> 默认 GPU 加速(DirectML),CPU 6-9x 提速。无 GPU 时自动回退 CPU。
578> 旧版 PaddleOCR(PP-OCRv4)管线保留为备选。
579```

文件内容是平台检查时读出的文本,只供查看。平台不会运行包里的任何脚本或程序。