PaddleOCR PP-StructureV3 文档结构化解析产线：精度对比、推理性能基准与参数调优实战指南
【免费下载链接】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
PP-StructureV3 是 PaddleOCR 3.x 中的文档结构化解析产线，能够将文档图像和 PDF 高效转换为 Markdown 等结构化内容，覆盖版面区域检测、表格识别、公式识别、图表理解与多栏阅读顺序恢复。本文基于仓库内官方算法文档与配套源码，完整梳理其关键精度指标、多硬件推理性能基准、Python API/CLI 调用方式与全部可配置参数，帮助你在选型、部署与调参三个环节快速落地。
1. PP-StructureV3 是什么：功能定位与产线组成
PP-StructureV3 将“文档图像/PDF → 结构化数据”这条链路整合为一条可服务化、可二次开发的产线。官方产线教程 PP-StructureV3 产线使用教程 中将其组成归纳为 7 个模块或子产线，其中后 4 个为可选能力：
- 版面区域检测模块：定位文档中的文本块、标题、表格、公式、印章、图表等区域，是整条产线的入口；
- 通用 OCR 子产线：完成文本检测与文本识别；
- 文档图像预处理子产线（可选）：文档图像方向分类 + 文本图像矫正；
- 表格识别子产线（可选）：表格分类、有线/无线表格结构识别、表格单元格检测、表格方向分类；
- 印章文本识别子产线（可选）：印章文本检测 + 印章文本识别；
- 公式识别子产线（可选）：将公式区域转换为 LaTeX；
- 图表解析模块（可选）：对文档中的图表（chart）进行理解解析。
1.1 源码结构：PaddleX 产线的 Python 封装
从源码结构看，仓库中的PPStructureV3是对底层 PaddleX 产线的薄封装，位于 paddleocr/_pipelines/pp_structurev3.py：
- 类
PPStructureV3继承PaddleXPipelineWrapper，其_paddlex_pipeline_name属性返回字符串"PP-StructureV3"，即实际推理由 PaddleX 中同名产线完成； - 模块加载时会先执行
_apply_layout_parsing_patches()。该补丁实现于 paddleocr/_pipelines/_patch_layout_parsing.py，用于修复版面重叠率计算中大坐标整型溢出（例如经过文档图像矫正后）以及空包围盒列表导致的异常，保证layout_merge_bboxes_mode等合并逻辑的稳定性； - 构造函数将
model_name/model_dir/ 阈值 / 开关类参数统一收集到self._params，并在_get_paddlex_config_overrides()中按SubModules.*/SubPipelines.*的路径结构映射为 PaddleX 配置覆盖项（见 pp_structurev3.py#L307-L528），这解释了后文参数表中每一项为什么能精确作用于对应子模块； - CLI 子命令名为
pp_structurev3（PPStructureV3CLISubcommandExecutor.subparser_name），通过add_simple_inference_args注册了通用的-i/--input（必填，输入路径或 URL）与--save_path（输出目录）参数（见 paddleocr/_utils/cli.py#L31-L47）。
1.2 OCR 子产线的版本与语言选择
PP-StructureV3 内置的通用 OCR 子产线支持PP-OCRv3、PP-OCRv4、PP-OCRv5三个版本，由源码常量_SUPPORTED_OCR_VERSIONS = ["PP-OCRv3", "PP-OCRv4", "PP-OCRv5"]约束，传入其他版本会抛出ValueError（pp_structurev3.py#L28-L106）。
当未显式指定文本检测/识别模型时，lang与ocr_version会共同决定模型选择，_get_ocr_model_names()的关键逻辑（pp_structurev3.py#L530-L690）：
- 未指定语言时默认
ch（中文）； ocr_version未指定时，中文/英文/日韩泰及主流拉丁语言、东斯拉夫语言自动选用PP-OCRv5，其余语言（阿拉伯文、西里尔文、天城文等）回落到PP-OCRv3；- 例如中文默认组合为
PP-OCRv5_server_det+PP-OCRv5_server_rec，拉丁文使用{latin}_PP-OCRv5_mobile_rec，v4 版本目前覆盖ch/en； - 如果同时显式传入了检测/识别的模型名或模型目录，
lang与ocr_version会被忽略并打印警告。
模型细节可参见 PP-OCRv5 文档 与 公式识别模块文档、文本检测模块文档。
2. 关键指标：OmniDocBench 上的精度对比
以下表格完整继承自官方算法文档 PP-StructureV3 算法文档 的“关键指标”章节。评估基准为 OmniDocBench（面向多样 PDF 文档解析的综合标注基准），指标为各维度的编辑距离（Edit，越低越好）：
| Method Type | Methods | Overall EN | Overall ZH | Text EN | Text ZH | Formula EN | Formula ZH | Table EN | Table ZH | Read Order EN | Read Order ZH |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Pipeline Tools | PP-structureV3 | 0.145 | 0.206 | 0.058 | 0.088 | 0.295 | 0.535 | 0.159 | 0.109 | 0.069 | 0.091 |
| Pipeline Tools | MinerU-0.9.3 | 0.15 | 0.357 | 0.061 | 0.215 | 0.278 | 0.577 | 0.18 | 0.344 | 0.079 | 0.292 |
| Pipeline Tools | MinerU-1.3.11 | 0.166 | 0.310 | 0.0826 | 0.2000 | 0.3368 | 0.6236 | 0.1613 | 0.1833 | 0.0834 | 0.2316 |
| Pipeline Tools | Marker-1.2.3 | 0.336 | 0.556 | 0.08 | 0.315 | 0.53 | 0.883 | 0.619 | 0.685 | 0.114 | 0.34 |
| Pipeline Tools | Mathpix | 0.191 | 0.365 | 0.105 | 0.384 | 0.306 | 0.454 | 0.243 | 0.32 | 0.108 | 0.304 |
| Pipeline Tools | Docling-2.14.0 | 0.589 | 0.909 | 0.416 | 0.987 | 0.999 | 1 | 0.627 | 0.81 | 0.313 | 0.837 |
| Pipeline Tools | Pix2Text-1.1.2.3 | 0.32 | 0.528 | 0.138 | 0.356 | 0.276 | 0.611 | 0.584 | 0.645 | 0.281 | 0.499 |
| Pipeline Tools | Unstructured-0.17.2 | 0.586 | 0.716 | 0.198 | 0.481 | 0.999 | 1 | 1 | 0.998 | 0.145 | 0.387 |
| Pipeline Tools | OpenParse-0.7.0 | 0.646 | 0.814 | 0.681 | 0.974 | 0.996 | 1 | 0.284 | 0.639 | 0.595 | 0.641 |
| Expert VLMs | GOT-OCR | 0.287 | 0.411 | 0.189 | 0.315 | 0.36 | 0.528 | 0.459 | 0.52 | 0.141 | 0.28 |
| Expert VLMs | Nougat | 0.452 | 0.973 | 0.365 | 0.998 | 0.488 | 0.941 | 0.572 | 1 | 0.382 | 0.954 |
| Expert VLMs | Mistral OCR | 0.268 | 0.439 | 0.072 | 0.325 | 0.318 | 0.495 | 0.6 | 0.65 | 0.083 | 0.284 |
| Expert VLMs | OLMOCR-sglang | 0.326 | 0.469 | 0.097 | 0.293 | 0.455 | 0.655 | 0.608 | 0.652 | 0.145 | 0.277 |
| Expert VLMs | SmolDocling-256M_transformer | 0.493 | 0.816 | 0.262 | 0.838 | 0.753 | 0.997 | 0.729 | 0.907 | 0.227 | 0.522 |
| General VLMs | Gemini2.0-flash | 0.191 | 0.264 | 0.091 | 0.139 | 0.389 | 0.584 | 0.193 | 0.206 | 0.092 | 0.128 |
| General VLMs | Gemini2.5-Pro | 0.148 | 0.212 | 0.055 | 0.168 | 0.356 | 0.439 | 0.13 | 0.119 | 0.049 | 0.121 |
| General VLMs | GPT4o | 0.233 | 0.399 | 0.144 | 0.409 | 0.425 | 0.606 | 0.234 | 0.329 | 0.128 | 0.251 |
| General VLMs | Qwen2-VL-72B | 0.252 | 0.327 | 0.096 | 0.218 | 0.404 | 0.487 | 0.387 | 0.408 | 0.119 | 0.193 |
| General VLMs | Qwen2.5-VL-72B | 0.214 | 0.261 | 0.092 | 0.18 | 0.315 | 0.434 | 0.341 | 0.262 | 0.106 | 0.168 |
| General VLMs | InternVL2-76B | 0.44 | 0.443 | 0.353 | 0.29 | 0.543 | 0.701 | 0.547 | 0.555 | 0.317 | 0.228 |
从该表可以读出两点选型参考：在流水线类工具中，PP-structureV3 的 Overall 中英文编辑距离（0.145 / 0.206）与中文版 Text 指标均为加粗最优值；在专家 VLM 中，GOT-OCR 与 Mistral OCR 的整体编辑距离低于多数通用大 VLM，说明文档解析这一任务上“专用小模型组合的流水线”与“通用大模型”各有位置。注意中文 Formula 维度（0.535）相对偏高，若业务对公式解析要求严苛，可结合第 3 节基准考虑是否关闭公式识别或单独优化。
3. 推理性能基准
3.1 本地推理基准
基本测试环境为：Paddle 3.0 正式版、PaddleOCR 3.0.0 正式版、MinerU 1.3.10、CUDA 11.8、cuDNN 8.9。测试数据为 15 个 PDF 文件共 925 页，包含表格、公式、印章、图表等元素；在 V100 与 A100 两种 GPU 上测试了 6 种配置。配置维度包括：OCR 模型（Server/Mobile 系列）、公式识别模型（PP-FormulaNet-L / M）、是否启用图表识别模块、文本检测max_side_limit。
NVIDIA Tesla V100 + Intel Xeon Gold 6271C：
| 方案 | OCR 模型 | 公式识别模型 | 图表识别 | max_side_limit | 每页耗时 (s) | 平均 CPU (%) | 峰值 RAM (GB) | 平均 RAM (GB) | 平均 GPU (%) | 峰值 VRAM (GB) | 平均 VRAM (GB) |
|---|---|---|---|---|---|---|---|---|---|---|---|
| PP-StructureV3 | Server 系列 | PP-FormulaNet-L | ✗ | 4096 | 1.77 | 111.4 | 6.7 | 5.2 | 38.9 | 17.0 | 16.5 |
| PP-StructureV3 | Server 系列 | PP-FormulaNet-L | ✔ | 4096 | 4.09 | 105.3 | 5.5 | 4.0 | 24.7 | 17.0 | 16.6 |
| PP-StructureV3 | Mobile 系列 | PP-FormulaNet-L | ✗ | 4096 | 1.56 | 113.7 | 6.6 | 4.9 | 29.1 | 10.7 | 10.6 |
| PP-StructureV3 | Server 系列 | PP-FormulaNet-M | ✗ | 4096 | 1.42 | 112.9 | 6.8 | 5.1 | 38 | 16.0 | 15.5 |
| PP-StructureV3 | Mobile 系列 | PP-FormulaNet-M | ✗ | 4096 | 1.15 | 114.8 | 6.5 | 5.0 | 26.1 | 8.4 | 8.3 |
| PP-StructureV3 | Mobile 系列 | PP-FormulaNet-M | ✗ | 1200 | 0.99 | 113 | 7.0 | 5.6 | 29.2 | 8.6 | 8.5 |
| MinerU | - | - | - | - | 1.57 | 142.9 | 13.3 | 11.8 | 43.3 | 31.6 | 9.7 |
NVIDIA A100 + Intel Xeon Platinum 8350C：
| 方案 | OCR 模型 | 公式识别模型 | 图表识别 | max_side_limit | 每页耗时 (s) | 平均 CPU (%) | 峰值 RAM (GB) | 平均 RAM (GB) | 平均 GPU (%) | 峰值 VRAM (GB) | 平均 VRAM (GB) |
|---|---|---|---|---|---|---|---|---|---|---|---|
| PP-StructureV3 | Server 系列 | PP-FormulaNet-L | ✗ | 4096 | 1.12 | 109.8 | 9.2 | 7.8 | 29.8 | 21.8 | 21.1 |
| PP-StructureV3 | Server 系列 | PP-FormulaNet-L | ✔ | 4096 | 2.76 | 103.7 | 9.0 | 7.7 | 24 | 21.8 | 21.1 |
| PP-StructureV3 | Mobile 系列 | PP-FormulaNet-L | ✗ | 4096 | 1.04 | 110.7 | 9.3 | 7.8 | 22 | 12.2 | 12.1 |
| PP-StructureV3 | Server 系列 | PP-FormulaNet-M | ✗ | 4096 | 0.95 | 111.4 | 9.1 | 7.8 | 28.1 | 21.8 | 21.0 |
| PP-StructureV3 | Mobile 系列 | PP-FormulaNet-M | ✗ | 4096 | 0.89 | 112.1 | 9.2 | 7.8 | 18.5 | 11.4 | 11.2 |
| PP-StructureV3 | Mobile 系列 | PP-FormulaNet-M | ✗ | 1200 | 0.64 | 113.5 | 10.2 | 8.5 | 23.7 | 11.4 | 11.2 |
| MinerU | - | - | - | - | 1.06 | 168.3 | 18.3 | 16.8 | 27.5 | 76.9 | 14.8 |
两张表共同说明了三个调参杠杆的作用方向：
- OCR 模型 Server→Mobile：显著降低显存（V100 上 17GB→8.4GB），耗时变化不大；
- 公式识别模型 L→M：耗时略降、VRAM 降低；
max_side_limit4096→1200：文本检测输入分辨率下降后耗时与显存进一步降低（V100 上 1.15s/8.4GB → 0.99s/8.6GB）。max_side_limit的设置方式详见 文本检测模块文档；- 启用图表识别模块：精度能力增强但每页耗时明显上升（V100 上 1.77s→4.09s），按需开启。
3.2 服务化部署基准
服务化部署测试基于 NVIDIA A100 + Intel Xeon Platinum 8350C，测试数据为 1500 张包含表格、公式、印章、图表等元素的图像：
| 实例数 | 并发请求数 | 吞吐 | 平均时延（s） | 成功请求数/总请求数 |
|---|---|---|---|---|
| 4卡 ✖ 1实例/卡 | 4 | 1.69 | 2.36 | 100% |
| 4卡 ✖ 4实例/卡 | 16 | 4.05 | 3.87 | 100% |
从数据看，多实例（4 卡 × 4 实例/卡）将吞吐从 1.69 提升到 4.05，时延从 2.36s 上升到 3.87s，成功率保持 100%——这是“以时延换吞吐”的典型服务化扩展路径。
3.3 产线基准测试数据
测试环境：PaddlePaddle 3.1.0、CUDA 11.8、cuDNN 8.9、PaddleX @ develop 版本；测试数据为包含表格、印章、公式、图表的 280 张图像；测试策略为先使用 20 个样本预热，再对整个数据集重复 1 次测速。
| 流水线配置 | 硬件 | 平均推理时间 (s) | 峰值 CPU (%) | 平均 CPU (%) | 峰值主机内存 (MB) | 平均主机内存 (MB) | 峰值 GPU (%) | 平均 GPU (%) | 峰值设备内存 (MB) | 平均设备内存 (MB) |
|---|---|---|---|---|---|---|---|---|---|---|
| PP_StructureV3-default | Intel 8350C + A100 | 1.38 | 1384.60 | 113.26 | 5781.59 | 3431.21 | 100 | 32.79 | 37370.00 | 34165.68 |
| PP_StructureV3-default | Intel 6271C + V100 | 2.38 | 608.70 | 109.96 | 6388.91 | 3737.19 | 100 | 39.08 | 26824.00 | 24581.61 |
| PP_StructureV3-default | Intel 8563C + H20 | 1.36 | 744.30 | 112.82 | 6199.01 | 3865.78 | 100 | 43.81 | 35132.00 | 32077.12 |
| PP_StructureV3-default | Intel 8350C + A10 | 1.74 | 418.50 | 105.96 | 6138.25 | 3503.41 | 100 | 48.54 | 18536.00 | 18353.93 |
| PP_StructureV3-default | Intel 6271C + T4 | 3.70 | 434.40 | 105.45 | 6865.87 | 3595.68 | 100 | 71.92 | 13970.00 | 12668.58 |
| PP_StructureV3-pp | Intel 8350C + A100 | 3.50 | 679.30 | 105.96 | 13850.20 | 5146.50 | 100 | 14.01 | 37656.00 | 34716.95 |
| PP_StructureV3-pp | Intel 6271C + V100 | 5.03 | 494.20 | 105.63 | 13542.94 | 4833.55 | 100 | 20.36 | 29402.00 | 26607.92 |
| PP_StructureV3-pp | Intel 8563C + H20 | 3.17 | 481.50 | 105.13 | 14179.97 | 5608.80 | 100 | 19.35 | 35454.00 | 32512.19 |
| PP_StructureV3-full | Intel 8350C + A100 | 8.92 | 697.30 | 102.88 | 13777.07 | 4573.65 | 100 | 18.39 | 38776.00 | 37554.09 |
| PP_StructureV3-full | Intel 6271C + V100 | 13.12 | 437.40 | 102.36 | 13974.00 | 4484.00 | 100 | 17.50 | 29878.00 | 28733.59 |
| PP_StructureV3-seal | Intel 8350C + A100 | 1.39 | 747.50 | 112.55 | 5788.79 | 3742.03 | 100 | 33.81 | 38966.00 | 35832.44 |
| PP_StructureV3-seal | Intel 6271C + V100 | 2.44 | 630.10 | 110.18 | 6343.39 | 3725.98 | 100 | 42.23 | 28078.00 | 25834.70 |
| PP_StructureV3-seal | Intel 8563C + H20 | 1.40 | 792.20 | 113.63 | 6673.60 | 4417.34 | 100 | 46.33 | 35530.00 | 32516.87 |
| PP_StructureV3-seal | Intel 8350C + A10 | 1.75 | 422.40 | 106.08 | 6068.87 | 3973.49 | 100 | 50.12 | 19630.00 | 18374.37 |
| PP_StructureV3-seal | Intel 6271C + T4 | 3.76 | 400.30 | 105.10 | 6296.28 | 3651.42 | 100 | 72.57 | 14304.00 | 13268.36 |
| PP_StructureV3-chart | Intel 8350C + A100 | 7.70 | 746.80 | 102.69 | 6355.58 | 4006.48 | 100 | 22.38 | 37380.00 | 36730.73 |
| PP_StructureV3-chart | Intel 6271C + V100 | 10.58 | 599.20 | 102.51 | 5754.14 | 3333.78 | 100 | 21.99 | 26820.00 | 26253.70 |
| PP_StructureV3-chart | Intel 8350C + A10 | 8.03 | 413.30 | 101.31 | 6473.29 | 3689.84 | 100 | 26.19 | 18540.00 | 18494.69 |
| PP_StructureV3-chart | Intel 6271C + T4 | 11.69 | 460.90 | 101.85 | 6503.12 | 3524.06 | 100 | 46.81 | 13966.00 | 12481.94 |
| PP_StructureV3-notable | Intel 8350C + A100 | 1.24 | 738.30 | 110.45 | 5638.16 | 3278.30 | 100 | 35.32 | 30320.00 | 27026.17 |
| PP_StructureV3-notable | Intel 6271C + V100 | 2.24 | 452.40 | 107.79 | 5579.15 | 3635.95 | 100 | 43.00 | 23098.00 | 20684.43 |
| PP_StructureV3-notable | Intel 8563C + H20 | 1.18 | 989.00 | 107.71 | 6041.76 | 4024.76 | 100 | 50.67 | 33780.00 | 29733.15 |
| PP_StructureV3-notable | Intel 8350C + A10 | 1.58 | 225.00 | 102.56 | 5518.10 | 3333.08 | 100 | 49.90 | 21532.00 | 18567.99 |
| PP_StructureV3-notable | Intel 6271C + T4 | 3.40 | 413.30 | 103.58 | 5874.88 | 3662.49 | 100 | 76.82 | 13764.00 | 11890.62 |
| PP_StructureV3-noformula | Intel 6271C（纯 CPU） | 7.85 | 1172.50 | 964.70 | 17739.00 | 11101.02 | N/A | N/A | N/A | N/A |
| PP_StructureV3-noformula | Intel 8350C（纯 CPU） | 8.83 | 1053.50 | 970.64 | 15463.48 | 9408.19 | N/A | N/A | N/A | N/A |
| PP_StructureV3-noformula | Intel 8350C + A100 | 0.84 | 788.60 | 124.25 | 6246.39 | 3674.32 | 100 | 30.57 | 40084.00 | 37358.45 |
| PP_StructureV3-noformula | Intel 6271C + V100 | 1.42 | 606.20 | 115.53 | 7015.57 | 3707.03 | 100 | 35.63 | 29540.00 | 27620.28 |
| PP_StructureV3-noformula | Intel 8563C + H20 | 0.87 | 644.10 | 119.23 | 6895.76 | 4222.85 | 100 | 50.00 | 36878.00 | 34104.59 |
| PP_StructureV3-noformula | Intel 8350C + A10 | 1.03 | 377.50 | 106.87 | 5819.88 | 3830.19 | 100 | 42.87 | 19340.00 | 17550.94 |
| PP_StructureV3-noformula | Intel 6271C + T4 | 2.02 | 430.20 | 109.21 | 6600.62 | 3824.18 | 100 | 65.75 | 14332.00 | 12712.18 |
| PP_StructureV3-lightweight | Intel 6271C（纯 CPU） | 4.36 | 1189.70 | 995.78 | 14000.50 | 9374.97 | N/A | N/A | N/A | N/A |
| PP_StructureV3-lightweight | Intel 8350C（纯 CPU） | 3.74 | 1049.60 | 967.77 | 12960.96 | 7644.25 | N/A | N/A | N/A | N/A |
| PP_StructureV3-lightweight | Hygon 7490 + P800 | 0.86 | 572.20 | 120.84 | 8290.49 | 3569.44 | N/A | N/A | N/A | N/A |
| PP_StructureV3-lightweight | Intel 8350C + A100 | 0.61 | 823.40 | 126.25 | 9258.22 | 3776.63 | 52 | 18.95 | 7456.00 | 7131.95 |
| PP_StructureV3-lightweight | Intel 6271C + V100 | 1.07 | 686.80 | 116.70 | 9381.75 | 4126.28 | 58 | 22.92 | 8450.00 | 8083.30 |
| PP_StructureV3-lightweight | Intel 8563C + H20 | 0.46 | 999.00 | 122.21 | 9734.78 | 4516.40 | 61 | 24.41 | 7524.00 | 7167.52 |
| PP_StructureV3-lightweight | Intel 8350C + A10 | 0.70 | 355.40 | 111.51 | 9415.45 | 4094.06 | 89 | 30.85 | 7248.00 | 6927.58 |
| PP_StructureV3-lightweight | M4（Apple Silicon） | 12.22 | 223.60 | 107.35 | 9531.22 | 7884.61 | N/A | N/A | N/A | N/A |
| PP_StructureV3-lightweight | Intel 6271C + T4 | 1.13 | 461.40 | 112.16 | 7923.09 | 3837.31 | 85 | 41.67 | 8218.00 | 7902.04 |
各流水线配置的含义如下：
| Pipeline configuration | description |
|---|---|
| PP_StructureV3-default | 默认配置 |
| PP_StructureV3-pp | 默认配置基础上，开启文档图像预处理 |
| PP_StructureV3-full | 默认配置基础上，开启文档图像预处理和图表解析 |
| PP_StructureV3-seal | 默认配置基础上，开启印章文本识别 |
| PP_StructureV3-chart | 默认配置基础上，开启文档图表解析 |
| PP_StructureV3-notable | 默认配置基础上，关闭表格识别 |
| PP_StructureV3-noformula | 默认配置基础上，关闭公式识别 |
| PP_StructureV3-lightweight | 默认配置基础上，将所有任务模型都换成最轻量版本 |
备注：由于未收集 NPU 和 XPU 的设备内存数据，表中相应位置标记为 N/A。从该表可以得出几条实用结论：默认配置（Server 级模型）在 A100 上约 1.38 s/张、峰值显存约 37 GB；开启文档图像预处理（-pp）会使耗时翻倍以上（3.50 s），因为矫正模型参与每张图处理；关闭表格/公式（-notable/-noformula）与轻量化（-lightweight）是降低耗时与显存的主要手段，lightweight配置在 A100 上 0.61 s/张、显存峰值仅 7.5 GB，并且支持纯 CPU（Intel 8350C 约 3.74 s/张）与 Apple M4 等异构环境。
4. 实战使用：CLI 与 Python API
4.1 CLI 调用
PPStructureV3CLISubcommandExecutor注册的子命令为pp_structurev3，其参数在 pp_structurev3.py#L698-L1025 中逐个注册。最小可用命令：
# 基本用法：输入图像/PDF 路径或 URL，输出解析结果 python -m paddleocr pp_structurev3 -i ./doc.png --save_path ./output-i / --input：必填，输入路径或 URL（由 paddleocr/_utils/cli.py#L31-L47 定义）；--save_path：输出目录，执行器会逐条打印结果并调用res.save_all(save_path)落盘（见 perform_simple_inference）；- 常用调参示例：
# 关闭表格/公式识别，降低耗时与显存 python -m paddleocr pp_structurev3 -i ./doc.pdf \ --use_table_recognition False --use_formula_recognition False \ --save_path ./output # 调整版面检测阈值与文本检测分辨率 python -m paddleocr pp_structurev3 -i ./doc.png \ --layout_threshold 0.5 --text_det_limit_side_len 960 \ --save_path ./outputCLI 中布尔开关通过str2bool解析，接受true/yes/t/y/1等写法（paddleocr/_utils/cli.py#L20-L21）。
4.2 Python API 调用
from paddleocr import PPStructureV3 pipeline = PPStructureV3( # ocr_version="PP-OCRv5", # 可选：约束内置 OCR 子产线版本 # lang=None, # 可选：语言，未指定时默认 ch # layout_threshold=0.5, # 可选：版面检测置信度阈值 ) results = pipeline.predict("./doc.png") # 或 predict_iter 逐条流式获取 for res in results: res.print() # 打印单页解析结果 res.save_all(save_path="./output") # 保存 Markdown 等产物predict返回predict_iter的结果列表（pp_structurev3.py#L223-L298）；对多页 PDF，还可以使用concatenate_markdown_pages(markdown_list)将逐页 Markdown 拼接为整份文档。仓库测试 tests/pipelines/test_pp_structurev3.py 验证了：结果对象包含overall_ocr_res，其中有dt_polys（检测多边形）、rec_texts（识别文本）、rec_polys、rec_boxes四类字段，且上述参数均能正确透传到底层 PaddleX 产线。
4.3 核心参数说明
以下参数分组整理自PPStructureV3.__init__与predict_iter的签名（pp_structurev3.py#L31-L221），是 CLI 同名选项的完整集合：
功能开关类（布尔值）：
| 参数 | 作用 |
|---|---|
use_doc_orientation_classify | 是否使用文档图像方向分类（文档预处理） |
use_doc_unwarping | 是否使用文本图像矫正 |
use_textline_orientation | 是否使用文本行方向分类 |
use_seal_recognition | 是否启用印章文本识别 |
use_table_recognition | 是否启用表格识别 |
use_formula_recognition | 是否启用公式识别 |
use_chart_recognition | 是否启用图表识别 |
use_region_detection | 是否启用版面子区域检测（多栏阅读顺序） |
format_block_content | 是否将块内容格式化为 Markdown |
markdown_ignore_labels | Markdown 输出中忽略的版面标签列表（nargs="+"） |
版面检测后处理类：
| 参数 | 说明 |
|---|---|
layout_threshold | 版面检测置信度阈值。测试用例确认支持标量、按类别列表（如[0.45, 0.4]）与{类号: 阈值}字典三种形式 |
layout_nms | 版面检测是否使用 NMS |
layout_unclip_ratio | 检测框扩张系数，同样支持标量/列表/字典 |
layout_merge_bboxes_mode | 重叠框合并策略，取值union/small/large（字典形式可按类别指定），合并计算由补丁后的calculate_overlap_ratio完成（paddleocr/_pipelines/_patch_layout_parsing.py#L35-L73） |
文本检测/识别类：
| 参数 | 说明 |
|---|---|
text_det_limit_side_len/text_det_limit_type | 文本检测输入图像边长限制及限制方式（min/max） |
text_det_thresh/text_det_box_thresh | 像素级与框级检测阈值 |
text_det_unclip_ratio | 文本检测区域扩张系数 |
text_rec_score_thresh | 文本识别置信度过滤阈值 |
text_detection_model_name/_dir、text_recognition_model_name/_dir、text_recognition_batch_size | OCR 模型指定与批大小 |
表格/印章/公式/图表模块：每个模块均提供*_model_name、*_model_dir、*_batch_size，印章另有seal_det_limit_side_len/_type/thresh/box_thresh/unclip_ratio与seal_rec_score_thresh；predict_iter还提供use_wired_table_cells_trans_to_html、use_wireless_table_cells_trans_to_html、use_table_orientation_classify、use_ocr_results_with_table_cells、use_e2e_wired_table_rec_model、use_e2e_wireless_table_rec_model等表格识别子产线开关（默认分别为 False/False/True/True/False/True）。
构造期语言与版本参数：lang、ocr_version（取值限于PP-OCRv3/PP-OCRv4/PP-OCRv5，否则抛出ValueError）。注意：当同时显式指定了检测/识别模型名或目录时，lang与ocr_version会被忽略并输出警告。
5. 使用方法和常见问题
Q：默认模型是什么配置？如果需要更高精度、更快速度、或更小显存，应该调哪些参数？A：默认模型均采用了各模块参数量最大的模型，第 3.3 节展示了不同模型选择对显存和推理速度的影响，可根据设备情况和样本难易程度选择合适的模型。在 Python API 或 CLI 中设置device为<设备类型>:<设备编号1>,<设备编号2>...（例如gpu:0,1,2,3）可实现多卡并行推理；若内置多卡并行提速仍不满足预期，可参考官方多进程并行推理文档，结合具体场景进一步优化。
Q：PP-StructureV3 是否可以在 CPU 上运行？A：更推荐在 GPU 环境下推理，但也支持 CPU 运行。得益于多种配置选项与对轻量级模型的优化，纯 CPU 环境可选用轻量化配置，例如在 Intel 8350C 上每张图片推理时间约为 3.74 秒（对应PP_StructureV3-lightweight配置）。
Q：如何将 PP-StructureV3 集成到自己的项目中？A：
- Python 项目：直接使用 PaddleOCR 的 Python API 集成（本文第 4.2 节）；
- 其他编程语言：建议通过服务化部署方式集成，PaddleOCR 支持 C++、C#、Java、Go、PHP 等多种语言的客户端调用方式（仓库内即提供了 Go 客户端 api_sdk/go 与 TypeScript 客户端 api_sdk/typescript 示例与实现）；
- 若需与大模型交互，PaddleOCR 还提供 MCP 服务，仓库内对应实现见 mcp_server。
Q：服务化部署可以并发处理请求吗？A：基础服务化部署方案同一时间只处理一个请求，主要用于快速验证、打通开发链路或不需并发的场景；高稳定性服务化部署方案默认同样是单请求，但可参考服务化部署指南通过调整配置实现水平扩展（第 3.2 节的多实例基准即展示了该扩展方式）。
Q：服务化部署如何降低时延、提升吞吐？A：两种服务化部署方案都可以通过启用高性能推理插件提升模型推理速度、降低时延；对于高稳定性部署方案，通过调整服务配置设置多个实例，可以充分利用部署机器资源、有效提升吞吐。
6. 延伸阅读
- 产线完整使用教程（含各模块模型列表与下载）：PP-StructureV3 产线使用教程
- 各子模块文档：版面区域检测、文本检测、文本识别、公式识别、表格结构识别、图表解析
- 源码与测试：产线封装、CLI 工具函数、参数透传测试
【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
