PaddleOCR 文档智能解析实战指南：从 PaddleOCR-VL、PP-StructureV3 到 PP-OCRv6 的 PDF/图像转结构化数据全攻略

PaddleOCR 文档智能解析实战指南：从 PaddleOCR-VL、PP-StructureV3 到 PP-OCRv6 的 PDF/图像转结构化数据全攻略

【免费下载链接】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

PaddleOCR 是当前开源生态中面向 AI 应用场景的 OCR 工具包与文档解析引擎，其核心目标是将 PDF 文档和图像高效转换为结构化、LLM 友好的数据格式（JSON / Markdown），为 RAG、Agentic 应用提供底层数据支撑。本文以仓库主文档 readme/README_cn.md 为骨架，结合仓库内的产线教程、核心源码与配置，系统讲解 PaddleOCR-VL 文档视觉语言模型、PP-StructureV3 版面解析产线、PP-OCRv6 通用文本识别，以及从环境安装、CLI/Python API 调用、结果保存到服务化部署的完整实战路径，读完即可在自己的项目中接入文档解析能力。

1. PaddleOCR 能做什么：三大能力体系

从 readme/README_cn.md 的「核心特性」章节可以看出，PaddleOCR 的能力可以划分为三条主线，分别面向不同的开发者场景：

三者并非割裂：PP-StructureV3 产线内部就复用了通用 OCR 子产线（文本检测 + 文本识别），而 PaddleOCR-VL 则采用「版面分析 + VLM 识别」两阶段架构。下文分别展开。

2. PaddleOCR-VL：面向文档解析的轻量级视觉语言模型

2.1 模型定位与两阶段工作流程

PaddleOCR-VL 是 PaddleOCR 推出的先进文档解析模型，专为文档中的元素识别设计。以其初代版本为例，核心组件为 PaddleOCR-VL-0.9B：一个由 NaViT 风格动态分辨率视觉编码器与 ERNIE-4.5-0.3B 语言模型组成的紧凑视觉语言模型（VLM）。

根据 PaddleOCR-VL 使用教程，完整的 PaddleOCR-VL 流程由两个阶段组成：

1. 版面分析阶段：以整张图像作为输入，检测并定位图像中的各类版面元素（表格、公式、标题、文本、图像等），同时确定阅读顺序，并依据检测结果裁剪出对应的元素子图。以 v1 为例，版面分析模型为 PP-DocLayoutV2。
2. VLM 识别阶段：将每个元素子图独立输入 VLM，生成对应识别结果（如 Markdown 文本），再按照版面分析阶段给出的顺序合并各元素结果，得到整幅图像的完整解析结果。

这里有一个必须澄清的概念：PaddleOCR-VL 的完整能力依赖「版面分析 + VLM 识别」协同的完整流程，而非仅使用其中的 VLM 组件。例如直接通过 Transformers 本地执行 PaddleOCR-VL-0.9B 模型，或直接请求 vLLM / SGLang / FastDeploy 服务，都不等同于运行完整的 PaddleOCR-VL 流程。若出现无法复现官方精度、模型输出大量幻觉文本等问题，应首先确认是否走的是完整流程。这一点在 PaddleOCR-VL 教程 中被特别强调。

从源码结构看，完整流程在仓库中的实现入口位于 paddleocr/_pipelines/paddleocr_vl.py，其PaddleOCRVL类的__init__与predict方法同时接收版面分析参数（layout_detection_model_name、layout_threshold、layout_nms、layout_merge_bboxes_mode等）与 VLM 推理参数（vl_rec_model_name、temperature、top_p、min_pixels、max_pixels、max_new_tokens等），从 API 层面印证了两阶段架构。该类的restructure_pages方法还支持merge_tables（跨页表格合并）、relevel_titles（多级标题重建）、concatenate_pages（多页结果合并）等后处理能力。

2.2 版本演进与关键指标

根据 readme/README_cn.md 的版本动态与 PaddleOCR-VL 教程 的说明，PaddleOCR-VL 系列的演进脉络如下：

说明：以上精度数字均为官方文档公示的基准测试结果，具体评测集与口径以 PaddleOCR-VL 教程 与主文档为准。

