PaddleOCR 3.x 技术指南：将 PDF 与图像文档转化为 LLM 可用结构化数据的 OCR 与文档解析工具链-平芜编程栈

PaddleOCR 3.x 技术指南：将 PDF 与图像文档转化为 LLM 可用结构化数据的 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

PaddleOCR 是一个将 PDF 文档和图像转换为结构化、LLM 就绪数据（JSON/Markdown）的 OCR 与文档智能工具集。本文基于仓库根目录的 README.md 展开，结合 paddleocr 包源码、安装文档与快速上手文档，系统讲解其核心能力（PP-OCRv6 通用文字识别、PP-StructureV3 版面解析、PaddleOCR-VL 视觉语言模型、doc2md 办公文档转换）、命令行与 Python 双接口的具体用法，以及从源码层面确认的模型自动选择逻辑与参数映射机制，帮助读者完成从安装到产线调用的完整落地。

核心定位与能力版图

README 将 PaddleOCR 定位为面向 LLM 时代的文档解析引擎，覆盖两大核心场景：

1. 智能文档解析（LLM-Ready Document Parsing）

PaddleOCR-VL 系列视觉语言模型：以 PaddleOCR-VL-1.6（0.9B 参数）为代表，README 称其在 OmniDocBench v1.6 上取得 96.3% 的准确率，在文本、公式、表格识别上保持领先，并在古籍、生僻字、印章、图表理解上显著增强，输出支持Markdown与JSON两种结构化格式。
PP-StructureV3：将复杂 PDF 和图像转换为 Markdown 或 JSON，与 PaddleOCR-VL 系列不同，它提供更细粒度的坐标信息——包括表格单元格坐标、文本坐标等，适合需要精确定位下游信息的场景。
轻量高效：以小模型 footprint 达到商用级精度，适合边缘与云端部署。

2. 通用文字识别（场景 OCR）

100+ 语言支持：其中PP-OCRv6 以单一统一模型覆盖 50 种语言（中文、英文、日文及 46 种拉丁文字语言），多语言混排文档无需切换模型。
复杂元素识别：支持身份证件、街景、书籍、工业部件等自然场景下的文字检测与定位。
性能提升：README 声明 PP-OCRv6 相比 PP-OCRv5 检测精度 +4.6%、识别精度 +5.1%，端到端 CPU 推理提速 5.2 倍。

3. 开发者生态：与 Dify、RAGFlow、Pathway、Cherry Studio 等 AI Agent 生态项目深度集成；支持 NVIDIA GPU、Intel CPU、昆仑芯 XPU 等硬件后端的一键部署；提供面向 LLM 微调数据生产的完整 pipeline。

版本演进：从 3.2 到 3.7 的关键节点

README 的 Recent updates 段落记录了版本能力演进，按时间线梳理如下（均为 README 原文陈述）：

| 版本/日期 | 关键特性 | | - | - | |3.7.0 / 2026.07.22|HPD-Parsing高吞吐文档解析 VLM 上线：采用分层并行解码（hierarchical parallel decoding）与渐进式多 token 预测（P-MTP），公开基准峰值吞吐 4,752 tokens/s；支持 OpenAI 兼容 serving 与基于定制 vLLM 运行时的本地推理 | |3.7.0 / 2026.06.11|PP-OCRv6发布：medium 档（34.5M 参数）检测 +4.6%、识别 +5.1% 超越 PP-OCRv5_server；单模型统一 50 种语言；tiny(1.5M)/small(7.7M)/medium(34.5M) 三档覆盖边缘、移动与服务端；5.2× CPU 提速（OpenVINO）、Apple M4 tiny 档 6.1× 提速、A100 单样本 0.13s | |3.6.0 / 2026.05.28|PaddleOCR-VL-1.6：OmniDocBench v1.6 上 96.3%+；表格、古籍、生僻字能力升级，印章识别与定位、图表理解增强；架构与 VL-1.5 完全一致，可零成本替换迁移 | |3.5.0 / 2026.04.21| 灵活推理后端：Paddle 静态图/动态图/Transformers 三选一，20 个主流模型支持 Transformers 后端；Office 文档转 Markdown（Word/Excel/PPT）；PaddleOCR-VL、PP-StructureV3、PP-DocTranslation支持导出 DOCX；发布官方浏览器推理 SDKPaddleOCR.js（浏览器内直接运行 PP-OCRv5） | |3.4.0 / 2026.01.29| PaddleOCR-VL-1.5（0.9B SOTA VLM）：OmniDocBench 94.5%；首推 PP-DocLayoutV3 算法应对倾斜、弯折、扫描、光照、屏幕拍照五类难场景；新增印章识别、Text Spotting，语言扩展至 111 种；支持跨页表格自动合并与层级标题识别 | |3.3.0 / 2025.10.16| PaddleOCR-VL 初代发布（NaViT 风格动态分辨率视觉编码器 + ERNIE-4.5-0.3B，支持 109 种语言）；PP-OCRv5 多语言识别模型覆盖 109 种语言，仅 2M 参数 | |3.2.0 / 2025.08.21| PP-OCRv5 英/泰/希腊识别模型（英文场景较主模型 +11%）；全量支持飞桨 3.1.x；PP-OCRv5 C++ 本地部署支持 Linux/Windows；CUDA 12 高性能推理（Paddle Inference / ONNX Runtime 双后端）；服务端部署方案全开源；全线支持细粒度 benchmark；核心依赖与可选依赖拆分 |

