PaddleOCR PP-StructureV3：从 PDF 到 Markdown 的完整文档解析指南

PaddleOCR PP-StructureV3：从 PDF 到 Markdown 的完整文档解析指南

【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100+ languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR

多栏排版、嵌套表格与公式混杂的 PDF 和图片文档，人工转写成本高、自动化提取又容易丢失结构。PaddleOCR 的 PP-StructureV3 产线把版面区域检测、文本识别、表格结构识别、公式与图表识别串成一条完整产线，直接输出 Markdown / JSON / Word。本文覆盖安装步骤、最小可运行示例、典型场景的模型组合配置，以及基于 OmniDocBench 数据的性能对比与选型建议，帮你在半天内把文档解析能力接入现有项目。

核心能力速览

PP-StructureV3 的定位是端到端文档解析产线：你只需要一个输入文件，产线内部完成区域检测、分类路由到各识别模型、阅读顺序恢复与 Markdown 拼装，无需手工拼接各模型输出。

架构与数据流

一条 PDF 或图片进入产线后的处理流程如下：

1. 文档预处理（可选）：方向分类、图像矫正
2. 版面区域检测：切出文本、表格、公式、图表等区域
3. 各区域按类型路由：通用 OCR、表格识别、公式/图表/印章识别
4. 按多栏阅读顺序恢复拼接各块内容
5. 输出 Markdown / JSON / Word 结构化结果

下图是一份英文医学文档的解析效果，可以看到版面区域检测对表格区、正文区与标题区的定位结果：

快速上手

先安装最小依赖（Python 环境）：

pip install "paddlepaddle>=3.0.0" pip install "paddleocr>=3.0.0"

下面这段代码用默认高精度配置解析一张文档图片，并保存 JSON 与 Markdown 结果：

from paddleocr import PPStructureV3 pipeline = PPStructureV3() # 默认配置：服务端 OCR + 版面检测 + 表格/公式/印章识别 output = pipeline.predict("./pp_structure_v3_demo.png") for res in output: res.save_to_json(save_path="output") # 结构化 JSON，含各区域坐标与识别结果 res.save_to_markdown(save_path="output") # 按阅读顺序拼装好的 Markdown

首次运行会自动下载各模块模型，建议预留磁盘空间。如果已有 GPU，可在构造参数中加device="gpu"。

典型场景实践

以下场景展示与默认配置不同的 API 组合，可根据自身文档类型替换。

PDF 转单文件 Markdown

PDF 输入时产线默认逐页输出独立的 Markdown 文件。如果你的目标是整份文档一个文件（例如喂给 RAG 做切分），需要用concatenate_markdown_pages手动拼接各页结果：

from pathlib import Path from paddleocr import PPStructureV3 pipeline = PPStructureV3() output = pipeline.predict("./report.pdf") markdown_list, markdown_images = [], [] for res in output: md = res.markdown markdown_list.append(md) markdown_images.append(md.get("markdown_images", {})) # 页面内嵌图片 merged = pipeline.concatenate_markdown_pages(markdown_list) out_dir = Path("./output") out_dir.mkdir(parents=True, exist_ok=True) (out_dir / "report.md").write_text(merged, encoding="utf-8") for pages in markdown_images: for name, image in pages.items(): (out_dir / name).write_bytes(image)

预期输出：output/report.md为整份 PDF 合并后的 Markdown，页面中裁出的图片按相对路径一并落盘，Markdown 中的图片引用可直接渲染。

拼接完成后，还可以用res.save_to_word在同一次推理循环里额外产出 Word 版本，适合归档流程。

轻量配置：低延迟批量解析

默认配置偏向精度，模型体积和显存占用都不小。如果你的文档以简单扫描件为主、不需要公式与图表理解，把各模块换成轻量版本可以明显降低单页耗时：

