PaddleOCR 3.x 快速上手指南安装、命令行与 Python 脚本推理实战【免费下载链接】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 官方快速开始文档为核心骨架完整讲解 PaddleOCR 3.x 的安装流程推理引擎 功能包、paddleocr命令行推理与 Python 脚本推理的四种典型用法PP-OCRv6 整图 OCR、文本检测、文本识别、PP-StructureV3 文档结构解析并结合仓库源码深入解析统一推理引擎、默认模型选择与结果输出结构。读完本文你将能够在本地环境中独立完成 PaddleOCR 的安装、配置与端到端推理并理解其底层调用机制。一、安装准备先装推理引擎PaddleOCR 3.x 通过统一的推理引擎配置选择底层运行时目前可选用PaddlePaddle或Transformers作为后端二者通过参数engine指定详见下文统一推理引擎小节。在安装paddleocr功能包之前需要先安装所选引擎。1.1 安装 PaddlePaddlePaddle 引擎CPU 版本安装python -m pip install paddlepaddle3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/GPU 版本安装GPU 版本需要根据具体的 CUDA 版本来选择对应的安装包以下以 Linux 平台、pip 安装英伟达 GPU、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。其他平台Windows、macOS或不同 CUDA 版本的具体安装命令请参考飞桨官网安装文档中的说明操作。1.2 安装 TransformersHugging Face 引擎如需使用 Transformers 作为推理引擎需安装 Hugging Face Transformerspython -m pip install transformers5.8.0通常还需要安装 Transformers 所使用的底层推理框架如 PyTorch具体可参考 Transformers 官方安装文档。二、安装 paddleocr 功能包推理引擎就绪后执行如下命令安装 PaddleOCR 的完整功能python -m pip install paddleocr[all]PaddleOCR 也支持按需安装部分功能。根据仓库中的 安装文档paddleocr支持如下可选依赖组| 依赖组名称 | 对应的功能 | | - | - | |doc-parser| 文档解析用于提取文档中的表格、公式、印章、图片等版面元素包含 PP-StructureV3 等模型方案 | |ie| 信息抽取用于从文档中提取关键信息如姓名、日期、地址、金额等包含 PP-ChatOCRv4 等模型方案 | |trans| 文档翻译包含 PP-DocTranslation 等模型方案 | |doc2md| 文档转 Markdown可将 Word、Excel、PowerPoint 文件快速转为可读文本 | |all| 完整功能 |通用 OCR 产线与文档图像预处理产线无需额外依赖组本文涉及的 PP-OCRv6 整图 OCR、文本检测、文本识别属于默认能力安装paddleocr即可使用PP-StructureV3 文档结构解析属于doc-parser能力域。三、命令行快速推理安装完成后可直接通过paddleocr命令行工具进行推理。命令行入口的注册逻辑位于 paddleocr/_cli.py它会将ocr、text_detection、text_recognition、pp_structurev3等子命令统一挂载到主解析器上。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 transformers其中-i/--input为必填的输入图片路径见 paddleocr/_utils/cli.py 中add_simple_inference_args的定义--use_doc_orientation_classify、--use_doc_unwarping、--use_textline_orientation分别控制是否启用文档方向分类、文档矫正、文本行方向分类三个预处理模块。3.2 PP-OCRv6 文本检测模块仅执行文本检测定位图片中的文字区域不识别内容# 使用 PaddlePaddle 进行推理 paddleocr text_detection -i ./general_ocr_001.png --engine paddle # 使用 Transformers 进行推理 paddleocr text_detection -i ./general_ocr_001.png --engine transformers从源码看paddleocr/_models/text_detection.py 中TextDetection的默认模型为PP-OCRv6_medium_det。3.3 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 transformers对应 paddleocr/_models/text_recognition.py 中的TextRecognition模块默认模型为PP-OCRv6_medium_rec。3.4 PP-StructureV3 文档结构解析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_wireless四、Python 脚本推理除了命令行PaddleOCR 还提供面向 Python 的编程式 API。所有模型与管线类PaddleOCR、PPStructureV3、TextDetection、TextRecognition等统一从paddleocr包导出见 paddleocr/init.py。4.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: /root/.paddlex/predict_input/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([...]), # 文本检测多边形坐标 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: [www.997700, , Cm, 登机牌, BOARDING, ...], # 识别文本列表 rec_scores: array([0.67582953, ..., 0.97418666]), # 识别置信度 rec_polys: array([...]), rec_boxes: array([...])}}4.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([...]), # 检测到的文本区域多边形 dt_scores: [0.8562385635646694, 0.8818259002228059, 0.8406072284043453, 0.8855339313157491]}}4.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}}4.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: {boxes: [{cls_id: 1, label: image, score: 0.986..., coordinate: [...]}, {cls_id: 2, label: text, ...}, {cls_id: 0, label: paragraph_title, ...}, {cls_id: 10, label: doc_title, ...}, {cls_id: 6, label: figure_title, ...}, ...]}, overall_ocr_res: {model_settings: {use_doc_preprocessor: False, use_textline_orientation: False}, dt_polys: array([...]), text_det_params: {limit_side_len: 736, ...}, rec_texts: [助力双方交往, 搭建友谊桥梁, ...], rec_scores: array([...]), rec_boxes: array([...])}}}可以看到PP-StructureV3 的输出由两部分组成layout_det_res版面检测结果包含image、text、paragraph_title、doc_title、figure_title等版面元素的类别、置信度与坐标和overall_ocr_res整页 OCR 结果与 PP-OCRv6 输出结构一致。此外 Python API 还支持save_to_markdown直接输出 Markdown 格式的结构化文档这正是 PP-StructureV3 用于文档解析落地的关键能力。五、源码级解读统一推理引擎与常用参数5.1 推理引擎机制在 paddleocr/_common_args.py 中定义了受支持的推理引擎列表SUPPORTED_INFERENCE_ENGINE_LIST [ paddle, paddle_static, paddle_dynamic, transformers, onnxruntime, ]paddlePaddlePaddle 框架本文快速开始中的默认引擎transformersHugging Face Transformers 后端paddle_static/paddle_dynamicPaddlePaddle 静态图 / 动态图模式onnxruntimeONNX Runtime 后端。在 Python 构造器中直接传入enginepaddle或enginetransformers即可切换引擎命令行则使用--engine参数其choices即为上述列表。CLI 中引擎相关的详细配置如 TensorRT、MKLDNN 等需要在 PaddleX 的 YAML 配置文件中设置。5.2 常见公共参数除引擎外所有模型与管线还支持如下公共参数见 paddleocr/_common_args.py 与 paddleocr/_constants.py| 参数 | 默认值 | 说明 | | - | - | - | |--device| GPU 0可用时否则 CPU | 推理设备支持cpu、gpu、npu、gpu:0、gpu:0,1等写法 | |--precision|fp32| TensorRT 推理精度可选fp32/fp16| |--enable_mkldnn|True| 是否启用 MKL-DNN CPU 加速 | |--cpu_threads|10| CPU 推理线程数 | |--use_tensorrt|False| 是否使用 Paddle Inference TensorRT 子图引擎 | |--enable_cinn|False| 是否使用 CINN 编译器 |5.3 PP-OCRv6 整图 OCR 的核心参数PaddleOCR管线实现在 paddleocr/_pipelines/ocr.py的内部结构为文档预处理DocPreprocessor 文本检测TextDetection 文本行方向分类TextLineOrientation 文本识别TextRecognition文档预处理开关use_doc_orientation_classify文档方向分类、use_doc_unwarping文档矫正。二者任一为True时会启用 DocPreprocessor 子管线源码中use_doc_preprocessor取二者之或。文本行方向开关use_textline_orientation文本行方向分类。它对竖排文本或旋转文本行进行方向校正。文本检测参数text_det_limit_side_len输入图像边长限制输出示例中默认 736、text_det_limit_type边长限制方式min/max、text_det_thresh像素阈值默认 0.3大于该值的像素视为文本像素、text_det_box_thresh检测框阈值默认 0.6框内像素平均分高于该值才保留、text_det_unclip_ratio检测框扩张系数默认 1.5值越大扩张区域越大。文本识别参数text_rec_score_thresh识别置信度阈值低于该值的结果被过滤、text_rec_batch_size识别批大小、text_rec_input_shape识别模型输入形状。5.4 PP-StructureV3 的核心参数PPStructureV3管线实现在 paddleocr/_pipelines/pp_structurev3.py是一个更复杂的组合管线除上述文档预处理与通用 OCR 子管线外还包含| 参数 | 作用 | | - | - | |use_seal_recognition| 是否启用印章识别 | |use_table_recognition| 是否启用表格识别 | |use_formula_recognition| 是否启用公式识别Transformers 引擎下需关闭 | |use_chart_recognition| 是否启用图表识别 | |use_region_detection| 是否启用区域检测 | |layout_detection_model_name/layout_threshold/layout_nms等 | 版面检测模型及阈值、NMS、扩张等参数 | |wired_table_structure_recognition_model_name/wireless_table_structure_recognition_model_name| 有线 / 无线表格结构识别模型名Transformers 引擎下无线表格需指定SLANeXt_wireless | |format_block_content/markdown_ignore_labels| Markdown 输出的内容格式化与忽略标签控制 |六、默认模型与语言选择当未显式指定text_detection_model_name/text_recognition_model_name或对应model_dir时PaddleOCR 会根据lang与ocr_version自动选择默认模型。从 paddleocr/_pipelines/ocr.py 的_get_ocr_model_names实现可以看出当lang与ocr_version均为None时默认使用PP-OCRv6_medium_det文本检测与PP-OCRv6_medium_rec文本识别——这正是快速开始示例的行为仓库测试 tests/pipelines/test_ocr.py 中也对该默认模型进行了断言验证支持的 OCR 版本为PP-OCRv3、PP-OCRv4、PP-OCRv5、PP-OCRv6ocr_version参数的可选值可通过--ocr_version指定语言支持非常广泛PP-OCRv6覆盖中文ch、简体中文chinese_cht、英文en、日文japan以及拉丁语系语言PP-OCRv5额外覆盖韩文、泰文、希腊文、斯拉夫语系、阿拉伯语系、西里尔语系、天城文等PP-StructureV3 内部的语言映射逻辑见 paddleocr/_pipelines/pp_structurev3.py 的_get_ocr_model_names。若同时指定lang/ocr_version与模型名lang与ocr_version会被忽略并产生警告指定了不受支持的语言与版本组合时会抛出ValueError提示 No models are available。七、命令行执行流程与结果保存命令行推理的统一执行流程位于 paddleocr/_utils/cli.py 的perform_simple_inference解析-i/--input必填与--save_path输出目录可选用剩余参数实例化对应的模型 / 管线类如PaddleOCR、TextDetection通过predict_iter迭代推理结果逐条打印并统计耗时若指定了--save_path则调用res.save_all(save_path)将所有结果可视化图片、JSON 等保存到该目录结束后调用close()释放管线资源。因此命令行模式下只需追加--save_path ./output/即可将检测框可视化图与结果 JSON 一并落盘方便批量处理与二次开发。八、常见问题与注意事项PaddlePaddle 版本要求PaddleOCR 3.x 依赖 PaddlePaddle3.0及以上版本请勿使用旧版 2.x 框架否则可能报依赖错误。Transformers 引擎的模型支持范围PP-StructureV3 在使用transformers引擎时部分模型尚在支持中必须关闭公式识别--use_formula_recognition False并显式指定无线表格结构识别模型为SLANeXt_wireless否则推理可能失败。预处理模块开关快速开始示例统一关闭了文档方向分类、文档矫正与文本行方向分类三个开关以最小化依赖、加速推理。对旋转、畸变或包含竖排文本的真实场景可分别开启对应开关以获得更好效果代价是额外的模型加载与推理时间。多语言场景默认不指定lang为中文场景处理英文、日文、韩文、阿拉伯文等其他语言时应通过--lang参数指定语言以自动加载匹配的识别模型。结果保存Python API 中每个结果对象均提供print()、save_to_img()、save_to_json()方法PP-StructureV3 额外提供save_to_markdown()用于输出结构化文档配合concatenate_markdown_pages可将多页结果合并。至此你已经掌握了 PaddleOCR 3.x 从环境安装到命令行、Python 脚本推理的完整链路并理解了统一推理引擎、默认模型选择与参数调优背后的源码机制可以立即在本地开始你的 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），仅供参考