PaddleOCR 3.x 全景指南从 PP-OCRv6 多语种识别到 PaddleOCR-VL 复杂文档解析【免费下载链接】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 3.x 是飞桨团队面向大模型时代重构的 OCR 与文档智能工具链本文以 docs/index.md 为骨架系统梳理 3.x 的核心能力矩阵PaddleOCR-VL、PP-OCRv6、PP-StructureV3、PP-ChatOCRv4、安装与命令行/Python 双形态使用方式、模块—产线架构及 2.x 升级注意事项并结合仓库源码与配置文件给出可验证的实战依据。读完本文你将掌握 PaddleOCR 3.x 从环境搭建、通用 OCR 推理到复杂文档解析、Agent Skills 集成的完整落地路径。一、PaddleOCR 3.x 版本演进与核心特色能力1.1 从 2.x 到 3.x一次非兼容性架构升级PaddleOCR 2.0 发布于 2021 年 2 月此后四年多持续演进。随着多语种识别、版面分析等需求爆发以轻量化为初衷的旧架构逐渐暴露出模块分支与桥接层膨胀、接口不统一、测试成本高、依赖滞后等问题。为此PaddleOCR 3.x 做了一次重大非兼容性升级详见 docs/update/upgrade_notes.md核心变化有三新增多条模型产线推出 PP-OCRv5/v6、PP-StructureV3、PP-ChatOCRv4 等产线重点增强多文字类型识别与手写体识别满足大模型应用对复杂文档高精度解析的需求重构部署能力、统一推理接口融合飞桨 PaddleX 底层能力参见 docs/version3.x/paddleocr_and_paddlex.md统一优化 Python API 与 CLI覆盖高性能推理、服务化部署与端侧部署适配飞桨 3.0兼容 CINN 编译器统一模型命名体系为训练与推理提速。从源码侧看这一架构重构直接体现在包结构上paddleocr/init.py 同时导出了PaddleOCR、PPStructureV3、PaddleOCRVL、PPChatOCRv4Doc等 9 条产线与 12 个基础模块类以及PaddleOCRClient/AsyncPaddleOCRClient两个云端 API 客户端——模块与产线的组织方式与文档描述一一对应。1.2 四大核心能力截至 2026 年 6 月能力一句话定位关键亮点来自官方文档表述PaddleOCR-VL0.9B 超紧凑视觉语言模型增强多语种文档解析支持 109 种语言1.5 版本在 OmniDocBench v1.5 达 94.5%1.6 版本2026-05-28 发布以 96.3% 刷新 OmniDocBench v1.6支持异形框定位、印章与 spotting 识别模型结构与 1.5 完全一致、可零成本迁移PP-OCRv6全场景多语言文字识别2026-06-11 发布基于 PPLCNetV4 统一骨干tiny/small/medium 三档1.5M~34.5M 参数单模型支持 50 种语言medium 档识别精度提升 5.1%、检测提升 4.6%CPU 端到端推理加速 5.2×PP-StructureV3复杂文档解析将复杂 PDF/文档图像转换为保留原始结构的 Markdown 与 JSON强化版面区域检测、表格识别、公式识别并具备图表理解、多栏阅读顺序恢复能力PP-ChatOCRv4智能信息抽取原生集成 ERNIE 4.5从海量文档中精准提取关键信息精度较上一代提升 15 个百分点1.3 生态与配套服务PaddleOCR OCEAN 生态联盟以 Open Source开源、Community社区、Ecosystem生态、Application应用、Network网络五大理念发起面向全球 OCR 及文档智能上下游伙伴开放可通过邮件 paddleocrbaidu.com 联系加入官方 Agent Skills提供paddleocr-text-recognition与paddleocr-doc-parsing两个 Skills详见 docs/version3.x/integrations/skills.md支持在 Claude Code、claude.ai、OpenClaw 等支持 Skills 的 AI 应用中调用仓库内实现位于 skills/paddleocr-doc-parsing/SKILL.md 与 skills/paddleocr-text-recognition/SKILL.mdMCP 服务仓库提供独立 MCP 服务器实现 mcp_server/可查阅 docs/version3.x/integrations/mcp_server.md云端 APIPaddleOCR 官网免费 API 的每日文档解析上限已提升至 20,000 页支持大批量 PDF 解析。⚠️版本匹配警告PaddleOCR 3.x 引入了大量接口变动基于 2.x 编写的旧代码很可能无法直接运行务必保证所读文档与所用版本一致。二、快速开始安装与两种推理引擎PaddleOCR 3.x 支持通过统一推理引擎配置选择底层运行时目前可使用PaddlePaddle或Transformers两种引擎在产线文档中还会看到onnxruntime选项。2.1 安装推理引擎方式一PaddlePaddle 引擎推荐性能更优# CPU 端 python -m pip install paddlepaddle3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ # GPU 端以 Linux CUDA 11.8 为例其他平台见飞桨官网安装文档 python -m pip install paddlepaddle-gpu3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/使用 PaddlePaddle 推理时PaddleOCR 3.x 依赖3.0 及以上版本的 PaddlePaddle。方式二Transformers 引擎python -m pip install transformers5.8.0通常还需按 Transformers 官方说明安装其底层推理框架。2.2 安装 paddleocr# 完整功能 python -m pip install paddleocr[all] # 仅 OCR 基础功能 pip install paddleocr2.3 环境验证import paddleocr print(fPaddleOCR版本: {paddleocr.__version__}) # paddle_static 引擎下可继续验证 Paddle 与 GPU import paddle print(fPaddle版本: {paddle.__version__}) print(fGPU可用: {paddle.is_compiled_with_cuda()}) print(fGPU数量: {paddle.device.cuda.device_count()}) # transformers 引擎下验证依赖 import transformers print(fTransformers版本: {transformers.__version__})2.4 常见安装问题依赖冲突建议新建虚拟环境例如conda create -n paddleocr python3.8 conda activate paddleocr后再安装GPU 配置先用nvidia-smi检查 CUDA 版本再安装对应版本的paddlepaddle-gpu模型下载失败设置环境变量切换下载源import os os.environ[PADDLE_PDX_MODEL_SOURCE] BOS # 使用百度云存储三、命令行使用一条命令跑通四条产线3.1 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 # Transformers 引擎 paddleocr ocr -i ./general_ocr_002.png \ --use_doc_orientation_classify False \ --use_doc_unwarping False \ --use_textline_orientation False \ --engine transformers3.2 PP-OCRv6 文本检测 / 文本识别单模块# 文本检测 paddleocr text_detection -i ./general_ocr_001.png --engine paddle paddleocr text_detection -i ./general_ocr_001.png --engine transformers # 文本识别 paddleocr text_recognition -i ./general_ocr_rec_001.png --engine paddle paddleocr text_recognition -i ./general_ocr_rec_001.png --engine transformers3.3 PP-StructureV3 复杂文档解析# PaddlePaddle 引擎 paddleocr pp_structurev3 -i ./pp_structure_v3_demo.png \ --use_doc_orientation_classify False \ --use_doc_unwarping False \ --engine paddle # Transformers 引擎部分模型尚在支持中需关闭公式识别并更换无线表格模型 paddleocr pp_structurev3 -i ./pp_structure_v3_demo.png \ --engine transformers \ --use_formula_recognition False \ --wireless_table_structure_recognition_model_name SLANeXt_wireless3.4 常用 CLI 参数速查通用 OCR 产线 CLI 支持大量可调参数完整说明见 docs/version3.x/pipeline_usage/OCR.md下表为最常用部分参数含义类型默认值input待预测数据本地图像/PDF 路径或 URL目录预测暂不支持 PDFstr必填save_path推理结果保存路径不设置则不保存str—use_doc_orientation_classify是否启用文档方向分类模块boolTrueuse_doc_unwarping是否启用文本图像矫正模块boolTrueuse_textline_orientation是否启用文本行方向模块boolTruetext_detection_model_name/text_detection_model_dir文本检测模型名称 / 本地模型目录str产线默认 / 自动下载text_recognition_model_name/text_recognition_model_dir文本识别模型名称 / 本地模型目录str产线默认 / 自动下载text_recognition_batch_size文本识别 batch sizeint1textline_orientation_batch_size文本行方向 batch sizeint1ocr_version指定 PP-OCR 版本如 PP-OCRv4strPP-OCRv6engine推理引擎paddle / transformers / onnxruntimestrpaddle_staticdevice运行设备如gpu:0str—三个use_*开关默认均为 True纯文本截图场景按上文命令显式关闭可显著减少不必要的预处理耗时大多数场景下默认的paddle_static引擎推理性能更优建议优先使用。四、Python 脚本使用面向二次开发的标准接口PaddleOCR 3.x 的所有产线与模块均可通过 Python API 调用结果对象统一提供print()、save_to_img()、save_to_json()等方法。4.1 PP-OCRv6 通用 OCRfrom paddleocr import PaddleOCR ocr PaddleOCR( use_doc_orientation_classifyFalse, use_doc_unwarpingFalse, use_textline_orientationFalse, enginepaddle, ) result ocr.predict(./general_ocr_002.png) for res in result: res.print() res.save_to_img(output) res.save_to_json(output)典型输出结构节选doc_preprocessor_res记录文档方向与矫正结果如angle: -1dt_polys/rec_polys为检测与识别多边形坐标text_det_params记录了limit_side_len: 736、thresh: 0.3、box_thresh: 0.6、unclip_ratio: 1.5等检测后处理参数rec_texts与rec_scores为识别文本与置信度。4.2 文本检测 / 文本识别单模块from paddleocr import TextDetection, TextRecognition # 文本检测 model TextDetection(enginepaddle) output model.predict(general_ocr_001.png) for res in output: res.print() res.save_to_img(save_path./output/) res.save_to_json(save_path./output/res.json) # 输出含 dt_polys四边形坐标与 dt_scores检测置信度 # 文本识别 model TextRecognition(enginetransformers) output model.predict(inputgeneral_ocr_rec_001.png) for res in output: res.print() res.save_to_img(save_path./output/) res.save_to_json(save_path./output/res.json) # 输出示例{rec_text: 绿洲仕格维花园公寓, rec_score: 0.9908...}4.3 PP-StructureV3Markdown / JSON 结构化输出from paddleocr import PPStructureV3 pipeline PPStructureV3( use_doc_orientation_classifyFalse, use_doc_unwarpingFalse, enginepaddle, ) output pipeline.predict(input./pp_structure_v3_demo.png) for res in output: res.print() res.save_to_json(save_pathoutput) res.save_to_markdown(save_pathoutput)其输出 JSON 包含layout_det_res.boxes版面区域检测结果含cls_id、label、score、coordinate类别如image、text、paragraph_title、doc_title、figure_title与overall_ocr_res整页 OCR 结果含检测/识别多边形与文本可供下游程序直接消费。五、模块与产线理解 3.x 的架构组织方式PaddleOCR 3.x 采用模块—产线双层架构docs/version3.x/module_usage/module_overview.md 与 docs/version3.x/pipeline_usage/pipeline_overview.md模块是实现基本功能的最小单位通常由单个模型完成特定任务如文本检测、图像分类产线由一个或多个模块/子产线组合而成满足复杂场景需求并支持高性能推理与服务化部署。5.1 通用 OCR 产线的 5 个模块模块是否可选代表模型关键指标文档图像方向分类可选PP-LCNet_x1_0_doc_oriTop-1 Acc 99.06%4 类0°/90°/180°/270°文本图像矫正可选UVDocCER 0.179文本行方向分类可选PP-LCNet_x0_25_textline_oriAcc 98.85%/ PP-LCNet_x1_0_textline_oriAcc 99.42%2 类0°/180°文本检测必需PP-OCRv6_medium_det 等检测 Hmean 见下表文本识别必需PP-OCRv6_medium_rec 等识别精度见下表通用 OCR 产线支持 PP-OCRv3/v4/v5/v6 全系模型默认模型为PP-OCRv6_medium。5.2 PP-OCRv6 三档模型基准文本检测模块基于 PPLCNetV4 RepLKFPNHmean 为内部多场景评估集指标与 v4/v5 通用评估集指标不可直接对比模型检测 Hmean存储大小定位PP-OCRv6_medium_det86.2%59.4 MB精度最高适合服务端PP-OCRv6_small_det84.1%9.6 MB兼顾精度与效率适合移动端PP-OCRv6_tiny_det80.6%1.9 MB超轻量0.43M 参数适合端侧/IoT文本识别模块基于 PPLCNetV4 LightSVTR CTC/NRTR 多头解码器单模型支持 50 种语言tiny 档 49 种模型识别精度存储大小PP-OCRv6_medium_rec83.2%73.3 MBPP-OCRv6_small_rec81.3%20.4 MBPP-OCRv6_tiny_rec73.5%4.4 MB该模块共支持 20 个全量模型含 PP-OCRv5 多场景模型、ch_SVTRv2_rec、ch_RepSVTR_rec、英文/韩文/拉丁/希腊/阿拉伯/天城文等众多多语言模型完整列表见 docs/version3.x/pipeline_usage/OCR.md。5.3 从配置文件看 PP-OCRv6 的模型结构仓库中的训练配置 configs/rec/PP-OCRv6/PP-OCRv6_medium_rec.yml 印证了文档对模型架构的描述BackbonePPLCNetV4model_size: mediumHeadMultiHead由CTCHeadNeck 为lightsvtrdims 192、depth 2、mlp_ratio 4.0、local_kernel 7与NRTRHeadnrtr_dim 512max_text_length 25构成LossMultiLoss同时组合CTCLoss与NRTRLoss字典ppocr/utils/dict/ppocrv6_dict.txt开启use_space_char: true。PP-OCRv6_small_rec.yml、PP-OCRv6_tiny_rec.yml结构一致仅骨干model_size与尺寸参数不同三档模型共用同一架构设计。5.4 PP-StructureV3 产线的 7 个组成模块PP-StructureV3 在通用版面解析 v1 基础上强化了版面区域检测、表格识别、公式识别能力并增加图表理解、多栏阅读顺序恢复与 Markdown 转换能力由以下 7 个模块/子产线组成版面区域检测模块通用 OCR 子产线文档图像预处理子产线可选表格识别子产线可选印章文本识别子产线可选公式识别子产线可选图表解析模块可选关键子模型亮点版面区域检测核心模型PP-DocLayout_plus-LmAP(0.5) 83.2%识别 20 类常见版面元素文档标题、段落标题、文本、页码、摘要、目录、参考文献、脚注、页眉/页脚、算法、公式、图像、表格、印章、图表、侧栏文本等另有PP-DocBlockLayout版面子模块检测mAP 95.9%、PP-DocLayout-L/M/S23 类mAP 90.4%/75.2%/70.9%模块共支持 13 个全量模型表格结构识别SLANeXt_wired与SLANeXt_wireless分别针对有线/无线表格训练专用权重精度 69.65%配套PP-LCNet_x1_0_table_cls表格分类模型Top1 Acc 94.2%与RT-DETR-L_wired/wireless_table_cell_det单元格检测模型mAP 82.7%公式识别UniMERNet、PP-FormulaNet-S/L、PP-FormulaNet_plus-S/M/L、LaTeX_OCR_rec共 7 个模型En-BLEU 最高 92.22%PP-FormulaNet_plus-L印章文本检测PP-OCRv4_server_seal_detHmean 98.40%与PP-OCRv4_mobile_seal_detHmean 96.36%图表解析PP-Chart2Table0.58B 参数的多模态模型覆盖饼图、柱状图、堆叠面积图等常见图表类型。从源码侧看这些子产线在 paddleocr/_pipelines/ 中均有对应实现例如PPStructureV3的默认开关可在其代码及输出 JSON 的model_settings中直接观察到use_seal_recognition: True、use_table_recognition: True、use_formula_recognition: True、use_region_detection: True等。六、更多产线与模块索引除通用 OCR 与 PP-StructureV3 外3.x 还提供以下产线均可参考对应教程文档PaddleOCR-VL0.9B 视觉语言模型驱动的文档解析产线详见 docs/version3.x/pipeline_usage/PaddleOCR-VL.mdPP-ChatOCRv4集成 ERNIE 4.5 的文档智能问答与关键信息抽取产线详见 docs/version3.x/pipeline_usage/PP-ChatOCRv4.mdPP-DocTranslation文档翻译产线详见 docs/version3.x/pipeline_usage/PP-DocTranslation.mdDocUnderstanding / DocPreprocessor / SealRecognition / TableRecognitionV2 / FormulaRecognition / HPD-Parsing等见 docs/version3.x/pipeline_usage/ 目录。单模块层面共覆盖 14 个方向文档图像方向分类、文本图像矫正、文本行方向分类、文本检测、文本识别、版面分析/检测、表格结构识别、表格单元格检测、表格分类、公式识别、印章文本检测、图表解析、DocVLM 等完整说明见 docs/version3.x/module_usage/ 目录。七、Agent Skills将 OCR 能力接入 AI 应用PaddleOCR 官方 Agent Skills 将 OCR 与文档解析任务的触发规则、调用步骤、配置要求打包为可按需加载的模块化能力docs/version3.x/integrations/skills.md需求推荐 Skill输出只提取图片/PDF 中的纯文本paddleocr-text-recognition行级文本 边界框 置信度需要保留标题、段落、表格、公式等结构paddleocr-doc-parsingMarkdown / 结构化结果安装前提Python 3.9PaddleOCR 3.7.0pip install paddleocr3.7.0准备 AI Studio access token。安装方式三选一# 方式一skills CLI需 Node.js npx skills add PaddlePaddle/PaddleOCR -g --skill paddleocr-text-recognition -y npx skills add PaddlePaddle/PaddleOCR -g --skill paddleocr-doc-parsing -y # 方式二clawhubOpenClaw clawhub install paddleocr-text-recognition clawhub install paddleocr-doc-parsing # 方式三手动安装 git clone 仓库地址 # 将 skills/paddleocr-text-recognition、skills/paddleocr-doc-parsing 目录拷贝到 AI 应用指定位置环境变量必填PADDLEOCR_ACCESS_TOKEN可选PADDLEOCR_BASE_URL默认官方服务。八、2.x 迁移要点与已知限制8.1 推理代码迁移2.x 风格的PaddleOCR(langen)ocr.ocr(img.png)调用在 3.x 中仍然可用但返回结果对象化直接调用res.print()即可打印不再需要嵌套循环可视化也可直接res.save_to_img(result)。主要差异PaddleOCR.ocr不再接受det、rec等参数单功能推理请改用TextDetection、TextRecognition等独立接口show_log参数被全新的日志系统取代因旧设计下实例共享日志器会相互干扰详见 docs/version3.x/logging.mduse_onnx参数被高性能推理能力取代详见 docs/version3.x/inference_deployment/local_inference/high_performance_inference.md2.x 的PPStructure已移除请改用PPStructureV3。8.2 3.x 已知问题C 本地部署支持尚不完整暂无与 2.x PaddleServing 对齐的高性能服务化部署方案端侧部署仅支持部分重点模型。遇到问题可在 issue 区反馈也欢迎社区参与共建。九、本文关键依据与进一步阅读主题仓库依据3.x 版本升级原因与迁移docs/update/upgrade_notes.md快速开始安装/CLI/Pythondocs/quick_start.md通用 OCR 产线教程与参数表docs/version3.x/pipeline_usage/OCR.mdPP-StructureV3 产线教程docs/version3.x/pipeline_usage/PP-StructureV3.md模块与产线架构定义docs/version3.x/module_usage/module_overview.md、docs/version3.x/pipeline_usage/pipeline_overview.mdPP-OCRv6 模型结构配置configs/rec/PP-OCRv6/PP-OCRv6_medium_rec.yml产线与模块类导出paddleocr/init.pyAgent Skills 集成docs/version3.x/integrations/skills.md、skills/推理引擎与硬件支持docs/version3.x/inference_deployment/安装与运行层面建议按 docs/version3.x/installation.md 完成环境配置若需在国产硬件昆仑芯、昇腾、寒武纪、海光 DCU 等或 Apple Silicon 上运行 PaddleOCR-VL可参考 docs/version3.x/pipeline_usage/ 下对应的专项文档如 PaddleOCR-VL-Huawei-Ascend-NPU.md、PaddleOCR-VL-Kunlunxin-XPU.md、PaddleOCR-VL-Apple-Silicon.md 等。【免费下载链接】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），仅供参考 PaddleOCR 3.x 全景指南：从 PP-OCRv6 多语种识别到 PaddleOCR-VL 复杂文档解析
PaddleOCR 3.x 全景指南从 PP-OCRv6 多语种识别到 PaddleOCR-VL 复杂文档解析【免费下载链接】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 3.x 是飞桨团队面向大模型时代重构的 OCR 与文档智能工具链本文以 docs/index.md 为骨架系统梳理 3.x 的核心能力矩阵PaddleOCR-VL、PP-OCRv6、PP-StructureV3、PP-ChatOCRv4、安装与命令行/Python 双形态使用方式、模块—产线架构及 2.x 升级注意事项并结合仓库源码与配置文件给出可验证的实战依据。读完本文你将掌握 PaddleOCR 3.x 从环境搭建、通用 OCR 推理到复杂文档解析、Agent Skills 集成的完整落地路径。一、PaddleOCR 3.x 版本演进与核心特色能力1.1 从 2.x 到 3.x一次非兼容性架构升级PaddleOCR 2.0 发布于 2021 年 2 月此后四年多持续演进。随着多语种识别、版面分析等需求爆发以轻量化为初衷的旧架构逐渐暴露出模块分支与桥接层膨胀、接口不统一、测试成本高、依赖滞后等问题。为此PaddleOCR 3.x 做了一次重大非兼容性升级详见 docs/update/upgrade_notes.md核心变化有三新增多条模型产线推出 PP-OCRv5/v6、PP-StructureV3、PP-ChatOCRv4 等产线重点增强多文字类型识别与手写体识别满足大模型应用对复杂文档高精度解析的需求重构部署能力、统一推理接口融合飞桨 PaddleX 底层能力参见 docs/version3.x/paddleocr_and_paddlex.md统一优化 Python API 与 CLI覆盖高性能推理、服务化部署与端侧部署适配飞桨 3.0兼容 CINN 编译器统一模型命名体系为训练与推理提速。从源码侧看这一架构重构直接体现在包结构上paddleocr/init.py 同时导出了PaddleOCR、PPStructureV3、PaddleOCRVL、PPChatOCRv4Doc等 9 条产线与 12 个基础模块类以及PaddleOCRClient/AsyncPaddleOCRClient两个云端 API 客户端——模块与产线的组织方式与文档描述一一对应。1.2 四大核心能力截至 2026 年 6 月能力一句话定位关键亮点来自官方文档表述PaddleOCR-VL0.9B 超紧凑视觉语言模型增强多语种文档解析支持 109 种语言1.5 版本在 OmniDocBench v1.5 达 94.5%1.6 版本2026-05-28 发布以 96.3% 刷新 OmniDocBench v1.6支持异形框定位、印章与 spotting 识别模型结构与 1.5 完全一致、可零成本迁移PP-OCRv6全场景多语言文字识别2026-06-11 发布基于 PPLCNetV4 统一骨干tiny/small/medium 三档1.5M~34.5M 参数单模型支持 50 种语言medium 档识别精度提升 5.1%、检测提升 4.6%CPU 端到端推理加速 5.2×PP-StructureV3复杂文档解析将复杂 PDF/文档图像转换为保留原始结构的 Markdown 与 JSON强化版面区域检测、表格识别、公式识别并具备图表理解、多栏阅读顺序恢复能力PP-ChatOCRv4智能信息抽取原生集成 ERNIE 4.5从海量文档中精准提取关键信息精度较上一代提升 15 个百分点1.3 生态与配套服务PaddleOCR OCEAN 生态联盟以 Open Source开源、Community社区、Ecosystem生态、Application应用、Network网络五大理念发起面向全球 OCR 及文档智能上下游伙伴开放可通过邮件 paddleocrbaidu.com 联系加入官方 Agent Skills提供paddleocr-text-recognition与paddleocr-doc-parsing两个 Skills详见 docs/version3.x/integrations/skills.md支持在 Claude Code、claude.ai、OpenClaw 等支持 Skills 的 AI 应用中调用仓库内实现位于 skills/paddleocr-doc-parsing/SKILL.md 与 skills/paddleocr-text-recognition/SKILL.mdMCP 服务仓库提供独立 MCP 服务器实现 mcp_server/可查阅 docs/version3.x/integrations/mcp_server.md云端 APIPaddleOCR 官网免费 API 的每日文档解析上限已提升至 20,000 页支持大批量 PDF 解析。⚠️版本匹配警告PaddleOCR 3.x 引入了大量接口变动基于 2.x 编写的旧代码很可能无法直接运行务必保证所读文档与所用版本一致。二、快速开始安装与两种推理引擎PaddleOCR 3.x 支持通过统一推理引擎配置选择底层运行时目前可使用PaddlePaddle或Transformers两种引擎在产线文档中还会看到onnxruntime选项。2.1 安装推理引擎方式一PaddlePaddle 引擎推荐性能更优# CPU 端 python -m pip install paddlepaddle3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ # GPU 端以 Linux CUDA 11.8 为例其他平台见飞桨官网安装文档 python -m pip install paddlepaddle-gpu3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/使用 PaddlePaddle 推理时PaddleOCR 3.x 依赖3.0 及以上版本的 PaddlePaddle。方式二Transformers 引擎python -m pip install transformers5.8.0通常还需按 Transformers 官方说明安装其底层推理框架。2.2 安装 paddleocr# 完整功能 python -m pip install paddleocr[all] # 仅 OCR 基础功能 pip install paddleocr2.3 环境验证import paddleocr print(fPaddleOCR版本: {paddleocr.__version__}) # paddle_static 引擎下可继续验证 Paddle 与 GPU import paddle print(fPaddle版本: {paddle.__version__}) print(fGPU可用: {paddle.is_compiled_with_cuda()}) print(fGPU数量: {paddle.device.cuda.device_count()}) # transformers 引擎下验证依赖 import transformers print(fTransformers版本: {transformers.__version__})2.4 常见安装问题依赖冲突建议新建虚拟环境例如conda create -n paddleocr python3.8 conda activate paddleocr后再安装GPU 配置先用nvidia-smi检查 CUDA 版本再安装对应版本的paddlepaddle-gpu模型下载失败设置环境变量切换下载源import os os.environ[PADDLE_PDX_MODEL_SOURCE] BOS # 使用百度云存储三、命令行使用一条命令跑通四条产线3.1 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 # Transformers 引擎 paddleocr ocr -i ./general_ocr_002.png \ --use_doc_orientation_classify False \ --use_doc_unwarping False \ --use_textline_orientation False \ --engine transformers3.2 PP-OCRv6 文本检测 / 文本识别单模块# 文本检测 paddleocr text_detection -i ./general_ocr_001.png --engine paddle paddleocr text_detection -i ./general_ocr_001.png --engine transformers # 文本识别 paddleocr text_recognition -i ./general_ocr_rec_001.png --engine paddle paddleocr text_recognition -i ./general_ocr_rec_001.png --engine transformers3.3 PP-StructureV3 复杂文档解析# PaddlePaddle 引擎 paddleocr pp_structurev3 -i ./pp_structure_v3_demo.png \ --use_doc_orientation_classify False \ --use_doc_unwarping False \ --engine paddle # Transformers 引擎部分模型尚在支持中需关闭公式识别并更换无线表格模型 paddleocr pp_structurev3 -i ./pp_structure_v3_demo.png \ --engine transformers \ --use_formula_recognition False \ --wireless_table_structure_recognition_model_name SLANeXt_wireless3.4 常用 CLI 参数速查通用 OCR 产线 CLI 支持大量可调参数完整说明见 docs/version3.x/pipeline_usage/OCR.md下表为最常用部分参数含义类型默认值input待预测数据本地图像/PDF 路径或 URL目录预测暂不支持 PDFstr必填save_path推理结果保存路径不设置则不保存str—use_doc_orientation_classify是否启用文档方向分类模块boolTrueuse_doc_unwarping是否启用文本图像矫正模块boolTrueuse_textline_orientation是否启用文本行方向模块boolTruetext_detection_model_name/text_detection_model_dir文本检测模型名称 / 本地模型目录str产线默认 / 自动下载text_recognition_model_name/text_recognition_model_dir文本识别模型名称 / 本地模型目录str产线默认 / 自动下载text_recognition_batch_size文本识别 batch sizeint1textline_orientation_batch_size文本行方向 batch sizeint1ocr_version指定 PP-OCR 版本如 PP-OCRv4strPP-OCRv6engine推理引擎paddle / transformers / onnxruntimestrpaddle_staticdevice运行设备如gpu:0str—三个use_*开关默认均为 True纯文本截图场景按上文命令显式关闭可显著减少不必要的预处理耗时大多数场景下默认的paddle_static引擎推理性能更优建议优先使用。四、Python 脚本使用面向二次开发的标准接口PaddleOCR 3.x 的所有产线与模块均可通过 Python API 调用结果对象统一提供print()、save_to_img()、save_to_json()等方法。4.1 PP-OCRv6 通用 OCRfrom paddleocr import PaddleOCR ocr PaddleOCR( use_doc_orientation_classifyFalse, use_doc_unwarpingFalse, use_textline_orientationFalse, enginepaddle, ) result ocr.predict(./general_ocr_002.png) for res in result: res.print() res.save_to_img(output) res.save_to_json(output)典型输出结构节选doc_preprocessor_res记录文档方向与矫正结果如angle: -1dt_polys/rec_polys为检测与识别多边形坐标text_det_params记录了limit_side_len: 736、thresh: 0.3、box_thresh: 0.6、unclip_ratio: 1.5等检测后处理参数rec_texts与rec_scores为识别文本与置信度。4.2 文本检测 / 文本识别单模块from paddleocr import TextDetection, TextRecognition # 文本检测 model TextDetection(enginepaddle) output model.predict(general_ocr_001.png) for res in output: res.print() res.save_to_img(save_path./output/) res.save_to_json(save_path./output/res.json) # 输出含 dt_polys四边形坐标与 dt_scores检测置信度 # 文本识别 model TextRecognition(enginetransformers) output model.predict(inputgeneral_ocr_rec_001.png) for res in output: res.print() res.save_to_img(save_path./output/) res.save_to_json(save_path./output/res.json) # 输出示例{rec_text: 绿洲仕格维花园公寓, rec_score: 0.9908...}4.3 PP-StructureV3Markdown / JSON 结构化输出from paddleocr import PPStructureV3 pipeline PPStructureV3( use_doc_orientation_classifyFalse, use_doc_unwarpingFalse, enginepaddle, ) output pipeline.predict(input./pp_structure_v3_demo.png) for res in output: res.print() res.save_to_json(save_pathoutput) res.save_to_markdown(save_pathoutput)其输出 JSON 包含layout_det_res.boxes版面区域检测结果含cls_id、label、score、coordinate类别如image、text、paragraph_title、doc_title、figure_title与overall_ocr_res整页 OCR 结果含检测/识别多边形与文本可供下游程序直接消费。五、模块与产线理解 3.x 的架构组织方式PaddleOCR 3.x 采用模块—产线双层架构docs/version3.x/module_usage/module_overview.md 与 docs/version3.x/pipeline_usage/pipeline_overview.md模块是实现基本功能的最小单位通常由单个模型完成特定任务如文本检测、图像分类产线由一个或多个模块/子产线组合而成满足复杂场景需求并支持高性能推理与服务化部署。5.1 通用 OCR 产线的 5 个模块模块是否可选代表模型关键指标文档图像方向分类可选PP-LCNet_x1_0_doc_oriTop-1 Acc 99.06%4 类0°/90°/180°/270°文本图像矫正可选UVDocCER 0.179文本行方向分类可选PP-LCNet_x0_25_textline_oriAcc 98.85%/ PP-LCNet_x1_0_textline_oriAcc 99.42%2 类0°/180°文本检测必需PP-OCRv6_medium_det 等检测 Hmean 见下表文本识别必需PP-OCRv6_medium_rec 等识别精度见下表通用 OCR 产线支持 PP-OCRv3/v4/v5/v6 全系模型默认模型为PP-OCRv6_medium。5.2 PP-OCRv6 三档模型基准文本检测模块基于 PPLCNetV4 RepLKFPNHmean 为内部多场景评估集指标与 v4/v5 通用评估集指标不可直接对比模型检测 Hmean存储大小定位PP-OCRv6_medium_det86.2%59.4 MB精度最高适合服务端PP-OCRv6_small_det84.1%9.6 MB兼顾精度与效率适合移动端PP-OCRv6_tiny_det80.6%1.9 MB超轻量0.43M 参数适合端侧/IoT文本识别模块基于 PPLCNetV4 LightSVTR CTC/NRTR 多头解码器单模型支持 50 种语言tiny 档 49 种模型识别精度存储大小PP-OCRv6_medium_rec83.2%73.3 MBPP-OCRv6_small_rec81.3%20.4 MBPP-OCRv6_tiny_rec73.5%4.4 MB该模块共支持 20 个全量模型含 PP-OCRv5 多场景模型、ch_SVTRv2_rec、ch_RepSVTR_rec、英文/韩文/拉丁/希腊/阿拉伯/天城文等众多多语言模型完整列表见 docs/version3.x/pipeline_usage/OCR.md。5.3 从配置文件看 PP-OCRv6 的模型结构仓库中的训练配置 configs/rec/PP-OCRv6/PP-OCRv6_medium_rec.yml 印证了文档对模型架构的描述BackbonePPLCNetV4model_size: mediumHeadMultiHead由CTCHeadNeck 为lightsvtrdims 192、depth 2、mlp_ratio 4.0、local_kernel 7与NRTRHeadnrtr_dim 512max_text_length 25构成LossMultiLoss同时组合CTCLoss与NRTRLoss字典ppocr/utils/dict/ppocrv6_dict.txt开启use_space_char: true。PP-OCRv6_small_rec.yml、PP-OCRv6_tiny_rec.yml结构一致仅骨干model_size与尺寸参数不同三档模型共用同一架构设计。5.4 PP-StructureV3 产线的 7 个组成模块PP-StructureV3 在通用版面解析 v1 基础上强化了版面区域检测、表格识别、公式识别能力并增加图表理解、多栏阅读顺序恢复与 Markdown 转换能力由以下 7 个模块/子产线组成版面区域检测模块通用 OCR 子产线文档图像预处理子产线可选表格识别子产线可选印章文本识别子产线可选公式识别子产线可选图表解析模块可选关键子模型亮点版面区域检测核心模型PP-DocLayout_plus-LmAP(0.5) 83.2%识别 20 类常见版面元素文档标题、段落标题、文本、页码、摘要、目录、参考文献、脚注、页眉/页脚、算法、公式、图像、表格、印章、图表、侧栏文本等另有PP-DocBlockLayout版面子模块检测mAP 95.9%、PP-DocLayout-L/M/S23 类mAP 90.4%/75.2%/70.9%模块共支持 13 个全量模型表格结构识别SLANeXt_wired与SLANeXt_wireless分别针对有线/无线表格训练专用权重精度 69.65%配套PP-LCNet_x1_0_table_cls表格分类模型Top1 Acc 94.2%与RT-DETR-L_wired/wireless_table_cell_det单元格检测模型mAP 82.7%公式识别UniMERNet、PP-FormulaNet-S/L、PP-FormulaNet_plus-S/M/L、LaTeX_OCR_rec共 7 个模型En-BLEU 最高 92.22%PP-FormulaNet_plus-L印章文本检测PP-OCRv4_server_seal_detHmean 98.40%与PP-OCRv4_mobile_seal_detHmean 96.36%图表解析PP-Chart2Table0.58B 参数的多模态模型覆盖饼图、柱状图、堆叠面积图等常见图表类型。从源码侧看这些子产线在 paddleocr/_pipelines/ 中均有对应实现例如PPStructureV3的默认开关可在其代码及输出 JSON 的model_settings中直接观察到use_seal_recognition: True、use_table_recognition: True、use_formula_recognition: True、use_region_detection: True等。六、更多产线与模块索引除通用 OCR 与 PP-StructureV3 外3.x 还提供以下产线均可参考对应教程文档PaddleOCR-VL0.9B 视觉语言模型驱动的文档解析产线详见 docs/version3.x/pipeline_usage/PaddleOCR-VL.mdPP-ChatOCRv4集成 ERNIE 4.5 的文档智能问答与关键信息抽取产线详见 docs/version3.x/pipeline_usage/PP-ChatOCRv4.mdPP-DocTranslation文档翻译产线详见 docs/version3.x/pipeline_usage/PP-DocTranslation.mdDocUnderstanding / DocPreprocessor / SealRecognition / TableRecognitionV2 / FormulaRecognition / HPD-Parsing等见 docs/version3.x/pipeline_usage/ 目录。单模块层面共覆盖 14 个方向文档图像方向分类、文本图像矫正、文本行方向分类、文本检测、文本识别、版面分析/检测、表格结构识别、表格单元格检测、表格分类、公式识别、印章文本检测、图表解析、DocVLM 等完整说明见 docs/version3.x/module_usage/ 目录。七、Agent Skills将 OCR 能力接入 AI 应用PaddleOCR 官方 Agent Skills 将 OCR 与文档解析任务的触发规则、调用步骤、配置要求打包为可按需加载的模块化能力docs/version3.x/integrations/skills.md需求推荐 Skill输出只提取图片/PDF 中的纯文本paddleocr-text-recognition行级文本 边界框 置信度需要保留标题、段落、表格、公式等结构paddleocr-doc-parsingMarkdown / 结构化结果安装前提Python 3.9PaddleOCR 3.7.0pip install paddleocr3.7.0准备 AI Studio access token。安装方式三选一# 方式一skills CLI需 Node.js npx skills add PaddlePaddle/PaddleOCR -g --skill paddleocr-text-recognition -y npx skills add PaddlePaddle/PaddleOCR -g --skill paddleocr-doc-parsing -y # 方式二clawhubOpenClaw clawhub install paddleocr-text-recognition clawhub install paddleocr-doc-parsing # 方式三手动安装 git clone 仓库地址 # 将 skills/paddleocr-text-recognition、skills/paddleocr-doc-parsing 目录拷贝到 AI 应用指定位置环境变量必填PADDLEOCR_ACCESS_TOKEN可选PADDLEOCR_BASE_URL默认官方服务。八、2.x 迁移要点与已知限制8.1 推理代码迁移2.x 风格的PaddleOCR(langen)ocr.ocr(img.png)调用在 3.x 中仍然可用但返回结果对象化直接调用res.print()即可打印不再需要嵌套循环可视化也可直接res.save_to_img(result)。主要差异PaddleOCR.ocr不再接受det、rec等参数单功能推理请改用TextDetection、TextRecognition等独立接口show_log参数被全新的日志系统取代因旧设计下实例共享日志器会相互干扰详见 docs/version3.x/logging.mduse_onnx参数被高性能推理能力取代详见 docs/version3.x/inference_deployment/local_inference/high_performance_inference.md2.x 的PPStructure已移除请改用PPStructureV3。8.2 3.x 已知问题C 本地部署支持尚不完整暂无与 2.x PaddleServing 对齐的高性能服务化部署方案端侧部署仅支持部分重点模型。遇到问题可在 issue 区反馈也欢迎社区参与共建。九、本文关键依据与进一步阅读主题仓库依据3.x 版本升级原因与迁移docs/update/upgrade_notes.md快速开始安装/CLI/Pythondocs/quick_start.md通用 OCR 产线教程与参数表docs/version3.x/pipeline_usage/OCR.mdPP-StructureV3 产线教程docs/version3.x/pipeline_usage/PP-StructureV3.md模块与产线架构定义docs/version3.x/module_usage/module_overview.md、docs/version3.x/pipeline_usage/pipeline_overview.mdPP-OCRv6 模型结构配置configs/rec/PP-OCRv6/PP-OCRv6_medium_rec.yml产线与模块类导出paddleocr/init.pyAgent Skills 集成docs/version3.x/integrations/skills.md、skills/推理引擎与硬件支持docs/version3.x/inference_deployment/安装与运行层面建议按 docs/version3.x/installation.md 完成环境配置若需在国产硬件昆仑芯、昇腾、寒武纪、海光 DCU 等或 Apple Silicon 上运行 PaddleOCR-VL可参考 docs/version3.x/pipeline_usage/ 下对应的专项文档如 PaddleOCR-VL-Huawei-Ascend-NPU.md、PaddleOCR-VL-Kunlunxin-XPU.md、PaddleOCR-VL-Apple-Silicon.md 等。【免费下载链接】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），仅供参考 RELATED READING
延伸阅读
更多一线实战笔记与深度复盘，助您持续精进
` 一行代码完成推理、批量加速与自定义扩展)