产线版本通过pipeline_version参数控制，可选值为"v1"、"v1.5"和"v1.6"，默认"v1.6"（见 PaddleOCR-VL 教程）。

2.3 环境准备：Docker 镜像与手动安装

根据 PaddleOCR-VL 教程 第 1 节，本地运行环境有两种准备方式，官方强烈推荐 Docker 方案以最小化环境问题。

方法一：官方 Docker 镜像（仅 NVIDIA GPU）

要求 Docker 版本 ≥ 19.03，机器装配有 GPU 且 NVIDIA 驱动支持 CUDA 12.6 或以上：

docker run \ -it \ --gpus all \ --network host \ --user root \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-nvidia-gpu \ /bin/bash # 在容器中调用 PaddleOCR CLI 或 Python API

离线环境可使用后缀为-offline的镜像（约 10 GB），通过在联网机器上docker pull、docker save导出为 tar 文件，再在离线机器docker load后启动。镜像标签支持将latest替换为版本号（如paddleocr3.3-nvidia-gpu-offline）以固定版本。

方法二：手动安装推理引擎与 PaddleOCR

文档验证的 Python 版本范围为 3.9–3.13，强烈建议在虚拟环境中安装：

# 创建并激活虚拟环境 python -m venv .venv_paddleocr source .venv_paddleocr/bin/activate # 安装飞桨（注意：不允许同时安装 CPU 和 GPU 版本） # NVIDIA GPU（以 CUDA 12.6 为例） python -m pip install paddlepaddle-gpu==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/ # x64 CPU python -m pip install paddlepaddle==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ # 安装 PaddleOCR 文档解析依赖组 python -m pip install -U "paddleocr[doc-parser]"

如需使用transformers引擎，则按 Transformers 官方文档 安装后，在 CLI 中追加--engine transformers，或在 Python API 初始化时传入engine="transformers"。

PaddleOCR-VL 推理方式与硬件支持矩阵（节选自 PaddleOCR-VL 教程）：

其中✅表示支持，🚧表示适配中或待进一步验证，❌表示当前不支持。PaddlePaddle + vLLM这类格式表示「版面分析模型在客户端本地用飞桨推理 + VLM 由独立推理服务承担」。需要注意的是，vLLM、SGLang 和 FastDeploy 无法在 Windows 上原生运行，需要使用官方 Docker 镜像；不同推理引擎间存在依赖冲突时，通常需要将版面分析模型与 VLM 服务部署在不同环境。

2.4 CLI 快速开始

首次运行时 PaddleOCR-VL 会自动下载官方模型，需保证联网并预留下载与初始化时间。建议附加--save_path ./output保存结果：

# NVIDIA GPU paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png --save_path ./output # 昆仑芯 XPU / 海光 DCU / 沐曦 GPU / Apple Silicon # paddleocr doc_parser -i <图片URL或路径> --device xpu --save_path ./output # paddleocr doc_parser -i <图片URL或路径> --device dcu --save_path ./output # paddleocr doc_parser -i <图片URL或路径> --device metax_gpu --save_path ./output # paddleocr doc_parser -i <图片URL或路径> --device cpu --save_path ./output # 按需开关子模块 paddleocr doc_parser -i <图片> --use_doc_orientation_classify True --save_path ./output paddleocr doc_parser -i <图片> --use_doc_unwarping True --save_path ./output paddleocr doc_parser -i <图片> --use_layout_detection False --save_path ./output # 切换到 transformers 引擎 paddleocr doc_parser -i <图片> --engine transformers --save_path ./output

常用 CLI 参数（详见 PaddleOCR-VL 教程 参数表）：

执行成功后终端会打印结构化结果，设置了--save_path时结果文件同步保存到本地 output 目录。

2.5 Python API 集成

几行代码即可完成 PaddleOCR-VL 的快速推理（示例取自 PaddleOCR-VL 教程）：

