PaddleOCR 3.x 快速上手安装、命令行与 Python API 实战指南【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR本篇技术指南以 PaddleOCR 官方 Quick Start 文档为主体系统讲解 PaddleOCR 3.x 的完整上手路径从推理引擎PaddlePaddle / Transformers安装、paddleocr包安装到命令行CLI与 Python API 双入口下的 PP-OCRv6 全流程 OCR、文本检测、文本识别与 PP-StructureV3 版面分析流水线实战。读完本文你将掌握--engine推理引擎切换机制、PaddleOCR/TextDetection/TextRecognition/PPStructureV3四个核心 API 的调用方式与结果解析方法并理解这些接口在仓库源码中的底层实现。一、环境安装两条安装路径PaddleOCR 3.x 采用统一推理引擎配置机制底层运行时Runtime可选 PaddlePaddle 与 Transformers 两种引擎。安装分为两步先装推理引擎再装paddleocr包本身。1. 安装推理引擎路径 APaddlePaddle 引擎CPU 版本安装命令python -m pip install paddlepaddle3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/GPU 版本依赖特定的 CUDA 版本以下示例针对 Linux 平台、CUDA 11.8 环境的 NVIDIA GPU 安装。其他平台请参考 PaddlePaddle 官方安装文档python -m pip install paddlepaddle-gpu3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/重要提醒使用 PaddlePaddle 进行推理时PaddleOCR 3.x 依赖 PaddlePaddle3.0 及以上版本请确保版本满足要求。路径 BTransformers 引擎选择 Transformers 作为推理后端时安装 Hugging Face Transformerspython -m pip install transformers5.8.0多数情况下还需额外安装 Transformers 所依赖的底层推理框架具体请参考 Transformers 官方安装文档。2. 安装paddleocr包安装完整功能版本python -m pip install paddleocr[all]PaddleOCR 也支持按需安装特定功能。仓库中的安装文档将可选依赖划分为多个能力组| 依赖组名称 | 对应功能 | | - | - | |doc-parser| 文档解析抽取文档中的表格、公式、印章、图片等版面元素包含 PP-StructureV3 等模型方案 | |ie| 信息抽取抽取文档中的姓名、日期、地址、金额等关键信息包含 PP-ChatOCRv4 等模型方案 | |trans| 文档翻译包含 PP-DocTranslation 等模型方案 | |doc2md| 文档转 Markdown将 Word、Excel、PowerPoint 快速转换为可读文本 | |all| 全功能 |从源码结构看paddleocr包与依赖组是独立的安装维度通用 OCR 与文档图像预处理流水线无需额外依赖组而文档解析、信息抽取、文档翻译等能力需按上表安装对应依赖组。安装训练与模型导出依赖则需另行安装 PaddlePaddle 框架及仓库根目录的requirements.txt。二、命令行CLI使用安装完成后可直接通过paddleocr命令行执行推理。以下均以-i指定输入图片路径并用--engine显式选择推理引擎paddle或transformers。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 transformers命令中三个use_*开关分别控制文档方向分类自动纠正 0°/90°/180°/270° 旋转、文档图像矫正去卷曲/去透视畸变与文本行方向分类。在图片本身方向正常、文本行横平竖直的场景下关闭这三个预处理模块可以显著减少推理链路开销。2. PP-OCRv6 文本检测模块# PaddlePaddle 引擎 paddleocr text_detection -i ./general_ocr_001.png --engine paddle # Transformers 引擎 paddleocr text_detection -i ./general_ocr_001.png --engine transformers3. PP-OCRv6 文本识别模块# PaddlePaddle 引擎 paddleocr text_recognition -i ./general_ocr_rec_001.png --engine paddle # Transformers 引擎 paddleocr text_recognition -i ./general_ocr_rec_001.png --engine transformers4. PP-StructureV3 版面解析流水线PaddlePaddle 引擎paddleocr pp_structurev3 -i ./pp_structure_v3_demo.png \ --use_doc_orientation_classify False \ --use_doc_unwarping False \ --engine paddleTransformers 引擎注意当前部分模型仍在适配中必须关闭公式识别并替换无线表格结构识别模型paddleocr pp_structurev3 -i ./pp_structure_v3_demo.png \ --engine transformers \ --use_formula_recognition False \ --wireless_table_structure_recognition_model_name SLANeXt_wireless从仓库源码看paddleocr命令行的各子命令ocr、text_detection、text_recognition、pp_structurev3等由 paddleocr/_cli.py 中的_register_pipelines/_register_models统一注册最终都会落到对应的 Python API 类上执行。三、Python API 使用Python API 是比命令行更灵活的集成方式适合嵌入业务系统。统一套路为实例化模型/流水线对象 → 调用predict→ 遍历结果并调用res.print()/res.save_to_img()/res.save_to_json()/res.save_to_markdown()输出。1. PP-OCRv6 全流程 OCR# PaddlePaddle 引擎 from 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)# Transformers 引擎 from paddleocr import PaddleOCR ocr PaddleOCR( use_doc_orientation_classifyFalse, use_doc_unwarpingFalse, use_textline_orientationFalse, enginetransformers, ) result ocr.predict(./general_ocr_002.png) for res in result: res.print() res.save_to_img(output) res.save_to_json(output)示例输出节选关键字段数组元素以...省略{res: {input_path: ./general_ocr_002.png, page_index: None, model_settings: {use_doc_preprocessor: True, use_textline_orientation: False}, doc_preprocessor_res: {input_path: None, page_index: None, model_settings: {use_doc_orientation_classify: False, use_doc_unwarping: False}, angle: -1}, dt_polys: array([[[1, 4], ..., [99, 480]]], dtypeint16), text_det_params: {limit_side_len: 960, limit_type: max, thresh: 0.3, max_side_limit: 4000, box_thresh: 0.6, unclip_ratio: 1.5}, text_type: general, textline_orientation_angles: array([-1, ..., -1]), text_rec_score_thresh: 0.0, rec_texts: [www.997788.com, 登机牌, BOARDING PASS, 舱位CLASS, 序号 SERIAL NO., 座位号, SEAT NO, 航班FLIGHT, 日期, DATE, MU 2379, 03DEC, W, 035, , 始发地, FROM, 登机口, GATE, 登机时间BDT, 目的地TO, 福州, TAIYUAN, G11, FUZHOU, 身份识别IDNO., 姓名NAME, ZHANGQIWEI, 票号TKTNO., 张祺伟, 票价FARE, ETKT7813699238489/1, 登机口于起飞前10分钟关闭 GATESCL0SE10MINUTESBEFOREDEPARTURETIME], rec_scores: array([0.99684608, ..., 0.97179604]), rec_polys: array([[[1, 4], ..., [99, 480]]], dtypeint16), rec_boxes: array([[1, ..., 33], ..., [99, ..., 480]], dtypeint16)}}该输出结构清晰地展示了 PP-OCRv6 流水线的完整处理链文档预处理doc_preprocessor_res此处输出angle: -1表示无需旋转→ 文本检测dt_polys→ 文本行方向textline_orientation_angles→ 文本识别rec_texts、rec_scores、rec_boxes。同时text_det_params暴露了检测阶段的关键后处理参数与下方源码分析一一对应。2. PP-OCRv6 文本检测模块# PaddlePaddle 引擎 from paddleocr import TextDetection 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)# Transformers 引擎 from paddleocr import TextDetection model TextDetection(enginetransformers) 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)示例输出{res: {input_path: general_ocr_001.png, page_index: None, dt_polys: array([[[77, 551], ..., [36, 456]]], dtypeint16), dt_scores: [0.8562385635646694, 0.8818259002228059, 0.8406072284043453, 0.8855339313157491]}}dt_polys为检测到的文本框多边形顶点int16 数组dt_scores为每个框的检测置信度。TextDetection 默认模型为PP-OCRv6_medium_det见 paddleocr/_models/text_detection.py也可通过model_name参数替换。3. PP-OCRv6 文本识别模块# PaddlePaddle 引擎 from paddleocr import TextRecognition model TextRecognition(enginepaddle) 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)# Transformers 引擎 from paddleocr import TextRecognition 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)示例输出{res: {input_path: general_ocr_rec_001.png, page_index: None, rec_text: 绿洲仕格维花园公寓, rec_score: 0.990813672542572}}TextRecognition 默认模型为PP-OCRv6_medium_rec见 paddleocr/_models/text_recognition.py输出仅包含识别文本rec_text与其置信度rec_score。4. PP-StructureV3 版面解析流水线# PaddlePaddle 引擎 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)# Transformers 引擎 # 注意当前部分模型仍在适配中必须关闭公式识别并替换无线表格结构识别模型 from paddleocr import PPStructureV3 pipeline PPStructureV3( use_doc_orientation_classifyFalse, use_doc_unwarpingFalse, use_formula_recognitionFalse, wireless_table_structure_recognition_model_nameSLANeXt_wireless, enginetransformers, ) 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)PaddlePaddle 引擎示例输出节选...为省略数组元素{res: {input_path: ./pp_structure_v3_demo.png, page_index: None, model_settings: {use_doc_preprocessor: False, use_seal_recognition: True, use_table_recognition: True, use_formula_recognition: True, use_chart_recognition: False, use_region_detection: True}, layout_det_res: {input_path: None, page_index: None, boxes: [ {cls_id: 1, label: image, score: 0.9864752888679504, coordinate: [774.821, 201.05177, 1502.1008, 685.7733]}, {cls_id: 2, label: text, score: 0.9859225749969482, coordinate: [769.8655, 776.2446, 1121.5986, 1058.417]}, ..., {cls_id: 0, label: paragraph_title, score: 0.9476125240325928, coordinate: [28.159409, 456.7627, 339.5631, 514.9665]}, {cls_id: 10, label: doc_title, score: 0.9376171827316284, coordinate: [133.77905, 36.8844, 1379.6667, 123.46869]}, {cls_id: 6, label: figure_title, score: 0.7892374396324158, coordinate: [808.9641, 704.2555, 1484.0623, 747.2296]}]}, overall_ocr_res: {input_path: None, page_index: None, model_settings: {use_doc_preprocessor: False, use_textline_orientation: False}, dt_polys: array([[[129, 42], ..., [1156, 1351]]], dtypeint16), text_det_params: {limit_side_len: 736, limit_type: min, thresh: 0.3, max_side_limit: 4000, box_thresh: 0.6, unclip_ratio: 1.5}, text_type: general, textline_orientation_angles: array([-1, ..., -1]), text_rec_score_thresh: 0.0, rec_texts: [助力双方交往, 搭建友谊桥梁, 本报记者沈小晓, ...], rec_scores: array([0.99113536, ..., 0.95110035]), ...}}}PP-StructureV3 是文档级解析流水线layout_det_res输出版面检测结果doc_title、paragraph_title、text、image、figure_title等类别及坐标overall_ocr_res则给出整页 OCR 结果。相比通用 OCR它额外集成了印章识别、表格识别、公式识别、图表识别与区域检测等模块见model_settings并支持将结果直接保存为 Markdown。四、--engine参数与底层实现解析--engine是 PaddleOCR 3.x 统一推理引擎配置的核心入口。从 paddleocr/_common_args.py 源码可见当前支持的引擎枚举为SUPPORTED_INFERENCE_ENGINE_LIST [ paddle, paddle_static, paddle_dynamic, transformers, onnxruntime, ]若传入不在此列表中的值会在 parse_common_args 阶段直接抛出ValueError。当engine为paddle或未指定时源码 prepare_common_init_args 会构造{paddle_static: built}的engine_config其中built依据设备类型与加速开关生成GPU 设备下若启用 TensorRT 则run_mode为trt_fp32/trt_fp16否则为paddleCPU 设备下默认启用 MKL-DNN 加速enable_mkldnn默认True并设置cpu_threads默认 10 线程详见 paddleocr/_constants.py。除engine外模型与流水线类还接受一组通用推理参数同样在_common_args.py中注册为 CLI 选项| 参数 | 说明 | 默认值 | | - | - | - | |--device| 推理设备如cpu、gpu、npu、gpu:0多设备场景支持gpu:0,1并行 | 优先 GPU 0否则 CPU | |--use_tensorrt| 是否使用 Paddle Inference 的 TensorRT 子图引擎 |False| |--precision| TensorRT 精度fp32/fp16|fp32| |--enable_mkldnn| 是否启用 MKL-DNN 加速 |True| |--mkldnn_cache_capacity| MKL-DNN 缓存容量 |10| |--cpu_threads| CPU 推理线程数 |10| |--enable_cinn| 是否启用 CINN 编译器 |False|模型类如TextDetection、TextRecognition通过 paddleocr/_models/base.py 中的_create_paddlex_predictor调用 PaddleX 的create_predictor创建预测器流水线类如PaddleOCR、PPStructureV3则通过 paddleocr/_pipelines/base.py 中的_create_paddlex_pipeline创建 PaddleX 流水线。所有类在paddleocr/__init__.py顶层导出因此from paddleocr import PaddleOCR可直接使用。五、文本检测关键参数详解在 PaddleOCR 全流程与文本检测模块中以下检测参数直接影响检测效果对应源码 paddleocr/_models/_text_detection.py 中的 CLI 定义| 参数 | 含义 | 说明 | | - | - | - | |limit_side_len| 输入图像边长限制 | 对输入图像进行缩放限制默认 960OCR 全流程/ 736PP-StructureV3 场景可见 | |limit_type| 边长限制方式 |max表示最长边限制、min表示最短边限制配合limit_side_len使用 | |thresh| 检测像素阈值 | 概率图中得分大于该值的像素被判为文本像素默认0.3| |box_thresh| 检测框阈值 | 检测结果边框内所有像素的平均分大于该值才视为有效文本区域默认0.6| |unclip_ratio| 扩张系数 | 对文本区域进行扩张值越大扩张面积越大默认1.5| |input_shape| 模型输入形状 | 三元组(C, H, W)一般无需修改 |在 Python API 中这些参数在PaddleOCR类上对应text_det_limit_side_len、text_det_limit_type、text_det_thresh、text_det_box_thresh、text_det_unclip_ratio等命名参数并会通过 paddleocr/_pipelines/ocr.py 的_get_paddlex_config_overrides映射到 PaddleX 配置中的SubModules.TextDetection.*节点。这也是为什么前文示例输出的text_det_params中能看到limit_side_len、thresh、box_thresh、unclip_ratio等字段——它们正是流水线实际生效的检测后处理参数。六、从 2.x 平滑迁移兼容性与推荐实践PaddleOCR类在 paddleocr/_pipelines/ocr.py 中明确标注与 PaddleOCR 2.x 接口兼容旧的det_model_dir、rec_model_dir、use_angle_cls、rec_batch_num等参数会被自动映射到新命名如text_detection_model_dir、use_textline_orientation、text_recognition_batch_size并给出弃用警告同时旧版的ocr.ocr(img)方法仍保留但已标记弃用推荐统一使用predict。此外PaddleOCR还支持通过lang与ocr_version参数自动选择模型组合支持版本为PP-OCRv3/PP-OCRv4/PP-OCRv5/PP-OCRv6但注意一旦显式传入任何模型名或模型目录lang与ocr_version将被忽略并发出警告。官方 Quick Start 中的示例均为默认模型PP-OCRv6适用于通用中英文场景多语言、特定版面场景可结合docs/version3.x/下的模型列表与流水线文档进一步配置。实践建议生产环境集成优先使用 Python API 并通过enginepaddle搭配--use_tensorrt/--enable_mkldnn等加速开关获得最优性能需要与 Hugging Face 生态协同或对比不同框架推理结果时再切换enginetransformersPP-StructureV3 在 Transformers 引擎下需按官方说明关闭公式识别并替换无线表格模型SLANeXt_wireless。【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考