PP-StructureV3：文档转 Markdown，附真实输出

PP-StructureV3 能做什么#

PP-StructureV3 随 PaddleOCR 3.0 于 2025 年 5 月发布，是在之前的版面解析产线基础上构建的。它带来了更好的版面、表格和公式模型，以及图表理解、多栏阅读顺序和 Markdown 输出。¹⁵它由大约十几个小模型串联而成，每个模型都由一个 use_* 开关控制启用与否：

下面是 PaddleOCR 3.7.0 实际加载的默认模型。它们写在 PaddleX 3.7.2 的产线配置里，而不是 PaddleOCR 自己的文档里，所以其中有几项会让人意外：³

有两点需要注意。使用文档里写的无线表（无边框表格）模型是 SLANeXt_wireless，但配置实际加载的是 SLANet_plus。¹³另外，PP-StructureV3 不使用 PP-DocLayoutV2/V3——它们属于 PaddleOCR-VL。两者的取舍在于：PP-StructureV3 能给出单元格级和文本行级的坐标，而 VL 系列不能。⁵

安装#

PP-StructureV3 除了 PaddleOCR 和推理引擎之外，还需要 doc-parser 这个 extra。以下是我们使用的命令：⁴

python -m pip install paddlepaddle==3.2.0
python -m pip install "paddleocr[doc-parser]==3.7.0" python-docx

python -m pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/
python -m pip install "paddleocr[doc-parser]==3.7.0" python-docx

这个 extra 会装上 paddlex[ocr,genai-client]——包括 BeautifulSoup、lxml、openpyxl、pypdfium2、scikit-learn、tokenizers 等。它要求 Python 3.9 或更高版本。我们额外安装 python-docx，因为这个 extra 不包含它，而缺了它 Word 导出——以及命令行的 --save_path——都会失败（详情）。我们锁定 paddlepaddle==3.2.0，是因为 PyPI 上当前的 3.3.1 版在我们的测试中会让 PaddleOCR 3.7.0 在 CPU 上崩溃（详情与修复方法）。

不装这个 extra，创建产线时就会失败。这是我们复现出的报错：