from pathlib import Path from paddleocr import PaddleOCRVL output_dir = Path("./output") output_dir.mkdir(parents=True, exist_ok=True) # NVIDIA GPU（默认） pipeline = PaddleOCRVL() # pipeline = PaddleOCRVL(device="xpu") # 昆仑芯 XPU # pipeline = PaddleOCRVL(device="dcu") # 海光 DCU # pipeline = PaddleOCRVL(device="metax_gpu") # 沐曦 GPU # pipeline = PaddleOCRVL(device="cpu") # Apple Silicon # 按需开关子模块 # pipeline = PaddleOCRVL(use_doc_orientation_classify=True) # pipeline = PaddleOCRVL(use_doc_unwarping=True) # pipeline = PaddleOCRVL(use_layout_detection=False) output = pipeline.predict( "https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png" ) for res in output: res.print() ## 打印预测的结构化输出 res.save_to_json(save_path=output_dir) ## 保存 JSON 结果 res.save_to_markdown(save_path=output_dir) ## 保存 Markdown 结果 res.save_to_word(save_path=output_dir) ## 保存 Word 结果

切换到transformers引擎只需在初始化时传入engine="transformers"。多页 PDF 长文档后处理是文档解析的高频需求，PaddleOCR-VL 教程 提供了restructure_pages的完整用法：

from pathlib import Path from paddleocr import PaddleOCRVL input_file = "./your_pdf_file.pdf" output_dir = Path("./output") output_dir.mkdir(parents=True, exist_ok=True) pipeline = PaddleOCRVL() output = pipeline.predict(input=input_file) pages_res = list(output) output = pipeline.restructure_pages(pages_res) # output = pipeline.restructure_pages(pages_res, merge_tables=True) # 合并跨页表格 # output = pipeline.restructure_pages(pages_res, merge_tables=True, relevel_titles=True) # 合并跨页表格 + 重建多级标题 # output = pipeline.restructure_pages(pages_res, merge_tables=True, relevel_titles=True, concatenate_pages=True) # 合并跨页表格 + 重建多级标题 + 合并多页结果 for res in output: res.print() res.save_to_json(save_path=output_dir) res.save_to_markdown(save_path=output_dir)

批量处理建议：处理多个文件时，将目录路径或文件路径列表直接传给predict，其处理效率高于逐个文件循环调用predict：

# 传入目录路径 output = pipeline.predict("imgs") # 或传入文件路径列表 output = pipeline.predict(["imgs/file1.png", "imgs/file2.png", "imgs/file3.png"])

3. PP-StructureV3：细粒度坐标 + 强版面能力的解析产线

3.1 产线组成

与 PaddleOCR-VL「端到端 VLM」的路线不同，PP-StructureV3 是模块化拼装产线，提供更细粒度的坐标信息（包括表格单元格坐标、文本坐标等）。根据 PP-StructureV3 产线教程，产线包含 7 个模块或子产线：

产线在通用版面解析 v1 基础上，强化了版面区域检测、表格识别、公式识别能力，并新增图表理解、多栏阅读顺序恢复、结果转 Markdown 等能力。版面检测模型 PP-DocLayout_plus-L 覆盖 20 个常见类别：文档标题、段落标题、文本、页码、摘要、目录、参考文献、脚注、页眉、页脚、算法、公式、公式编号、图像、表格、图和表标题、印章、图表、侧栏文本和参考文献内容。

从源码看，其实现位于 paddleocr/_pipelines/pp_structurev3.py，PPStructureV3类的构造函数参数横跨版面、OCR、表格、印章、公式、图表等全模块（含use_table_recognition、use_formula_recognition、use_chart_recognition、use_region_detection等开关），与文档所述 7 模块结构一一对应。

3.2 Python API 与引擎切换

from paddleocr import PPStructureV3 pipeline = PPStructureV3() # pipeline = PPStructureV3(lang="en") # 切换英文识别模型，默认中英文 # pipeline = PPStructureV3(use_doc_orientation_classify=True) # pipeline = PPStructureV3(use_doc_unwarping=True) # pipeline = PPStructureV3(use_textline_orientation=True) # pipeline = PPStructureV3(device="gpu") output = pipeline.predict("./pp_structure_v3_demo.png") for res in output: res.print() res.save_to_json(save_path="output") res.save_to_markdown(save_path="output") res.save_to_word(save_path="output")

推理引擎切换（示例取自 PP-StructureV3 教程）：

# transformers 引擎 pipeline = PPStructureV3(engine="transformers") # onnxruntime 引擎（部分模型尚在支持中，需关闭公式识别） pipeline = PPStructureV3(engine="onnxruntime", use_formula_recognition=False)

