Agent Skill

PDF与图片文字提取专家

当用户需要从 PDF、图片、扫描件中提取文字内容时使用。适合处理合同、发票、报告等文档,尤其是中文扫描件、手机拍照的弯曲页面、歪斜的文档。 最新版特点:支持 PP-OCRv6 三档模型 (Tiny/Small/Medium) 和文本层 PDF 极速提取 (LiteParse ~0.9ms/页),并内置文档预处理管线(倾斜校正/方向校正/文档展平)和结构化解析(版面分析/表格提取)。 支持 PP-OCRv6 三档模型 (Tiny/Small/Medium) 和文本层 PDF 极速提取 (LiteParse ~0.9ms/页),并内置文档预处理管线(倾斜校正/方向校正/文档展平)和结构化解析(版面分析/表格提取)。

办公效率·托懂·来自 skill_hub·skillhub.cn ↗
skillhub install @user_779b44c7/pdf-ocr-md
32 Stars·8.4万 综合热度·6,680 字文档·源站更新 2026-11-22

README 文档

6,680 字

pdf-ocr-md — PDF → OCR → 结构化 Markdown [v3.5.1]

版本记录

  • v3.5.1 (2026-11-18):修正外部机器反馈的两类文档缺陷——环境表改为描述「标准安装后应有的状态」(删单机磁盘快照断言,补探测列与「路径非唯一解」声明);T6 判据重写(原「不存在+⚠️ 即 PASS」等于永不失败,现 5 条独立检查,负向用例 5/5 命中);回退顺序全文统一为 modelscope → hf-mirror → GitHub(以脚本实际为准)
  • v3.5.0 (2026-11-18):合并外部机器的完整可用性验证结论(19 项问题清单)——修复依赖检测粒度、输出路径语义歧义、--device 默认值、PDF 渲染后端、字符字典未初始化崩溃、Windows 中文路径读图失败;补齐 scripts/downloadmodels.sh、scripts/pdf2md.py 与 tests/smoketest.py;明确「扫描件判定规则」与「关键字段必须走 PaddleOCR」硬约束;模型体积与性能数据按实测校准
  • v3.4.2 (2026-09-14):环境表补齐各工具的标准位置与探测方法(此前只写单台机器的磁盘快照,易误导其他使用者)
  • v3.4.1 (2026-08-05):修复 PP-OCRv6 字典错位 bug(乱字符→正确识别);补齐 poppler/ImageMagick 依赖
  • v3.4.0:SKILL.md 精简至 ~120 行(原 578 行),详细教程移至 references/,按需加载。

环境

本节描述「标准安装后应有的状态」,不是任何一台机器的磁盘快照。 各机安装路径不同属正常——按「探测」列定位自己的环境,不要照抄别人机器的绝对路径,更不要因某个路径在本机不存在就认为它本不该存在。

工具用途标准位置(应存在)探测命令(找不到时用它定位)
lit文本层 PDF 快速解析(Rust)随 Python 装出,在 Scripts/lit(Windows)或 bin/lit(POSIX)where lit / which lit;无则 pip show liteparse
ocr6PP-OCRv6 三档 OCR(快速全文预览)模型在 ~/.workbuddy/.venvs/ppocrv6_models/;推理环境为任意装了 onnxruntime+cv2 的 venvbash scripts/download_models.sh --check all 验模型;python -c "import onnxruntime" 验环境
pdf2mdPaddleOCR v4 关键字段通道venv 在 ~/.venvs/paddleocr/(或自建同名 venv)python -c "import paddle, paddleocr" 验环境
prep文档预处理(倾斜/方向/展平)同 ocr6(共用 cv2/numpy)python -c "import cv2, numpy"

两个 venv 路径不是唯一解:~/.venvs/liteparse/、~/.venvs/ppocrv6/ 只是常见约定路径;PP-OCRv6 推理环境在本技能的实现中落在 ~/.workbuddy/.venvs/ppocrv6/,LiteParse 则随宿主 Python 安装。判断标准是「能不能 import / 能不能跑」,不是「目录在不在某个固定位置」。

上述四个命令是逻辑入口名,对应本技能包内的脚本(scripts/pdfocrv6.py / scripts/pdf2md.py / scripts/pdf_preprocess.py)。若 PATH 中没有对应可执行文件,用 python scripts/<名字>.py 调用即可,无需安装 wrapper。

安装后自检(先跑这段,再干活)

# ① 依赖
python -c "import cv2, numpy, onnxruntime, fitz; print('deps OK')"   # PP-OCRv6 通道
python -c "import paddle, paddleocr; print('paddle OK')"              # PaddleOCR 通道
# ② 命令入口
lit --version
# ③ 模型(三档应全部 OK)
python scripts/pdf_ocr_v6.py --tier tiny    --device cpu -i probe.png
python scripts/pdf_ocr_v6.py --tier small   --device cpu -i probe.png
python scripts/pdf_ocr_v6.py --tier medium  --device cpu -i probe.png

