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/PaddleOCRPaddleOCR 是当前开源生态中面向 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 的能力可以划分为三条主线分别面向不同的开发者场景能力体系核心技术输出形态典型场景智能文档解析面向大模型PaddleOCR-VL 系列含 PaddleOCR-VL-1.6、PP-StructureV3Markdown / JSON论文、合同、报表、古籍等复杂文档转结构化数据喂给 LLM通用文本识别场景 OCRPP-OCR 系列v2/v3/v4/v5/v6文本行检测框 识别文本证件、街景、书籍、工业零部件等自然场景文字提取开发者生态与部署Python API、CLI、服务化部署、C/Android/iOS/JS 多端 SDKAPI 结果RAG 数据管线、Agent 工具链、边缘与云端部署三者并非割裂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 流程由两个阶段组成版面分析阶段以整张图像作为输入检测并定位图像中的各类版面元素表格、公式、标题、文本、图像等同时确定阅读顺序并依据检测结果裁剪出对应的元素子图。以 v1 为例版面分析模型为 PP-DocLayoutV2。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 (v1)2025.10随 3.3.0 发布页级文档解析与元素级识别达 SOTA支持 109 种语言NaViT 动态分辨率视觉编码器 ERNIE-4.5-0.3B低资源消耗PaddleOCR-VL-1.52026.01随 3.4.0 发布OmniDocBench v1.5 达 94.5%引入 PP-DocLayoutV3 异形框定位解决倾斜、弯曲、扫描、光线变化、屏幕拍照 5 类真实场景新增印章识别、文本行检测/识别扩展至 111 种语言PaddleOCR-VL-1.62026.05随 3.6.0 发布OmniDocBench v1.6 突破 96.3%表格、古籍、生僻字识别大幅提升印章、spotting、图表识别增强模型结构与 1.5 完全一致零成本迁移说明以上精度数字均为官方文档公示的基准测试结果具体评测集与口径以 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-gpu3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/ # x64 CPU python -m pip install paddlepaddle3.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 初始化时传入enginetransformers。PaddleOCR-VL 推理方式与硬件支持矩阵节选自 PaddleOCR-VL 教程推理方式NVIDIA GPU昆仑芯 XPU海光 DCU华为昇腾 NPUx64 CPUApple SiliconAMD GPUIntel Arc GPUPaddlePaddle✅✅✅✅✅✅Transformers✅✅PaddlePaddle vLLM✅✅✅❌❌✅✅PaddlePaddle FastDeploy✅✅❌❌PaddlePaddle MLX-VLM❌❌❌❌❌✅❌❌其中✅表示支持表示适配中或待进一步验证❌表示当前不支持。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 教程 参数表参数说明类型默认值input必填待预测数据支持本地图像/PDF 路径、URL 链接、本地目录目录模式不支持 PDFstr无save_path推理结果保存路径不设置则不落盘str无pipeline_version产线版本可选v1/v1.5/v1.6strv1.6layout_detection_model_name/layout_detection_model_dir版面分析模型名称 / 本地模型目录不设置则使用默认模型或自动下载str无layout_threshold版面模型得分阈值0-1 浮点数float初始化默认值layout_nms版面分析是否使用后处理 NMSbool初始化默认值use_doc_orientation_classify是否使用文档方向分类模块boolFalseuse_doc_unwarping是否使用文本图像矫正模块boolFalseuse_layout_detection是否使用版面分析模块关闭即退化为纯 VLM 直出boolTrue执行成功后终端会打印结构化结果设置了--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(parentsTrue, exist_okTrue) # NVIDIA GPU默认 pipeline PaddleOCRVL() # pipeline PaddleOCRVL(devicexpu) # 昆仑芯 XPU # pipeline PaddleOCRVL(devicedcu) # 海光 DCU # pipeline PaddleOCRVL(devicemetax_gpu) # 沐曦 GPU # pipeline PaddleOCRVL(devicecpu) # Apple Silicon # 按需开关子模块 # pipeline PaddleOCRVL(use_doc_orientation_classifyTrue) # pipeline PaddleOCRVL(use_doc_unwarpingTrue) # pipeline PaddleOCRVL(use_layout_detectionFalse) 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_pathoutput_dir) ## 保存 JSON 结果 res.save_to_markdown(save_pathoutput_dir) ## 保存 Markdown 结果 res.save_to_word(save_pathoutput_dir) ## 保存 Word 结果切换到transformers引擎只需在初始化时传入enginetransformers。多页 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(parentsTrue, exist_okTrue) pipeline PaddleOCRVL() output pipeline.predict(inputinput_file) pages_res list(output) output pipeline.restructure_pages(pages_res) # output pipeline.restructure_pages(pages_res, merge_tablesTrue) # 合并跨页表格 # output pipeline.restructure_pages(pages_res, merge_tablesTrue, relevel_titlesTrue) # 合并跨页表格 重建多级标题 # output pipeline.restructure_pages(pages_res, merge_tablesTrue, relevel_titlesTrue, concatenate_pagesTrue) # 合并跨页表格 重建多级标题 合并多页结果 for res in output: res.print() res.save_to_json(save_pathoutput_dir) res.save_to_markdown(save_pathoutput_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 个模块或子产线模块/子产线可选性关联文档仓库相对路径版面区域检测模块必选docs/version3.x/module_usage/layout_detection.md通用 OCR 子产线必选docs/version3.x/pipeline_usage/OCR.md文档图像预处理子产线可选docs/version3.x/pipeline_usage/doc_preprocessor.md表格识别子产线可选docs/version3.x/pipeline_usage/table_recognition_v2.md印章文本识别子产线可选docs/version3.x/pipeline_usage/seal_recognition.md公式识别子产线可选docs/version3.x/pipeline_usage/formula_recognition.md图表解析模块可选docs/version3.x/module_usage/chart_parsing.md产线在通用版面解析 v1 基础上强化了版面区域检测、表格识别、公式识别能力并新增图表理解、多栏阅读顺序恢复、结果转 Markdown 等能力。版面检测模型 PP-DocLayout_plus-L 覆盖 20 个常见类别文档标题、段落标题、文本、页码、摘要、目录、参考文献、脚注、页眉、页脚、算法、公式、公式编号、图像、表格、图和表标题、印章、图表、侧栏文本和参考文献内容。从源码看其实现位于 paddleocr/_pipelines/pp_structurev3.pyPPStructureV3类的构造函数参数横跨版面、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(langen) # 切换英文识别模型默认中英文 # pipeline PPStructureV3(use_doc_orientation_classifyTrue) # pipeline PPStructureV3(use_doc_unwarpingTrue) # pipeline PPStructureV3(use_textline_orientationTrue) # pipeline PPStructureV3(devicegpu) output pipeline.predict(./pp_structure_v3_demo.png) for res in output: res.print() res.save_to_json(save_pathoutput) res.save_to_markdown(save_pathoutput) res.save_to_word(save_pathoutput)推理引擎切换示例取自 PP-StructureV3 教程# transformers 引擎 pipeline PPStructureV3(enginetransformers) # onnxruntime 引擎部分模型尚在支持中需关闭公式识别 pipeline PPStructureV3(engineonnxruntime, use_formula_recognitionFalse)默认使用本地飞桨推理引擎时各模块会根据默认模型名称自动选择仅支持动态图的模型使用paddle_dynamic同时支持静态图和动态图的模型优先使用paddle_static。运行前需先安装 PaddlePaddle见 飞桨框架安装说明。多页 PDF 整体转 Markdownfrom pathlib import Path from paddleocr import PPStructureV3 input_file ./your_pdf_file.pdf output_path Path(./output) pipeline PPStructureV3() output pipeline.predict(inputinput_file) # 对多页结果进行跨页表格合并、标题重建等后处理再逐页保存为 Markdown/JSON4. PP-OCRv6 与通用文本识别产线4.1 产线模块与默认模型通用 OCR 产线用于解决文字识别任务支持 PP-OCRv3/v4/v5/v6 系列模型默认模型为 PaddleOCR 3.7 发布的PP-OCRv6_medium。根据 通用 OCR 产线教程产线包含 5 个模块文档图像方向分类模块可选PP-LCNet_x1_0_doc_oriTop-1 Acc 99.06%四类别0°/90°/180°/270°文本图像矫正模块可选UVDoc高精度矫正模型文本行方向分类模块可选PP-LCNet_x0_25_textline_oriTop-1 Acc 98.85%与 PP-LCNet_x1_0_textline_oriTop-1 Acc 99.42%文本检测模块必选PP-OCRv6 提供 tiny/small/medium 三档检测模型文本识别模块必选同样提供 tiny/small/medium 三档识别模型PP-OCRv6 基于全新设计的 PPLCNetV4 统一骨干网络从 readme/README_cn.md 与 PP-OCRv6 算法文档 可以确认其关键特性三档模型覆盖全场景tiny1.5M 参数/ small7.7M/ medium34.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 产线教程文本检测模块模型检测 Hmean%模型存储MB适用场景PP-OCRv6_medium_det86.2*59.4服务端部署精度最高PP-OCRv6_small_det84.1*9.6移动端部署PP-OCRv6_tiny_det80.6*1.9端侧/IoT0.43M 参数PP-OCRv5_server_det83.884.3性能较好的服务器PP-OCRv5_mobile_det79.04.7端侧设备文本识别模块核心模型节选模型识别 Avg Accuracy%模型存储MB说明PP-OCRv6_medium_rec83.2*73.3PP-OCRv6 中等规模识别模型PP-OCRv5_server_rec86.38中文81新一代识别模型支持简繁英日PP-OCRv5_mobile_rec81.29中文16移动端识别模型en_PP-OCRv5_mobile_rec85.257.5超轻量英文模型优化空格漏识别th_PP-OCRv5_mobile_rec82.687.5泰语识别el_PP-OCRv5_mobile_rec89.287.5希腊语识别arabic_PP-OCRv5_mobile_rec81.277.6阿拉伯语识别文本识别模块共支持 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 ./outputPython API 方式from paddleocr import PaddleOCR pipeline PaddleOCR() # pipeline PaddleOCR(langen) # 切换语言 # pipeline PaddleOCR(devicegpu) # 使用 GPU output pipeline.predict(图片路径或URL) for res in output: res.print() res.save_to_json(save_pathoutput)对应产线实现位于 paddleocr/_pipelines/ocr.pyPaddleOCR的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 与文档图像预处理doc-parser文档解析提取表格、公式、印章、图片等版面元素含 PP-StructureV3 等ie信息抽取从文档提取姓名、日期、地址、金额等关键信息含 PP-ChatOCRv4 等trans文档翻译含 PP-DocTranslation 等doc2md文档转 Markdown将 Word/Excel/PowerPoint 转为可读文本all完整功能# 仅通用 OCRPython 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 SDKGo 客户端见 api_sdk/goTypeScript 客户端见 api_sdk/typescriptPython 侧还有异步/同步 API 客户端 paddleocr/_api_client含PaddleOCRClient与AsyncPaddleOCRClientC 推理deploy/cpp_inferAndroiddeploy/ppocr-android 与 deploy/android_demoiOSdeploy/ios_demo浏览器端PaddleOCR.js官方浏览器推理 SDK支持在浏览器中运行 PP-OCRv5见 paddleocr-jsMCP 服务器面向 LLM Agent 的 mcp_server 与 LangChain 集成PaddleOCR-VL 系列、PP-StructureV3 与 PP-DocTranslation 已支持将解析结果导出为 DOCX便于在 Microsoft Word 中查看和编辑同时支持将 Word、Excel、PowerPoint 等常见文档格式转换为 Markdowndoc2md_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-StructureV37 模块模块化产线为核心的文档智能解析以 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考