安装：核心依赖与可选能力域

安装方式

paddleocr 包定义了最小核心依赖（paddlex[ocr-core]>=3.7.0,<3.8.0、PyYAML、requests、aiohttp、typing-extensions），要求 Python ≥ 3.8，并通过[project.scripts]注册paddleocr命令行入口（映射到 paddleocr.main:console_entry）。

# 仅通用 OCR 与文档图像预处理等默认能力 python -m pip install paddleocr # 需要文档解析、文档理解、文档翻译、关键信息抽取等全部可选能力 python -m pip install "paddleocr[all]"

按能力域选择依赖组

从 pyproject.toml 的optional-dependencies与安装文档可确认各依赖组与功能域的一一对应关系：

通用 OCR 产线与文档图像预处理产线无需额外依赖组。需注意：doc2md依赖组支持 Python 3.8+，其余依赖组受上游限制需 Python 3.9+。

推理引擎

PaddleOCR 3.5 起采用统一推理引擎配置，底层可在PaddlePaddle与Transformers之间切换。使用 PaddlePaddle 推理时，PaddleOCR 3.x 依赖 3.0 及以上版本的飞桨框架；使用 Transformers 后端时需安装transformers>=5.8.0。详见安装文档。

快速上手：命令行与 Python 双接口

命令行使用

安装完成后，paddleocr命令提供ocr、text_detection、text_recognition、pp_structurev3等子命令。以下命令来自快速上手文档：

# PP-OCRv6 完整 OCR 产线（PaddlePaddle 推理） paddleocr ocr -i ./general_ocr_002.png \ --use_doc_orientation_classify False \ --use_doc_unwarping False \ --use_textline_orientation False \ --engine paddle # PP-OCRv6 文本检测单模块 paddleocr text_detection -i ./general_ocr_001.png --engine paddle # PP-OCRv6 文本识别单模块 paddleocr text_recognition -i ./general_ocr_rec_001.png --engine paddle # PP-StructureV3 文档解析产线 paddleocr pp_structurev3 -i ./pp_structure_v3_demo.png \ --use_doc_orientation_classify False \ --use_doc_unwarping False \ --engine paddle

使用 Transformers 后端时仅需将--engine paddle替换为--engine transformers；注意 PP-StructureV3 在 Transformers 后端下部分模型尚在支持中，需关闭公式识别并指定无线表格结构识别模型（--use_formula_recognition False --wireless_table_structure_recognition_model_name SLANeXt_wireless）。

Python 脚本使用

paddleocr 包的__init__导出了完整的公开 API 面：产线类（PaddleOCR、PaddleOCRVL、PPStructureV3、PPDocTranslation、PPChatOCRv4Doc、DocUnderstanding、DocPreprocessor、FormulaRecognitionPipeline、SealRecognition、TableRecognitionPipelineV2等）、单模型类（TextDetection、TextRecognition、LayoutDetection、TableStructureRecognition、FormulaRecognition、ChartParsing等）、API 客户端（PaddleOCRClient、AsyncPaddleOCRClient）以及文档转换函数doc2md_convert。

通用 OCR 产线（PP-OCRv6 默认）：