⚠️ pip 返回 0 ≠ 装成功:企业环境的安全守卫会拦截 pip 的文件写入,pip install 退出码为 0 但 import 必然失败。唯一可靠的判据是 import 成功 + 最小推理跑通(即上面的 ③)。

系统依赖(Windows)

依赖版本用途安装
PyMuPDF1.27+PDF 渲染首选(纯 PyPI,免 poppler)pip install PyMuPDF
poppler25.07.0pdf2image 的 PDF→图(回退方案)winget(用户 PATH 已写入,新终端生效)
ImageMagick7.1.2-29LiteParse OCR 的图像转换winget MSIX(magick.exe 别名)
Tesseract5.4 + chi_simLiteParse OCR 中文引擎已有 C:\Program Files\Tesseract-OCR\

⚠️ poppler 需要新终端才能被 PATH 找到;且 winget 装 poppler 会从 GitHub 下载,国内常失败 → 优先用 PyMuPDF。

快速选择(必读)

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

# ② 判定扫描件:去掉分页标记与页码后,若无实质文字 ⇒ 扫描件
#    实测:lit 对扫描件输出 "\n--- Page 1 ---\n1\n\n--- Page 2 ---\n2\n"
#    判定 = 剔除 "--- Page N ---" 与纯数字行后,是否还有文字

# ③ 扫描件走 PP-OCRv6(三档:tiny 6.3MB / small 31MB / medium 133MB)
python scripts/pdf_ocr_v6.py input.pdf --tier small --device cpu -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 --device cpu -o ./output

# ⑤ 关键字段(金额/编号/公章/签名)→ 走 PaddleOCR v4,不要用 PP-OCRv6
python scripts/pdf2md.py input.pdf -o ./output

档位选择阈值

情形用哪档依据
快速通读全文、只需大致内容tiny0.5s/页,够用
常规合同/报告正式存档small默认档,性价比最高
小字号、密集表格、扫描质量差medium精度最高
任何含金额/编号/签章的正式用途不用 PP-OCRv6,走 pdf2mdtiny/medium 金额还原 0/12

⚠️ 硬约束:哪些字段不能交给 PP-OCRv6

实测(12 页扫描件压测):金额 12,345.67 的还原率 —— PP-OCRv6 tiny 0/12、medium 0/12;PaddleOCR v4 12/12。

内容走 PP-OCRv6走 PaddleOCR v4
正文/普通文字✅ 可用✅ 可用
金额(千分位/小数)❌ 实测 0/12✅ 12/12
编号(合同号/单号)❌ 不保证✅
公章/签名❌ 会乱码✅ 基本正确

PP-OCRv6 定位是快速全文预览,不是关键字段通道。涉及金额/编号/签章的正式用途,必须用 PaddleOCR v4 复核。

--device 与输出路径

  • --device 默认 cpu(原默认 gpu,但无 DirectML 会静默回退,易误判)。GPU 需先装 onnxruntime-directml(Intel/AMD)或 onnxruntime-silicon(Apple M)。
  • -o 语义:以 .txt/.json 结尾且输入为单图 → 输出该文件(同名 .json 一并生成);否则 → 输出目录(内含 <basename>.txt + <basename>.json)。多页输入即使传 -o result.txt 也按目录处理并打印提示。
  • scripts/pdf2md.py 的 -o 恒为输出目录,固定生成 <basename>.md + <basename>.json。

输出结构(OCR 结果 JSON)

pdfocrv6.py 输出的 JSON:

{
  "engine": "PP-OCRv6 tiny",
  "model_size": "6.3 MB",
  "pages": [
    {
      "page": 1,
      "results": [
        {
          "text": "识别出的文字",
          "confidence": 0.9632,
          "box": [[592,537],[318,537],[318,509],[592,509]]
        }
      ]
    }
  ]
}

pdf2md.py 输出的 JSON(字段名不同,注意区分):

{
  "engine": "paddleocr-v4",
  "model": "PP-OCRv4",
  "source": "输入文件路径",
  "dpi": 300,
  "pages": [ { "page": 1, "results": [ { "text": "...", "confidence": 0.98, "box": [] } ] } ]
}
字段适用含义
pages[].page两者页码,从 1 开始
pages[].results[].text两者识别文本(按阅读顺序)
pages[].results[].confidence两者置信度 0~1。低置信度行必须人工复核
pages[].results[].box两者四点包围盒坐标(像素),可用于裁剪/复核定位
engine两者引擎标识,PP-OCRv6 形如 PP-OCRv6 tiny,PaddleOCR 形如 paddleocr-v4
model_size仅 PP-OCRv6模型档位体积(tiny 6.3 MB / small 31 MB / medium 133 MB)
model / source / dpi仅 PaddleOCR模型名 / 输入来源 / 渲染 DPI

