references/full-guide.md
18.3 KB查看排版效果| 1 | --- |
| 2 | name: pdf-ocr-md |
| 3 | version: 3.3.0 |
| 4 | description: 当用户需要从 PDF、图片、扫描件中提取文字内容时使用。适合处理合同、发票、报告等文档,尤其是中文扫描件、手机拍照的弯曲页面、歪斜的文档。支持 PP-OCRv6 三档模型 (Tiny/Small/Medium)。 |
| 5 | related_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秒出) |
| 32 | lit parse input.pdf --no-ocr -o output.txt |
| 33 | |
| 34 | # ② 如果输出为空,说明是扫描件 |
| 35 | # 按需选模型档位(速度从快到慢:tiny > small > medium) |
| 36 | python scripts/pdf_ocr_v6.py input.pdf --tier tiny -o ./output |
| 37 | ``` |
| 38 | |
| 39 | ### 直接指定 |
| 40 | |
| 41 | ```bash |
| 42 | # 文本层PDF(电子合同/报表) |
| 43 | lit parse input.pdf --no-ocr -o output.txt |
| 44 | |
| 45 | # 中文扫描件(合同/发票)— 先预处理 |
| 46 | python scripts/pdf_preprocess.py input.pdf -o ./preprocessed --all |
| 47 | pdf2md ./preprocessed/input_p001.jpg -o ./output_dir |
| 48 | |
| 49 | # 或快速跳过预处理(平整的扫描件) |
| 50 | pdf2md 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 | # 安装 |
| 126 | python3 -m venv ~/.venvs/opendataloader |
| 127 | ~/.venvs/opendataloader/bin/pip install -i https://pypi.tuna.tsinghua.edu.cn/simple opendataloader-pdf |
| 128 | |
| 129 | # CLI |
| 130 | opendataloader-pdf input.pdf -f json,markdown -o ./output |
| 131 | |
| 132 | # Python |
| 133 | from opendataloader_pdf import convert |
| 134 | convert("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 | # 环境 |
| 158 | python3 -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 " |
| 163 | from paddleocr import PaddleOCR |
| 164 | ocr = PaddleOCR(lang='ch') |
| 165 | result = ocr.ocr('page.png') |
| 166 | for 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 | ``` |
| 198 | ModuleNotFoundError: 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""" |
| 208 | def whatfile(f): |
| 209 | return None |
| 210 | |
| 211 | def what(buf, h=None): |
| 212 | return None |
| 213 | ``` |
| 214 | |
| 215 | #### 问题2:np.sctypes 移除 |
| 216 | |
| 217 | **现象:** |
| 218 | ``` |
| 219 | AttributeError: 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 | # 修复后: |
| 233 | NP_FLOAT_TYPES = {np.float16, np.float32, np.float64} |
| 234 | NP_INT_TYPES = {np.int8, np.int16, np.int32, np.int64} |
| 235 | NP_UINT_TYPES = {np.uint8, np.uint16, np.uint32, np.uint64} |
| 236 | ``` |
| 237 | |
| 238 | #### 问题3:OpenCV 与 NumPy 2.x 不兼容 |
| 239 | |
| 240 | **现象:** |
| 241 | ``` |
| 242 | ImportError: 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 | ``` |
| 258 | ImportError: 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 | # 环境 |
| 272 | python3 -m venv ~/.venvs/paddleocr |
| 273 | source ~/.venvs/paddleocr/bin/activate |
| 274 | |
| 275 | # 安装(使用 PaddlePaddle 3.0.0,支持 NumPy 2.x) |
| 276 | pip install paddlepaddle==3.0.0 |
| 277 | pip install "numpy>=2" paddleocr==2.7.3 |
| 278 | pip uninstall opencv-python -y |
| 279 | pip install opencv-python-headless --no-cache-dir |
| 280 | |
| 281 | # 创建 imghdr shim |
| 282 | cat > ~/.venvs/paddleocr/lib/python3.13/site-packages/imghdr.py << 'EOF' |
| 283 | def whatfile(f): |
| 284 | return None |
| 285 | def what(buf, h=None): |
| 286 | return None |
| 287 | EOF |
| 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 | |
| 297 | LlamaIndex 出品(8k⭐),Rust 核心,轻量零依赖。 |
| 298 | |
| 299 | ### 安装 |
| 300 | |
| 301 | ```bash |
| 302 | # 已安装: ~/.venvs/liteparse/ + ~/.local/bin/lit |
| 303 | pip install liteparse # Python |
| 304 | npm i @llamaindex/liteparse # Node.js |
| 305 | cargo install liteparse # Rust CLI |
| 306 | ``` |
| 307 | |
| 308 | ### 核心命令 |
| 309 | |
| 310 | ```bash |
| 311 | # 文本层PDF → 文本(推荐 --no-ocr,跳过不必要的OCR) |
| 312 | lit parse input.pdf --no-ocr -o output.txt |
| 313 | |
| 314 | # 扫描件PDF → 文本(内置Tesseract,中文用 --ocr-language chi_sim) |
| 315 | lit parse input.pdf --ocr-language chi_sim -o output.txt |
| 316 | |
| 317 | # 批量处理 |
| 318 | lit batch-parse ./input-dir ./output-dir |
| 319 | |
| 320 | # 生成截图(用于LLM视觉分析) |
| 321 | lit 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 |
| 361 | pip install opencv-python-headless numpy Pillow pdf2image |
| 362 | ``` |
| 363 | |
| 364 | ### CLI 命令 |
| 365 | |
| 366 | ```bash |
| 367 | # 全部预处理(推荐) |
| 368 | python scripts/pdf_preprocess.py input.pdf -o ./preprocessed --all |
| 369 | |
| 370 | # 仅倾斜校正 |
| 371 | python scripts/pdf_preprocess.py input.jpg -o ./output --deskew |
| 372 | |
| 373 | # 仅方向校正 |
| 374 | python scripts/pdf_preprocess.py input.jpg -o ./output --orient |
| 375 | |
| 376 | # 仅文档展平(弯曲/透视照片) |
| 377 | python scripts/pdf_preprocess.py input.jpg -o ./output --unwarp |
| 378 | |
| 379 | # PDF 全页 + 高DPI |
| 380 | python scripts/pdf_preprocess.py input.pdf -o ./preprocessed --all --dpi 400 |
| 381 | |
| 382 | # 预览模式(显示对比图,不保存) |
| 383 | python 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 |
| 398 | python scripts/pdf_preprocess.py input.pdf -o ./preprocessed --all |
| 399 | pdf2md ./preprocessed/input_p001.jpg -o ./output_dir |
| 400 | |
| 401 | # 对于平整扫描件, 预处理效果不大, 可跳过 |
| 402 | pdf2md 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 |
| 420 | from scripts.pdf_preprocess import preprocess_image, deskew_image, unwarp_image |
| 421 | import cv2 |
| 422 | |
| 423 | img = cv2.imread('scan.jpg') |
| 424 | processed = preprocess_image(img, deskew=True, orient=True, unwarp=True) |
| 425 | cv2.imwrite('corrected.jpg', processed) |
| 426 | |
| 427 | --- |
| 428 | |
| 429 | ## E:结构化文档解析 — 版面分析 + 表格提取 |
| 430 | |
| 431 | 利用 docling 进行深度版面分析, 输出结构化 Markdown 和 JSON。 |
| 432 | 保留文档的标题层级、表格、列表、图片标注等逻辑结构。 |
| 433 | |
| 434 | ### 安装 |
| 435 | |
| 436 | ```bash |
| 437 | pip install docling |
| 438 | # docling 2.97+ 会自动安装版面分析模型 |
| 439 | ``` |
| 440 | |
| 441 | ### CLI 命令 |
| 442 | |
| 443 | ```bash |
| 444 | # 结构化解析为 Markdown + JSON |
| 445 | python scripts/pdf_parse_structured.py input.pdf -o ./output |
| 446 | |
| 447 | # 禁用 OCR (文本层 PDF, 更快) |
| 448 | python scripts/pdf_parse_structured.py input.pdf -o ./output --no-ocr |
| 449 | |
| 450 | # 仅输出 Markdown |
| 451 | python scripts/pdf_parse_structured.py input.pdf -o ./output --md-only |
| 452 | |
| 453 | # 仅输出 JSON (含完整版面坐标) |
| 454 | python scripts/pdf_parse_structured.py input.pdf -o ./output --json-only |
| 455 | |
| 456 | # 仅前3页 |
| 457 | python scripts/pdf_parse_structured.py input.pdf -o ./output --pages "1-3" |
| 458 | ``` |
| 459 | |
| 460 | ### 输出说明 |
| 461 | |
| 462 | ``` |
| 463 | output/ |
| 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 | # 完整管线: 预处理 → 结构化解析 |
| 496 | python scripts/pdf_preprocess.py input.pdf -o ./preprocessed --all |
| 497 | python scripts/pdf_parse_structured.py ./preprocessed/input_p001.jpg -o ./output |
| 498 | |
| 499 | # 也可直接解析 |
| 500 | python 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 | |
| 518 | PaddleOCR 最新 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 | # 创建虚拟环境并安装 |
| 526 | python3 -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,可浏览器运行) |
| 537 | python scripts/pdf_ocr_v6.py input.jpg --tier tiny -o output.txt |
| 538 | |
| 539 | # Small 模型(均衡,7.7MB) |
| 540 | python scripts/pdf_ocr_v6.py input.jpg --tier small -o output.txt |
| 541 | |
| 542 | # Medium 模型(高精度,34.5MB) |
| 543 | python scripts/pdf_ocr_v6.py input.pdf --tier medium -o ./output |
| 544 | |
| 545 | # 指定最低置信度 |
| 546 | python scripts/pdf_ocr_v6.py input.jpg --tier medium --min-conf 0.6 -o output.txt |
| 547 | ``` |
| 548 | |
| 549 | ### 输出 |
| 550 | |
| 551 | ``` |
| 552 | output/ |
| 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 | ``` |
文件内容是平台检查时读出的文本,只供查看。平台不会运行包里的任何脚本或程序。