from paddleocr import PPStructureV3 pipeline = PPStructureV3( layout_detection_model_name="PP-DocLayout-S", # 4.8MB 轻量版面模型 text_detection_model_name="PP-OCRv5_mobile_det", # 移动端文本检测 text_recognition_model_name="PP-OCRv5_mobile_rec", # 移动端文本识别 use_formula_recognition=False, # 关闭公式识别 use_chart_recognition=False, # 关闭图表解析 use_seal_recognition=False, # 关闭印章识别 ) output = pipeline.predict("./invoice.jpg") for res in output: res.save_to_markdown(save_path="output")

预期输出：结构与默认配置一致的 Markdown，仅少了公式 LaTeX 与图表描述内容；版面检测 GPU 耗时从 50ms 级降到 10ms 级（V100 数据）。

英文与多语言文档

产线默认使用中英文 PP-OCRv5 模型。纯英文或指定语言文档可通过lang切换识别模型，例如英文文档、韩文文档：

from paddleocr import PPStructureV3 pipeline = PPStructureV3(lang="en") # 自动选择英文识别模型 output = pipeline.predict("./en_paper.pdf") for res in output: res.save_to_markdown(save_path="output")

预期输出：按英文识别模型产出的 Markdown。lang支持的语言清单与对应的ocr_version组合规则，见文档目录docs/version3.x/pipeline_usage/PP-StructureV3.md的附录部分。

性能与选型

以下数据来自 OmniDocBench 评测（编辑距离，数值越低越好），对比对象为常见的文档解析方案：

速度方面，V100 上 925 页混合文档的实测：Server OCR + PP-FormulaNet-L 且开启图表识别时约 4.1s/页，关闭图表识别降至约 1.8s/页，公式与图表模块是主要耗时项。

分档建议：

• 如果你要在 CPU 或端侧做低延迟批量解析，推荐轻量档：PP-DocLayout-S+PP-OCRv5_mobile系列，并关闭公式、图表、印章模块。
• 如果你处理以文本为主的通用文档（合同、报告、新闻页），推荐均衡档：默认配置即可，必要时用predict_iter流式处理控制内存。
• 如果你解析学术论文或含大量公式的教材，推荐高性能档：PP-DocLayout_plus-L版面模型 +PP-FormulaNet-L公式模型 + 开启use_chart_recognition，预留 16GB 以上显存。

常见问题 FAQ

推理速度达不到预期默认配置加载的是服务端模型，单模块精度优先。换成轻量模型组合即可提速，典型改法见上节轻量配置；同时关闭不需要的可选模块（公式、图表）能进一步降低 50% 以上耗时。

pipeline = PPStructureV3( layout_detection_model_name="PP-DocLayout-S", text_detection_model_name="PP-OCRv5_mobile_det", text_recognition_model_name="PP-OCRv5_mobile_rec", )

PDF 结果是按页拆开的，如何合并predict对 PDF 逐页输出，Markdown 默认每页一个文件。收集每页res.markdown后调用pipeline.concatenate_markdown_pages(markdown_list)拼接，并同步落盘markdown_images中的裁切图片。

显存或内存不足（OOM）优先关闭use_chart_recognition与use_formula_recognition（两者模型体积最大），再把predict换成predict_iter，逐页处理、及时释放上一页的中间结果，可显著降低峰值占用。

总结与延伸

1. 版面、OCR、表格、公式一条产线打通
2. Markdown / JSON / Word 三格式输出
3. 各模块模型可独立替换组合
4. 支持 100+ 语言与 GPU / CPU 部署

PP-StructureV3 的价值在于把「文档到结构化数据」这段链路收敛为一次predict调用，后续 PaddleOCR 对版面、表格与公式模块的每次迭代都可以直接热替换模型名接入。

延伸阅读：

• docs/version3.x/pipeline_usage/PP-StructureV3.md：产线完整参数与各模块模型列表
• docs/version3.x/pipeline_usage/table_recognition_v2.md：表格识别 v2 子产线细节
• paddleocr/_pipelines/pp_structurev3.py：产线封装源码，可查看所有可配置参数

【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100+ languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR