shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 内容与媒体无需 API Key

paddleocr-pdf

用 PaddleOCR 云端 API 将 PDF 转为结构化 Markdown，自动检测 PDF 类型选择最优模型（文字版走 PP-StructureV3，扫描件走 PaddleOCR-VL-1.6），支持表格、公式、图表识别，自动切分超长文件，每天 2000 页免费额度。

person作者: vincentduhubModelScope
download下载资源包

PaddleOCR PDF 转 Markdown

用百度 PaddleOCR 云端 API 将 PDF 转为结构化 Markdown。 支持表格还原、公式转 LaTeX、图表解析，每天 2000 页免费。

v2.0 新增：自动检测 PDF 类型，文字版走 PP-StructureV3，扫描件走 PaddleOCR-VL-1.6，无需手动选择。

When to Use

  • 需要将 PDF（文字版或扫描件）转为结构化 Markdown
  • PDF 含表格、公式、图表需要结构化识别
  • 处理超长 PDF（几百页），需要自动切分避免 API 截断
  • 向量化前需要将 PDF 转为高质量 Markdown

Don't use for:

  • 非 PDF 格式的图片（脚本专为 PDF 设计）
  • 只需提取纯文本不需要结构（直接用 pypdf 即可）

前置条件

  1. 已注册飞桨星河社区账号并获取 Access Token
  2. 获取地址：https://aistudio.baidu.com/paddleocr → 点击 API 按钮 → 复制 Token
  3. 将 Token 存入环境变量 PADDLEOCR_TOKEN 或运行时通过 --token 传入
  4. 安装 pypdf（用于页数检查、自动切分和类型检测）：pip install pypdf

使用步骤

Step 1: 确认文件路径

确认用户提供的 PDF 文件路径存在：

ls -lh <pdf_path>

Step 2: 调用脚本处理 PDF

使用技能目录下的 scripts/paddleocr_pdf.py：

# 最简用法（自动检测类型，输出存到 /root/pdf/<文件名>/）
PADDLEOCR_TOKEN="你的token" python scripts/paddleocr_pdf.py /path/to/file.pdf

# 手动指定模型
PADDLEOCR_TOKEN="你的token" python scripts/paddleocr_pdf.py /path/to/file.pdf --model PP-StructureV3
PADDLEOCR_TOKEN="你的token" python scripts/paddleocr_pdf.py /path/to/file.pdf --model PaddleOCR-VL-1.6

# 含图表的文档
PADDLEOCR_TOKEN="你的token" python scripts/paddleocr_pdf.py /path/to/file.pdf --chart

# 自定义切分阈值
PADDLEOCR_TOKEN="你的token" python scripts/paddleocr_pdf.py /path/to/file.pdf --chunk-size 50

# 通过 URL 处理
PADDLEOCR_TOKEN="你的token" python scripts/paddleocr_pdf.py "https://example.com/file.pdf"

默认输出目录：/root/pdf/<文件名不含扩展名>/。例如处理 report.pdf，输出到 /root/pdf/report/。

Step 3: 验证输出

# 查看完整 Markdown
head -50 <output_dir>/full_output.md

# 查看输出文件列表
ls -lh <output_dir>/

自动类型检测与模型选择

脚本在处理本地 PDF 时会自动执行以下流程：

本地文件 → 采样前 5 页提取文本 → ≥2 页文字超过 30 字符 → 文字版 → PP-StructureV3
                                  → 否则 → 扫描件 → PaddleOCR-VL-1.6
URL 输入 → 无法检测，默认使用 PaddleOCR-VL-1.6

| 模型 | 适用场景 | 优势 | |------|----------|------| | PP-StructureV3 | 文字版 PDF | 结构解析精准，表格/公式还原好，标题层级识别 | | PaddleOCR-VL-1.6 | 扫描件/图片型 PDF | 多模态理解，OCR 识别能力强 |

可用 --model 手动覆盖自动检测结果。

Markdown 后处理

OCR 结果保存前会自动进行后处理，确保输出对向量化友好：

| 后处理步骤 | 说明 | |------------|------| | HTML 表格 → Markdown 表格 | <table> 标签转为 \| col \| col \| 格式，减少 token 噪声 | | 图片标签 → VLM 描述 | 调用 VLM 视觉模型生成文字描述，替换 <img> 标签 | | 装饰性图片删除 | VLM 判定为无有效内容（二维码、logo 等）的图片直接移除 | | 空 <div> 清理 | 移除处理后残留的空 HTML 标签 |

默认开启 VLM 描述。如不需要，使用 --no-vlm 参数，图片标签将被直接删除。

自动切分机制

脚本在处理本地 PDF 时会自动执行以下流程：

本地文件 → 检测页数 → 页数 ≤ chunk_size → 直接提交 API
                     → 页数 > chunk_size → 切分为多份 → 逐份提交 → 合并 Markdown → 清理临时文件