from paddleocr import PaddleOCR ocr = PaddleOCR( use_doc_orientation_classify=False, # 关闭文档方向分类 use_doc_unwarping=False, # 关闭文档弯页矫正 use_textline_orientation=False, # 关闭文本行方向分类 engine="paddle", # 推理引擎：paddle / transformers ) result = ocr.predict("./general_ocr_002.png") for res in result: res.print() # 打印结构化结果 res.save_to_img("output") # 保存可视化标注图 res.save_to_json("output") # 保存 JSON 结果

结果字典包含rec_texts（识别文本）、rec_scores（置信度）、dt_polys/rec_polys（多边形坐标）、rec_boxes（边界框）以及text_det_params（检测超参数快照）等字段。

单模块调用：

from paddleocr import TextDetection, TextRecognition model = TextDetection(engine="paddle") output = model.predict("general_ocr_001.png") rec_model = TextRecognition(engine="paddle") output = rec_model.predict(input="general_ocr_rec_001.png")

PP-StructureV3 文档解析产线：

from paddleocr import PPStructureV3 pipeline = PPStructureV3( use_doc_orientation_classify=False, use_doc_unwarping=False, engine="paddle", ) output = pipeline.predict(input="./pp_structure_v3_demo.png") for res in output: res.print() res.save_to_json(save_path="output") # 结构化 JSON（含细粒度坐标） res.save_to_markdown(save_path="output") # Markdown 文档

PP-StructureV3 的构造参数在 pp_structurev3.py 中完整暴露，涵盖版面检测（layout_detection_model_name、layout_threshold、layout_nms等）、表格识别（有线/无线双模型：wired_table_structure_recognition_model_name、wireless_table_structure_recognition_model_name）、印章识别（use_seal_recognition、seal_text_detection_model_name等）、公式识别（use_formula_recognition）与图表识别（use_chart_recognition）等能力开关，并支持format_block_content、markdown_ignore_labels等 Markdown 输出控制项——这正是 README 所述"更细粒度坐标信息"的落点。

Office 文档转 Markdown

3.5 版本引入的doc2md能力由 paddleocr/_doc2md 实现：通过default_registry按文件扩展名路由到对应的转换器，入口函数为包级导出的doc2md_convert：

from paddleocr import doc2md_convert result = doc2md_convert("report.docx") print(result.markdown)

该能力依赖doc2md依赖组（python-docx、python-pptx、openpyxl、pylatexenc）。

源码剖析：模型自动选择与产线内部结构

语言到模型的自动路由

PaddleOCR 产线实现中，当用户未显式指定检测/识别模型时，_get_ocr_model_names方法会根据lang与ocr_version参数自动解析模型名。从源码可以确认如下路由逻辑（ocr.py）：

默认（lang=None, ocr_version=None）：直接使用PP-OCRv6_medium_det+PP-OCRv6_medium_rec，即默认走 PP-OCRv6 中等档模型；
ocr_version=None且指定lang：若语言属于_PPOCRV6_LANGS（中/繁中/英/日 + 全部拉丁语系，剔除pi），自动选 PP-OCRv6；韩语、泰语、希腊语、天城文/阿拉伯/西里尔文系语言则回落到 PP-OCRv5 对应语种模型（如latin_PP-OCRv5_mobile_rec、eslav_PP-OCRv5_mobile_rec）；卡纳达语（ka）回落至 PP-OCRv3；
显式指定版本：PP-OCRv5 中文/繁中/日文使用PP-OCRv5_server_rec，英文使用en_PP-OCRv5_mobile_rec；PP-OCRv4 仅覆盖中英；PP-OCRv3 按语种选择{rec_lang}_PP-OCRv3_mobile_rec。

ocr_version的合法取值为["PP-OCRv3", "PP-OCRv4", "PP-OCRv5", "PP-OCRv6"]（见 ocr.py），传入其他值会直接抛出ValueError；语言组常量定义在 paddleocr/_utils/langs.py 中，按拉丁、斯拉夫、阿拉伯、西里尔、天城文等文字体系分组，印证了 README 关于多语言覆盖的实现方式。

2.x 兼容参数映射

PaddleOCR 3.x 的 Python 接口刻意保留了 2.x 的参数名兼容性。源码中的_DEPRECATED_PARAM_NAME_MAPPING（ocr.py）定义了 2.x 参数到新命名的映射，例如det_model_dir → text_detection_model_dir、use_angle_cls → use_textline_orientation、cls_model_dir → textline_orientation_model_dir。传入旧参数名时仅触发弃用警告并被自动翻译，而新旧参数同时传入则抛出互斥错误。命令行子命令同样通过DeprecatedOptionAction注册了对应的--det_model_dir等废弃选项。

参数如何落到产线配置

从源码结构看，PaddleOCR继承自PaddleXPipelineWrapper，其_paddlex_pipeline_name属性返回"OCR"，即本包是 PaddleX 底层产线的薄封装层。_get_paddlex_config_overrides方法（ocr.py）将用户传入的参数按产线配置路径逐项覆盖，例如：

text_det_thresh→SubModules.TextDetection.thresh
text_det_box_thresh→SubModules.TextDetection.box_thresh
text_det_unclip_ratio→SubModules.TextDetection.unclip_ratio
use_doc_orientation_classify或use_doc_unwarping任一为真时，自动启用use_doc_preprocessor子产线

这意味着用户级参数最终被精确注入到 PaddleX 的产线 YAML 配置结构中，predict返回的是包含model_settings（生效参数快照）、doc_preprocessor_res、dt_polys、rec_texts等字段的完整结果对象，与快速上手文档中展示的输出示例一致。

服务化与多语言生态

官方 API 客户端

除本地推理外，paddleocr包内置官方 API 客户端 PaddleOCRClient（及异步版AsyncPaddleOCRClient）：内部封装"提交任务 → 轮询 → 拉取结果"的异步作业流，token 支持显式传参或从PADDLEOCR_ACCESS_TOKEN环境变量读取，服务地址可通过PADDLEOCR_BASE_URL覆盖，并提供细粒度的异常体系（AuthError、RateLimitError、PollTimeoutError、JobFailedError等，见 paddleocr/_api_client）。配套的多语言客户端 SDK 位于 api_sdk/，包含 Go 与 TypeScript 两套完整实现。

部署与集成生态

仓库中与文档能力直接相关的部署与集成资产包括：

deploy/：Android/iOS Demo、C++ 推理（cpp_infer/）、HubServing 服务端部署方案（hubserving/，支持手工构造 HTTP 请求实现任意语言客户端）、ONNX 转换（paddle2onnx/）、压缩/量化/剪枝（slim/）等；
mcp_server/：基于 PaddleOCR 的 MCP 服务器，将 OCR 能力暴露给 LLM Agent；
skills/：面向 AI Agent 的文档解析与文字识别技能定义；
paddleocr-js/：官方浏览器推理 SDK（PaddleOCR.js），对应 3.5 版本发布说明中"浏览器内直接运行 PP-OCRv5"的能力；
langchain-paddleocr/：LangChain 集成包，提供文档加载器。

训练与模型导出

模型训练走独立安装路径：克隆仓库后执行python -m pip install -r requirements.txt安装训练依赖（requirements.txt），训练配置集中在 configs/ 目录下按 det/rec/cls/table 等任务组织（如 configs/det/PP-OCRv6/、configs/rec/PP-OCRv6/），入口工具为 tools/train.py、tools/eval.py 与 tools/export_model.py。训练侧的算法实现（数据增强、损失函数、后处理等）位于 ppocr/ 目录。

适用边界与使用建议

综合 README 与仓库证据，给出几点实操建议：

选型：追求极简部署与多语言混排场景选 PP-OCRv6 产线（PaddleOCR类）；需要表格/公式/印章细粒度坐标与 Markdown 输出选PPStructureV3；追求极限解析精度且可接受 VLM 推理成本选PaddleOCRVL；高吞吐批量解析可关注 3.7 引入的 HPD-Parsing；
依赖裁剪：只做通用 OCR 时安装裸paddleocr包即可，避免安装all依赖组引入的额外负担；
后端切换：同一份代码通过engine="paddle" | "transformers"切换推理后端，PP-StructureV3 在 Transformers 后端下需按上文说明调整模型与能力开关；
版本约束：当前仓库对应 PaddleX>=3.7.0,<3.8.0依赖区间，Python 本体支持 3.8+（可选依赖组需 3.9+），使用 PaddlePaddle 推理需飞桨 3.0+；
2.x 迁移：旧代码可继续传det_model_dir、use_angle_cls等旧参数名，会收到弃用警告并被自动映射，建议逐步迁移到新命名。