RuntimeError: A dependency error occurred during pipeline creation. Please refer to the installation documentation to ensure all required dependencies are installed.
(caused by DependencyError: `PP-StructureV3` requires additional dependencies. To install them, run `pip install "paddlex[ocr]==<PADDLEX_VERSION>"` if you're installing `paddlex` from an index, ...)

修复方法是 pip install "paddleocr[doc-parser]"——报错信息建议直接安装 paddlex[ocr]，这样也行，但很容易与 PaddleOCR 锁定的版本对不上。

快速开始：Python 与命令行#

from paddleocr import PPStructureV3

pipeline = PPStructureV3(
    use_doc_orientation_classify=False,   # 本来就是默认值；旋转的扫描件请设为 True
    use_doc_unwarping=False,              # 拍摄的弯曲页面请设为 True
)
for res in pipeline.predict("invoice.png"):
    res.print()                                  # 在终端打印结构化结果
    res.save_to_markdown(save_path="output")     # output/invoice.md + output/imgs/
    res.save_to_json(save_path="output")         # output/invoice_res.json
    res.save_to_img(save_path="output")          # 版面、OCR 和阅读顺序的可视化图

paddleocr pp_structurev3 -i invoice.png --save_path ./output

# GPU，以及最常用的几个开关
paddleocr pp_structurev3 -i scan.pdf --device gpu:0 \
  --use_doc_orientation_classify True --use_chart_recognition True --save_path ./output

第一次运行会把所有默认模型下载到 ~/.paddlex/official_models/。在命令行中，--save_path 会对每一页调用所有已注册的保存方法，包括 Word 导出——所以没装 python-docx 时，我们的命令行运行写出了 Markdown、JSON、HTML、XLSX 和图片，然后以 ModuleNotFoundError: No module named 'docx' 和退出码 1 中止。⁹⁴设备会自动选择（有 GPU 时用 GPU 0）；传入 device="cpu" 或 device="gpu:0" 可以强制指定。

真实输出：一张发票和一页论文#

下面是默认产线在我们两张测试页面上的原始输出，未做任何修改。左边是输入的图片，右边是 save_to_markdown() 生成的 .md 文件。⁴

发票#

mdinvoice.md（默认模型）

## Northwind Lighting Co

88 Foundry Lane, Leeds LS1 4AB, United Kingdom billing@northwind-lighting.example·VAT GB 123 4567 89INVOICE

Invoice no.INV-2026-0917Issue date 14 Oct 2026Due date 13 Noy 2026

BILL TO

Ashgrove Architects Ltd Unit 5. CanaL Wharf Manchester M1 2EQ

PROJECT

Library refit, Ievel 2PO number: AA-77310


<div style="text-align: center;"><html><body><table border="1"><tbody><tr><td>Description</td><td>Qty</td><td>Unit price</td><td>Amount</td></tr><tr><td>LED panel 600×600,4000K</td><td>24</td><td>£46.00</td><td>£1,104.00</td></tr><tr><td>Linear pendant, 1.2 m</td><td>10</td><td>£128.50</td><td>£1,285.00</td></tr><tr><td>Emergency exit sign</td><td>6</td><td>£39.90</td><td>£239.40</td></tr><tr><td>DALI dimming driver</td><td>12</td><td>£22.75</td><td>£273.00</td></tr><tr><td>Installation labour (hours)</td><td>16</td><td>£55.00</td><td>£880.00</td></tr></tbody></table></body></html></div>


## Payment terms

Subtotal £3,781.40VAT 20%£756.28Total due £4,537.68Please pay within 30 days by bank transfer to Northwind Lighting Co.Sort code 12-34-56, account 87654321. Quote the invoice number as reference.Late payments may incur interest at 8% above the Bank of England base rate.

上面的表格 HTML 原样渲染后如下：

做对了的：全部 24 个表格单元格、每个数字和价格、两个章节标题，以及付款条款的每一行。出错的地方：

• 三行文字有错字：Noy 应为 Nov，Ievel（大写 I）应为 level，Unit 5. CanaL 应为 Unit 5, Canal。这些错误来自 PP-OCRv5 文本识别模型——见修复方法。
• 区块内的换行直接消失，连空格都没留。“INV-2026-0917Issue date 14 Oct 2026Due date”在页面上原本是三行“标签/值”。如果你需要键值对，请读取 overall_ocr_res（每个文本行一条），而不是 Markdown。
• 阅读顺序错了一次。合计金额区块被放到了“Payment terms”标题之后，并和下面的段落粘在一起。
• 页脚不见了。“Thank you for your business.”其实被检测到了——它在 JSON 里，标签为 footer——但 footer 属于默认的 markdown_ignore_labels，同在其中的还有 header、number、footnote、aside_text 以及页眉/页脚图片。³传入 markdown_ignore_labels=[] 即可保留全部内容。
• 表格没有 <thead>，表头行只是一个普通行。标题丢掉了末尾的句点（“Northwind Lighting Co”）。

含公式和表格的论文页#

mdpaper-page.md

### 3. Training Objective

We train the recognizer with a standard sequence objective. Given N text-line images x_i and their transcriptions y_i, the model minimises the average negative log-likelihood of the target sequence:

$$\mathcal{L}=-\textstyle\frac{1}{N}{\sum_{i\:=\:1}^{N}}\mathsf{l o g}\:p(y_{i}\mid x_{i}),$$

Table 2 reports the effect of the training schedule on a held-out set of 2,000 receipt photographs. Longer schedules improve accuracy but cost time.

<div style="text-align: center;">Table 2. Schedule ablation on the receipt set.</div>



<div style="text-align: center;"><html><body><table border="1"><thead><tr><td>Schedule</td><td>Line accuracy</td><td>Train hours</td></tr></thead><tbody><tr><td>Short (20 epochs)</td><td>91.4%</td><td>6</td></tr><tr><td>Medium (50 epochs)</td><td>93.1%</td><td>15</td></tr><tr><td>Long (100 epochs)</td><td>93.6%</td><td>29</td></tr></tbody></table></body></html></div>


### 4. Discussion

The medium schedule offers the best trade-off : it reaches 93.1% line accuracy in roughly half the training time of the long schedule.

这一页的结果几乎完美。正文每个词都正确；表格完全准确，这次还有了正确的 <thead>；图表标题也作为独立区块保留了下来。公式是数学上正确的 LaTeX，但有两处小问题：“log”被输出为 \mathsf{l o g}（渲染成无衬线的“log”，而不是常见的 \log）；公式编号“(1)”被检测为 formula_number，但没有出现在 Markdown 中。页码“4”是被有意去掉的（标签为 number）。带编号的标题变成了 ###；发票上不带编号的标题则变成了 ##。

修复：改用 PP-OCRv6 文本模型#

PaddleOCR 3.7.0 已把 PP-OCRv6 设为普通 OCR 的默认模型，但 PP-StructureV3 的配置仍然加载 PP-OCRv5_server_det 和 PP-OCRv5_server_rec。³你无法通过 ocr_version="PP-OCRv6" 切换——这个类在该参数上只接受 PP-OCRv3、v4 和 v5。²请直接传入模型名称：

from paddleocr import PPStructureV3

pipeline = PPStructureV3(
    text_detection_model_name="PP-OCRv6_medium_det",
    text_recognition_model_name="PP-OCRv6_medium_rec",
)

我们在同一台机器上用两种配置分别处理了这张发票。所有不同的行如下：⁴

四个错字全部修正，还补回了两个缺失的空格，没有任何地方变差。这些错误确实来自文本模型：在我们的 普通 OCR 基准测试（英文） 中，单独运行的 PP-OCRv5_server 在这张发票上犯了完全相同的 Noy、CanaL 和 Ievel 错误。Markdown 的其余部分——表格、标题、阅读顺序——完全一致，因为只换了文本模型。

这个提速与我们的 普通 OCR 基准测试（英文） 一致：在 CPU 上，PP-OCRv6_medium 比 PP-OCRv5_server 更快也更准。另一个好处是：PP-OCRv6 medium 用一个模型就能识别 50 种语言，包括日文和 46 种拉丁字母语言，因此对默认模型处理得不太好的多语言混排文档也能覆盖。⁸

其他语言#

lang 参数会替你选择文本模型，但只会从 PP-OCRv5 及更早的模型中选。在 3.7.0 源码中，lang="en"、"ch"、"chinese_cht" 和 "japan" 都映射到 PP-OCRv5_server_rec；"fr"、"de" 等拉丁字母语言使用 latin_PP-OCRv5_mobile_rec；韩文、泰文、希腊文和东斯拉夫语言有各自的 PP-OCRv5 mobile 模型；阿拉伯文、西里尔文和天城文则退回到 PP-OCRv3 模型。²如果你传入了模型名称，lang 会被忽略并给出警告。全部语言代码见 语言列表。

多页 PDF 转为一个 Markdown 文件#

对 PDF 调用 predict() 会为每一页返回一个结果，save_to_markdown() 也是每页写一个文件。要得到单个文件，请收集每页的 res.markdown，再用 concatenate_markdown_pages() 合并，它还会判断段落是否跨页延续：¹²

from pathlib import Path
from paddleocr import PPStructureV3

pipeline = PPStructureV3()
pages = pipeline.predict("report.pdf")

markdown_list, images = [], []
for res in pages:
    markdown_list.append(res.markdown)
    images.append(res.markdown.get("markdown_images", {}))

merged = pipeline.concatenate_markdown_pages(markdown_list)
text = merged["markdown_texts"]          # merged 是 MarkdownResult，不是 str

out = Path("output"); out.mkdir(exist_ok=True)
(out / "report.md").write_text(text, encoding="utf-8")
for page_images in images:                       # 图片和表格截图
    for rel_path, img in page_images.items():
        (out / rel_path).parent.mkdir(parents=True, exist_ok=True)
        img.save(out / rel_path)

我们的 2 页 PDF 测试结果#

我们用 Pillow 把同样的两张测试图片打包成 PDF（Pillow 会把它们存为 JPEG），再交给产线处理。PaddleX 以 2.0 倍缩放渲染 PDF 页面，所以发票变成了 1191 × 1684 px 的图片，而不是原来的 1240 × 1754。³⁴这个小变化带来了明显的影响：

• 默认模型丢掉了大部分词间空格：“88FoundryLane,LeedsLS14AB,UnitedKingdom”、“Please pay within30days”。不过 PNG 运行中的字符错误消失了。
• 使用 PP-OCRv6 时文字是干净的——“88 Foundry Lane, Leeds LS1 4AB, United Kingdom”——只有一串数字例外（“VAT GB 123456789”）。
• 两种配置下合计金额区块都消失了。“Subtotal”、“VAT 20%”和“Total due”都被 OCR 识别出来了——它们在 overall_ocr_res 里——但没有任何版面框覆盖它们，所以它们没能进入 parsing_res_list 和 Markdown。在 PNG 运行中，该区块的版面得分只有 0.40。
• 第 2 页的公式比 PNG 版本更干净：是 \log p(y_{i}\mid x_{i})，而不是 \mathsf{l o g}。

区块缺失的修复方法是 layout_threshold。用 predict(..., layout_threshold=0.3) 重新处理 PDF 后，合计金额回到了 Markdown 中（“Subtotal £3,781.40VAT 20%£756.28Total due £4,537.68”）。不过标签也有变化：在 0.3 时，顶部两个标题之一不再被标为标题，还多出了一个 header 区块；在 0.2 时，顶部两个标题都不再是标题。阈值只需降到够用为止。⁴

总的经验是：版面检测决定了哪些内容能进入你的 Markdown，而它对分辨率和压缩很敏感。每遇到一种新的文档类型，都抽查几页，与保留了 OCR 找到的每一行的 overall_ocr_res 对照。

表格#

表格识别默认开启。分类模型先判断每个表格是有线表（带框线）还是无线表，然后结构模型和单元格模型把它重建为 HTML。页面上的每个表格都会进入 table_res_list，同样的 HTML 也会嵌入 Markdown。¹

for res in pipeline.predict("invoice.png"):
    for i, table in enumerate(res["table_res_list"]):
        html = table["pred_html"]          # "<html><body><table>..."
        cells = table["cell_box_list"]     # 每个单元格一个框，页面坐标
        print(i, len(cells), html[:80])
    res.save_to_html(save_path="output")   # 每个表格一个 .html 文件
    res.save_to_xlsx(save_path="output")   # 每个表格一个 .xlsx 文件

在我们的发票上，cell_box_list 有 24 个框，每个单元格一个；论文页上是 12 个。每个条目还有 table_ocr_pred，即表格内部的原始 OCR 结果。⁴影响表格行为的 predict() 选项有：²

如果你只需要表格、不需要版面分析，单独的 table_recognition_v2 产线（TableRecognitionPipelineV2）更轻量。

公式#

公式识别默认开启，使用 PP-FormulaNet_plus-L。每个公式都会出现在 formula_res_list 中，带有 rec_formula（LaTeX），并在 Markdown 中以 $$…$$ 块的形式出现——上面的论文页就是真实的例子。¹⁴L 模型精度最高，也是整条产线中最重的部分，远超其他模型。百度官方的数据（Tesla T4 GPU / Xeon Gold 6271C CPU）：¹

对于在 CPU 上处理的纯英文文档，按这些数据，formula_recognition_model_name="PP-FormulaNet_plus-S" 每个公式大约快 12 倍，英文精度略有损失（中文则损失很大）。如果你的文档没有数学公式，use_formula_recognition=False 可以完全跳过这个模型。使用 engine="onnxruntime" 时也必须加上这个开关，因为那里暂不支持公式模型。¹

印章与图表#

两者默认都关闭。use_seal_recognition=True 会加入 PP-OCRv4_server_seal_det 来识别印章上的弯曲文字——这在中文发票和合同上很常见——它有自己的 seal_det_* 阈值，结果写入 seal_res_list。¹use_chart_recognition=True 会用 PP-Chart2Table 把柱状图、折线图和饼图转换为表格，这是一个 0.58B 参数、约 1.4 GB 的模型。¹百度给出的质量数据前后不一：使用文档报告的“Model Score”为 75.98，3.1.0 的发布说明则是 RMS-F1 80.60%——可能是不同的指标。这两项都不在我们的测试范围内；鉴于模型体积，图表识别在 CPU 上会比较慢。

重要参数#

所有构造参数的默认值都是 None，意思是“使用 PaddleX 配置”。使用文档公布了这些参数最终对应的值——但对其中一些设置，PaddleOCR 3.7.0 实际加载的配置却不一样：¹³

以配置为准。我们保存的 JSON 记录了实际使用的设置：overall_ocr_res.text_det_params 显示为 limit_side_len 736, limit_type "min", unclip_ratio 1.5, max_side_limit 4000——是配置里的值，而不是文档里的值。⁴如果你按文档调了 PP-StructureV3 的参数却看不到变化，原因就在这里。

推理引擎相关选项同样以关键字参数传入：device、engine、enable_mkldnn（默认 True）、cpu_threads（默认 10）、enable_hpi、use_tensorrt、precision，以及用于完整 YAML 覆盖的 paddlex_config。¹

结果里有什么#

每页的结果都是一个类似字典的对象。JSON 文件包含相同的字段：¹⁴

res.markdown 是一个字典，包含 markdown_texts、markdown_images、page_continuation_flags、page_index 和 input_path；res.img 提供可视化图像（layout_det_res、overall_ocr_res 等）。¹

保存：Markdown、JSON、Word、HTML、Excel#

我们对结果调用了每一个保存方法。六个开箱即用，一个需要额外安装包：⁴

PDF 输入时，文件名会带上页码后缀：report_0.md、report_1.md 依此类推。save_path 请传目录而不是文件名，否则各页会互相覆盖。¹

结果对象还有 save_all(path)，会一次运行所有保存方法——这和命令行的 --save_path 做的事情一样，这也是命令行在缺少 python-docx 时同样失败的原因。

CPU 上的性能#

这里的所有测试都在 4-vCPU Intel Xeon @ 2.10 GHz、15 GB 内存、无 GPU 的机器上运行，使用 CPU 上的 PaddlePaddle 3.2.0 并开启默认的 oneDNN 加速。⁴

*在第二个会话中测得，当时机器上还有其他任务在运行，请视为近似值；发票的数据来自一次干净的运行。从我们的测试中得出三点实用建议：

• 首次调用很慢。创建产线要加载大约十几个模型（第一次运行还要下载），第一次 predict() 还要预热。产线只创建一次，然后对所有文件复用。
• 预留约 5 GB 内存。这是加载并运行默认产线时我们的 Python 进程占用的内存（常驻内存）。4 GB 的机器会很吃力。
• 关掉不需要的功能是最有效的手段。按百度自己的表格，使用 L 模型的公式识别是最重的阶段（在他们的 CPU 上每个公式超过 3 秒）；use_formula_recognition=False、use_chart_recognition=False（默认已关闭）以及换用 S 公式模型都能缩短耗时。¹

百度公布的数据快得多，因为他们用的是 GPU 或大型服务器 CPU。对于默认配置，他们的 280 张图片基准报告：A100 上每张 1.38 s，A10 上 1.74 s，T4 上 3.70 s；“轻量”配置在 Intel Xeon 8350C CPU 上每张 3.74 s，在 Apple M4 上 12.22 s。⁶这些是我们没有复现的官方数据。

同一来源显示：图表识别会让每页耗时增加一倍以上，而 mobile/轻量配置大约能减半。使用 server 模型时，V100 上的峰值显存为 17.0 GB，A100 上为 21.8 GB；轻量配置下分别为 8.6 GB 和 11.4 GB。⁶

从 PaddleOCR 2.x 的 PPStructure 迁移#

PPStructure 在 3.x 中已被移除，from paddleocr import PPStructure 现在会抛出 ImportError。它的替代者是 PPStructureV3，而且与 PaddleOCR 类不同，它没有兼容层：每个旧关键字参数都会抛出 ValueError: Unknown argument: …。⁹

我们的 迁移指南 有完整的映射表，还有一个能自动改写旧代码的转换工具。

什么时候不该用 PP-StructureV3#

• 你只需要文字。直接用 PaddleOCR 搭配 PP-OCRv6 更快：在我们的机器上，PP-OCRv6 medium 识别同一张发票用 PaddlePaddle 需要 9.3 s，用 ONNX Runtime 需要 5.7 s，PP-OCRv6 small 只要 1.9 s（基准测试（英文））。它还会返回每一行及其检测框，处理表单时这往往正是你需要的。
• 你最看重困难文档上的精度，而且有 GPU。在 OmniDocBench v1.5（第三方）上，PP-StructureV3 总分 86.73；PaddleOCR-VL-1.5 为 94.50。⁷杂乱的扫描件、手写体和复杂版面正是 PaddleOCR-VL 的用武之地。
• 表单与键值对抽取。如我们的发票所示，标签/值对在 Markdown 中会被合并成连续的文字。请使用行级 OCR 结果，或 PP-ChatOCRv4 这类信息抽取产线。
• 原生数字 PDF。如果 PDF 本身已有文本层，直接提取文本可以完全避免 OCR 错误，耗时也只是零头；PP-StructureV3 适合扫描件和纯图片 PDF。对于 Word、Excel 和 PowerPoint 文件，PaddleOCR 的 doc2md 无需任何 OCR 即可转换。
• 小机器。默认产线要加载大约十几个模型，其中包括一个 698 MB 的公式模型。在低内存服务器上，请关闭公式和图表识别，或使用轻量模型。

还没拿定主意？我们的 OCR 工具对比（英文） 把 PP-StructureV3 与 Docling、MinerU 等工具放在一起比较。

常见问题#