| 环节 | 说明 | |------|------| | 页数检测 | 使用 pypdf.PdfReader，秒级完成 | | 默认阈值 | 90 页（API 上限 100 页，留 10 页余量） | | 切分方式 | 按页序号连续切分，每份 ≤ chunk_size 页 | | 临时文件 | 处理完成后自动清理 | | 页码编排 | 合并输出时页码从第 1 页连续编号 | | URL 输入 | 无法预检页数，直接提交（可能被截断） |

可选参数说明

| 参数 | 默认 | 说明 | |------|------|------| | --token TOKEN | 环境变量 | 直接传入 Token | | --model MODEL | 自动检测 | 手动指定模型：PP-StructureV3 或 PaddleOCR-VL-1.6 | | --chart | false | 图表识别（含统计图/饼图时开启） | | --no-vlm | | 不使用 VLM 描述图片，直接删除 <img> 标签 | | --chunk-size N | 90 | 超过 N 页自动切分（API 上限 100） |

PP-StructureV3 特有参数（API 级别，默认开启）

| 参数 | 默认 | 说明 | |------|------|------| | useTableRecognition | true | 表格转 HTML/Markdown | | useFormulaRecognition | true | 公式转 LaTeX | | useRegionDetection | true | 多栏/复杂排版识别 |

PaddleOCR-VL-1.6 特有参数

| 参数 | 默认 | 说明 | |------|------|------| | useDocOrientationClassify | false | 文档方向矫正 | | useDocUnwarping | false | 文档去弯曲 |

输出结构

每个 PDF 的详细输出（单页 MD、图片等）在 /root/pdf/<文件名>/ 目录下，完整 Markdown 同时以 PDF 同名文件复制到 /root/pdf/md/ 统一目录，方便批量下载：

/root/pdf/
├── md/                          # 📋 统一 Markdown 目录（方便下载）
│   ├── 01 计算机网络基础.md
│   ├── 02 数据通信基础.md
│   └── ...
├── 01 计算机网络基础/            # 详细输出
│   ├── 01 计算机网络基础.md      # 完整 Markdown（与 md/ 下相同）
│   ├── page_0.md               # 第 1 页 Markdown
│   ├── page_1.md               # 第 2 页 Markdown
│   ├── ...
│   └── images/                 # 提取的图片（如有）
│       ├── img_0_0.jpg
│       └── ...
└── 01 计算机网络基础.pdf         # 源 PDF

Common Pitfalls

  1. 未安装 pypdf 导致无法检测类型和切分。 脚本会 graceful 降级：无法检测类型时默认使用 PaddleOCR-VL，无法切分时直接提交。但超长 PDF 可能被 API 截断丢失内容。务必 pip install pypdf。

  2. 文字版 PDF 被误判为扫描件。 如果文字版 PDF 的文字层是图片嵌入的（如某些电子书），pypdf 提取不到文本，会被判为扫描件走 PaddleOCR-VL。这其实不影响结果（VL 也能处理），只是会慢一些。可用 --model PP-StructureV3 手动覆盖。

  3. URL 输入的超长 PDF 被截断。 URL 方式无法本地预检页数，脚本只能直接提交。如已知 URL 对应的 PDF 超过 100 页，建议先下载到本地再处理。

  4. Token 过期报 401。 重新到 https://aistudio.baidu.com/paddleocr 获取。

  5. 任务一直 pending。 高峰期排队可能需要几分钟，耐心等待。超过 10 分钟可重新提交。

  6. 切分后单页图片跨页断裂。 切分按固定页数切割，无法感知逻辑内容边界。如需保持章节完整性，可手动将 PDF 预切分后再调用。

  7. 表格识别效果不好。 确保 --chart 没有误开（它只用于统计图，普通表格不需要）。PP-StructureV3 和 PaddleOCR-VL 默认都支持表格结构还原。

  8. PP-StructureV3 比 PaddleOCR-VL 慢很多。 文字版 PDF 处理速度约 1-2 页/10 秒，33 页约需 5 分钟。同等页数 VL 通常快 2-3 倍。如果对速度敏感且不需要精确结构解析，可用 --model PaddleOCR-VL-1.6 强制走 VL。

  9. 免费额度消耗不变。 切分只是拆分提交，总页数不变，不浪费额度。但每次提交的轮询开销会略增。

  10. 后台运行时看不到进度输出。 Python stdout 在非 TTY 模式下全缓冲，print 不会立即输出。后台运行时加 PYTHONUNBUFFERED=1：PYTHONUNBUFFERED=1 python3 paddleocr_pdf.py ...。

  11. pypdf 对某些 PDF 输出大量 "Ignoring wrong pointing object" 警告。 这是 pypdf 对内部结构异常 PDF 的正常行为，不影响页数检测和类型判断，可以忽略。

Verification Checklist

  • [ ] pypdf 已安装（python -c "from pypdf import PdfReader; print('ok')"）
  • [ ] PADDLEOCR_TOKEN 环境变量已设置或通过 --token 传入
  • [ ] 输出目录包含 full_output.md 且内容完整
  • [ ] 检查使用的模型是否正确（文字版应为 PP-StructureV3）
  • [ ] 如有切分，确认页码连续无跳跃
  • [ ] 如有图片，确认 images/ 目录下图片完整