默认使用本地飞桨推理引擎时，各模块会根据默认模型名称自动选择：仅支持动态图的模型使用paddle_dynamic；同时支持静态图和动态图的模型优先使用paddle_static。运行前需先安装 PaddlePaddle，见 飞桨框架安装说明。

多页 PDF 整体转 Markdown：

from pathlib import Path from paddleocr import PPStructureV3 input_file = "./your_pdf_file.pdf" output_path = Path("./output") pipeline = PPStructureV3() output = pipeline.predict(input=input_file) # 对多页结果进行跨页表格合并、标题重建等后处理，再逐页保存为 Markdown/JSON

4. PP-OCRv6 与通用文本识别产线

4.1 产线模块与默认模型

通用 OCR 产线用于解决文字识别任务，支持 PP-OCRv3/v4/v5/v6 系列模型，默认模型为 PaddleOCR 3.7 发布的PP-OCRv6_medium。根据 通用 OCR 产线教程，产线包含 5 个模块：

• 文档图像方向分类模块（可选）：PP-LCNet_x1_0_doc_ori，Top-1 Acc 99.06%，四类别（0°/90°/180°/270°）
• 文本图像矫正模块（可选）：UVDoc，高精度矫正模型
• 文本行方向分类模块（可选）：PP-LCNet_x0_25_textline_ori（Top-1 Acc 98.85%）与 PP-LCNet_x1_0_textline_ori（Top-1 Acc 99.42%）
• 文本检测模块（必选）：PP-OCRv6 提供 tiny/small/medium 三档检测模型
• 文本识别模块（必选）：同样提供 tiny/small/medium 三档识别模型

PP-OCRv6 基于全新设计的 PPLCNetV4 统一骨干网络，从 readme/README_cn.md 与 PP-OCRv6 算法文档 可以确认其关键特性：

• 三档模型覆盖全场景：tiny（1.5M 参数）/ small（7.7M）/ medium（34.5M），分别面向端侧、移动端、服务端部署
• 50 种语言统一支持：单一模型覆盖中文、英文、日文及 46 种拉丁语系，无需按语种切换模型
• 精度与速度：medium 档相比 PP-OCRv5_server 检测精度提升 4.6%、识别精度提升 5.1%；medium 档 CPU OpenVINO 推理加速 5.2×，tiny 档 Apple M4 加速 6.1×
• 专业场景增强：数码显示屏、点阵字符、轮胎印字、工业字符等传统 VLM 难以覆盖的场景识别能力大幅提升

注意：通用 OCR 产线教程 中特别注明，PP-OCRv6 指标基于内部多场景评估集测得，PP-OCRv5/v4 指标基于通用评估集测得，两者评估集不同，指标不可直接对比。

4.2 模型选择参考（节选自 OCR 产线教程）

文本检测模块：

文本识别模块（核心模型节选）：

文本识别模块共支持 20 个全量模型，涵盖中文、英文、韩文、拉丁文、东斯拉夫语言、泰语、希腊语、阿拉伯语、天城文、泰卢固文等多种语言，另有 SVTRv2、RepSVTR、PP-OCRv4 系列等模型可选。

4.3 通用 OCR 产线调用

CLI 方式（通用 OCR 产线教程 第 2 节）：

# 默认使用 PP-OCRv6_medium 模型组合 paddleocr ocr -i <图片路径或URL> --save_path ./output # 指定语言与设备 # paddleocr ocr -i <图片> --lang en --device gpu --save_path ./output

Python API 方式：

from paddleocr import PaddleOCR pipeline = PaddleOCR() # pipeline = PaddleOCR(lang="en") # 切换语言 # pipeline = PaddleOCR(device="gpu") # 使用 GPU output = pipeline.predict(<图片路径或URL>) for res in output: res.print() res.save_to_json(save_path="output")

对应产线实现位于 paddleocr/_pipelines/ocr.py，PaddleOCR的predict_iter支持在调用时动态覆盖use_doc_orientation_classify、use_doc_unwarping、use_textline_orientation、text_det_thresh、text_det_box_thresh、text_rec_score_thresh、return_word_box等参数——其中return_word_box对应 README 中提到的「PP-OCR 系列模型支持返回单文字坐标」特性。

5. 安装与依赖组选择