confidence 高 不等于 识别对——实测中 PP-OCRv6 金额乱码时 confidence 仍显示 0.95+。置信度只作参考,关键字段以 PaddleOCR 结果为准。

工作流

输入文档
  ├── 有文本层 → lit parse --no-ocr(~15ms/页)
  │     └── 剔除分页标记后无实质文字 ⇒ 转扫描件
  └── 扫描件 → 先预处理(倾斜/方向/展平) → ocr6(tiny|small|medium)
        └── 含金额/编号/签章 → 再走 PaddleOCR v4 复核

性能速查

类型引擎单页17 页合同
文本层 PDFLiteParse~15ms~0.15s
扫描件(极速)PP-OCRv6 Tiny~0.5s~6s(12页实测)
扫描件(均衡)PP-OCRv6 Small~1-2s~2-4min(估)
扫描件(高精度)PP-OCRv6 Medium~1s~12s(12页实测)
中文旧版PaddleOCR v4~1.7s~20s(12页实测)

数据来源:文本层 ~15ms/页、tiny/medium/PaddleOCR 的 12 页耗时均为本机实测(2026-11-18);其余标注「估」。PP-OCRv6 识别速度与 PaddleOCR v4 同量级,差别在关键字段准确率而非速度。 准确率:PP-OCRv6 ~97%+(正文),预处理后 ~98%+。关键字段(金额/编号/签章)以 PaddleOCR 为准。

模型体积

档位目录实测体积
Tinyppocrv6_onnx(不带 tier 后缀)6.3 MB
Smallppocrv6smallonnx31 MB
Mediumppocrv6mediumonnx133 MB
三档合计~170 MB

模型根目录:~/.workbuddy/.venvs/ppocrv6models/。 下载:bash scripts/downloadmodels.sh all(镜像优先,见 references/ppocrv6-guide.md) 只校验不下载:bash scripts/download_models.sh --check all(输出每档完整性 + 体积)

按需加载的参考文档

所有详细教程已移至 references/,需要时读取:

场景参考文件
LiteParse 完整用法(Rust CLI/截图/批量)references/liteparse-usage.md
PaddleOCR 旧版(v4,Python 3.13 兼容修复)references/paddleocr.md + references/paddleocr-py313-compat.md
pdf2md 关键字段通道(CLI + 安装)references/pdf2md-guide.md
文档预处理详解(倾斜/方向/展平/效果预测)references/pdf-preprocessing.md
结构化解析(版面分析+表格提取+JSON)references/structured-parsing.md
PP-OCRv6 完整指南(模型选择/GPU加速/迁移)references/ppocrv6-guide.md
国内网络适配与镜像源references/network-and-troubleshooting.md
完整原版 SKILL.md(v3.3.0 全部内容)references/full-guide.md
OpenDataLoader(纯 Java,已不推荐)references/opendataloader.md

回归测试

python tests/smoke_test.py

8 项用例:文本层提取、扫描件判定规则、中文测试图 OCR、多页页数一致、文档引用一致性、环境表描述标准状态(非单机快照)、pdf2md CLI 契约、关键字段硬约束留存。升级后先跑这个。

已知限制(v3.5.1 明确标注)

限制说明
PP-OCRv6 不做关键字段金额/编号/签章 → 必须 pdf2md
模型不自动下载需手动跑 scripts/download_models.sh
pdf2md 需独立环境PaddleOCR v4 与 PP-OCRv6 依赖不兼容,须装在单独 venv(建议 Python 3.12);按 references/pdf2md-guide.md 建
pdfparsestructured.py 依赖 doclingdocling 在部分环境装不上(pypdfium2 DLL 被拦),非必选链路

注意事项

  • 模型不是首次运行自动下载:PP-OCRv6 三档模型需手动下载(bash scripts/downloadmodels.sh all,约 170 MB),默认不自动拉取。默认路径 ~/.workbuddy/.venvs/ppocrv6models/。
  • 内存占用需实测:OCR 任务建议串行执行,避免同时加载多个 OCR 引擎(每个引擎峰值 300MB-1GB,以本机实测为准)
  • 预处理对平整扫描件效果不明显,对手机拍照/弯曲文档提升 1~5%
  • 解释器建议:PaddleOCR 优先用 Python 3.12;3.13 需按 references/paddleocr-py313-compat.md 打补丁
  • 本机 pip 返回 0 ≠ 装成功:企业安全守卫会拦截 pip 文件写入,唯一可靠判据是 import 成功 + 最小推理跑通

同分类其他技能

查看全部 ›