PDF与图片文字提取专家
当用户需要从 PDF、图片、扫描件中提取文字内容时使用。适合处理合同、发票、报告等文档,尤其是中文扫描件、手机拍照的弯曲页面、歪斜的文档。 最新版特点:支持 PP-OCRv6 三档模型 (Tiny/Small/Medium) 和文本层 PDF 极速提取 (LiteParse ~0.9ms/页),并内置文档预处理管线(倾斜校正/方向校正/文档展平)和结构化解析(版面分析/表格提取)。 支持 PP-OCRv6 三档模型 (Tiny/Small/Medium) 和文本层 PDF 极速提取 (LiteParse ~0.9ms/页),并内置文档预处理管线(倾斜校正/方向校正/文档展平)和结构化解析(版面分析/表格提取)。
skillhub install @user_779b44c7/pdf-ocr-md
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 |
ocr6 | PP-OCRv6 三档 OCR(快速全文预览) | 模型在 ~/.workbuddy/.venvs/ppocrv6_models/;推理环境为任意装了 onnxruntime+cv2 的 venv | bash scripts/download_models.sh --check all 验模型;python -c "import onnxruntime" 验环境 |
pdf2md | PaddleOCR 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)
| 依赖 | 版本 | 用途 | 安装 |
|---|---|---|---|
| PyMuPDF | 1.27+ | PDF 渲染首选(纯 PyPI,免 poppler) | pip install PyMuPDF |
| poppler | 25.07.0 | pdf2image 的 PDF→图(回退方案) | winget(用户 PATH 已写入,新终端生效) |
| ImageMagick | 7.1.2-29 | LiteParse OCR 的图像转换 | winget MSIX(magick.exe 别名) |
| Tesseract | 5.4 + chi_sim | LiteParse 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
档位选择阈值
| 情形 | 用哪档 | 依据 |
|---|---|---|
| 快速通读全文、只需大致内容 | tiny | 0.5s/页,够用 |
| 常规合同/报告正式存档 | small | 默认档,性价比最高 |
| 小字号、密集表格、扫描质量差 | medium | 精度最高 |
| 任何含金额/编号/签章的正式用途 | 不用 PP-OCRv6,走 pdf2md | tiny/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 页合同 |
|---|---|---|---|
| 文本层 PDF | LiteParse | ~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 为准。
模型体积
| 档位 | 目录 | 实测体积 |
|---|---|---|
| Tiny | ppocrv6_onnx(不带 tier 后缀) | 6.3 MB |
| Small | ppocrv6smallonnx | 31 MB |
| Medium | ppocrv6mediumonnx | 133 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 依赖 docling | docling 在部分环境装不上(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 成功 + 最小推理跑通
同分类其他技能
查看全部 ›腾讯文档(docs.qq.com)-在线云文档平台,是创建、编辑、管理文档的首选 skill。涉及"新建/创建/编辑/读取/查看/搜索文
335 262.3万 WPS Office 全家桶WPS Office 全家桶 - 四引擎(WPS/MS Office/LibreOffice/纯Python)智能识别用户已安装软件,纯
182 109.3万 ppt-generator-skill智能 PPT 生成助手。根据用户描述的主题、行业、风格,自动生成漂亮的 PPT 文件。支持所有行业(商务、教育、科技、医疗、金融、创意等
378 91.6万 腾讯文档在线协作自动化通过 Tencent Docs Open API 以 curl + jq 创建、读取、列出、搜索和管理腾讯文档的自动化工作流,覆盖在线文
0 85.8万 WPS Office 全家桶WPS Office 全家桶 - 四引擎(WPS/MS Office/LibreOffice/纯Python)智能识别用户已安装软件,纯
5 81.6万 秘书材料星公文写作-妙笔skill体制内资深办公室主任+管理学博士,自学编程开发的智能公文写作Skill,让所有办公室同仁少掉头发、少加无用的班,材料一稿过关,省下的时间
50 77.2万