根据 安装文档，paddleocr包支持按能力域选择可选依赖组，避免一次性安装全部重依赖：

# 仅通用 OCR（Python 3.8+） python -m pip install paddleocr # 文档解析（需要 Python 3.9+） python -m pip install "paddleocr[doc-parser]" # 完整能力 python -m pip install "paddleocr[all]"

Python 版本要求：paddleocr本体与doc2md依赖组支持 Python 3.8 及以上；doc-parser、ie、trans、all等受上游依赖限制，需要 Python 3.9 及以上。模型训练与模型导出需另行按 飞桨框架安装 安装飞桨并执行python -m pip install -r requirements.txt。

6. 服务化部署与多端集成

6.1 服务化部署方案

根据 服务化部署文档，PaddleOCR 推荐基于 PaddleX 进行服务化部署，提供两种方案：

• 基础服务化部署：简单易用、开发成本低，适合快速验证与打通开发链路（单请求串行处理）。
• 高稳定性服务化部署：基于 NVIDIA Triton Inference Server 打造，稳定性更高，允许调整配置水平扩展实例以提升吞吐（可通过手动构造 HTTP 请求调用，客户端代码可用任意编程语言编写）。

生产环境建议使用专门的 VLM 推理服务（如 vLLM、SGLang、FastDeploy）而非本地直推，以获得更好的推理速度、显存占用与稳定性表现。PaddleOCR-VL 相关的 Docker 编排与高吞吐方案见 deploy/paddleocr_vl_docker 目录（含pipeline_config_vllm.yaml、pipeline_config_fastdeploy.yaml等配置）。

6.2 多语言客户端与多端 SDK

仓库提供了丰富的多端集成方式：

• 官方 API SDK：Go 客户端见 api_sdk/go，TypeScript 客户端见 api_sdk/typescript；Python 侧还有异步/同步 API 客户端 paddleocr/_api_client（含PaddleOCRClient与AsyncPaddleOCRClient）
• C++ 推理：deploy/cpp_infer
• Android：deploy/ppocr-android 与 deploy/android_demo
• iOS：deploy/ios_demo
• 浏览器端：PaddleOCR.js官方浏览器推理 SDK，支持在浏览器中运行 PP-OCRv5，见 paddleocr-js
• MCP 服务器：面向 LLM Agent 的 mcp_server 与 LangChain 集成

PaddleOCR-VL 系列、PP-StructureV3 与 PP-DocTranslation 已支持将解析结果导出为 DOCX，便于在 Microsoft Word 中查看和编辑；同时支持将 Word、Excel、PowerPoint 等常见文档格式转换为 Markdown（doc2md_convert，见 paddleocr/init.py）。

7. 官方在线体验与进一步学习路径

• 在线体验：PaddleOCR 官方网站提供交互式体验中心与 APIs，无需本地设置即可一键体验文档解析效果。
• 产线教程清单（仓库内完整路径）：
  • PaddleOCR-VL 使用教程
  • PP-StructureV3 产线教程
  • 通用 OCR 产线教程
  • 表格识别子产线、公式识别子产线、印章识别子产线、文档预处理子产线
  • 产线总览
• 更多能力：ONNX 模型转换见 获取 ONNX 模型；OpenVINO、ONNX Runtime、TensorRT 等高性能推理见 高性能推理；多 GPU/多进程并行推理见 流水线并行推理。
• 引用方式：如论文引用，可参考 readme/README_cn.md 文末的 BibTeX 条目（PaddleOCR 3.0 Technical Report 与 PaddleOCR-VL 系列论文）。

总结

本文以 readme/README_cn.md 为主线，系统梳理了 PaddleOCR 面向 AI 应用的三条能力路径：以 PaddleOCR-VL（两阶段「版面分析 + VLM」架构）与 PP-StructureV3（7 模块模块化产线）为核心的文档智能解析，以 PP-OCRv6 为代表的通用多语言场景 OCR，以及围绕二者的安装、调用、结果导出与服务化部署全链路。开发者可按需选择：追求端到端快速解析选 PaddleOCR-VL，需要细粒度坐标与模块化定制选 PP-StructureV3，纯文本识别选通用 OCR 产线，生产环境则优先考虑服务化部署方案。

【免费下载链接】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