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 3.x 的官方快速入门指南对应仓库 docs/quick_start.en.md面向希望尽快把 OCR 能力跑起来的开发者。PaddleOCR 3.x 引入了统一推理引擎配置可在 PaddlePaddle 与 Hugging Face Transformers 之间自由切换底层运行时在此基础上本文会带你完成环境安装、命令行推理与 Python 脚本调用三个环节覆盖 PP-OCRv6 整图识别、文本检测、文本识别与 PP-StructureV3 文档结构化四条主线并结合仓库源码说明engine、use_doc_orientation_classify、use_doc_unwarping、use_textline_orientation等关键参数在底层是如何生效的。读完本文你将能够独立完成 PaddleOCR 3.x 的部署与二次开发。一、理解 PaddleOCR 3.x 的统一推理引擎机制PaddleOCR 3.x 在架构上最显著的变化是推理引擎与业务 API 解耦。无论是完整 OCR 管线PaddleOCR、文档结构化管线PPStructureV3还是单模型模块TextDetection/TextRecognition都通过一个统一的engine参数选择底层运行时。从源码看该机制实现在 paddleocr/_common_args.pySUPPORTED_INFERENCE_ENGINE_LIST [ paddle, paddle_static, paddle_dynamic, transformers, onnxruntime, ]即当前版本支持paddle默认、paddle_static、paddle_dynamic、transformers与onnxruntime五种引擎。所有模型与管线的公共参数device、engine、use_tensorrt、precision、enable_mkldnn、cpu_threads、enable_cinn等都会经过 parse_common_args 校验与归一化——例如引擎不在支持列表内会直接抛出ValueError。随后 prepare_common_init_args 会根据引擎类型与设备类型CPU/GPU自动组装engine_configGPU 上可选择 Paddle Inference 的 TensorRT 子图trt_fp32/trt_fp16CPU 上则可开启 MKL-DNN 加速。在命令行层面CLI 入口 paddleocr/_cli.py 会注册全部管线与模型子命令最终每个预测器的创建经由 paddleocr/_models/base.py 中的_create_paddlex_predictor调用 PaddleX 的create_predictor完成因此你既可以通过--engine paddle使用 PaddlePaddle也可以通过--engine transformers使用 Transformers。二、环境安装2.1 安装推理引擎PaddleOCR 支持统一推理引擎配置你可以按需选择底层运行时目前支持 PaddlePaddle 与 Transformers。选择一PaddlePaddleCPU 安装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/GPU 安装对 CUDA 版本有特定要求其他平台请参照 PaddlePaddle 官方安装文档进行。注意使用 PaddlePaddle 推理时PaddleOCR 3.x 依赖 PaddlePaddle3.0及以上版本。选择二Transformers使用 Transformers 引擎推理时安装 Hugging Face Transformerspython -m pip install transformers5.8.0多数情况下你还需要安装 Transformers 所依赖的底层推理框架具体请参见 Transformers 官方安装文档。2.2 安装paddleocr安装 PaddleOCR 的全部功能python -m pip install paddleocr[all]PaddleOCR 也支持按需安装特定功能如仅装 OCR 或仅装文档解析相关依赖详细说明见 PaddleOCR 安装文档。提示安装完成后可通过paddleocr -v或paddleocr --version查看版本信息版本号来源于 paddleocr/_version.py 中的importlib.metadata读取。三、命令行快速体验paddleocr安装后会注册同名 CLI 命令支持ocr、text_detection、text_recognition、pp_structurev3等子命令完整注册逻辑见 paddleocr/_cli.py。以下示例均以仓库演示图如general_ocr_002.png为输入。3.1 PP-OCRv6 整图 OCRPaddlePaddle 引擎paddleocr ocr -i ./general_ocr_002.png \ --use_doc_orientation_classify False \ --use_doc_unwarping False \ --use_textline_orientation False \ --engine paddleTransformers 引擎paddleocr ocr -i ./general_ocr_002.png \ --use_doc_orientation_classify False \ --use_doc_unwarping False \ --use_textline_orientation False \ --engine transformers参数说明均对应 paddleocr/_pipelines/ocr.py 中的 CLI 定义参数含义类型/默认行为-i, --input输入图片路径或 URL必填--engine推理引擎取值为paddle/paddle_static/paddle_dynamic/transformers/onnxruntime默认由 PaddleX 自动选择--use_doc_orientation_classify是否启用文档方向分类0°/90°/180°/270°布尔值True/False--use_doc_unwarping是否启用文档图像矫正去弯曲布尔值True/False--use_textline_orientation是否启用文本行方向分类解决单行文字倒置问题布尔值True/False--device推理设备如cpu、gpu、gpu:0默认 GPU 0 可用时用 GPU否则 CPU--save_path结果保存目录可选从源码看use_doc_orientation_classify与use_doc_unwarping二者任一为True时use_doc_preprocessor会被自动置为True见 paddleocr/_pipelines/ocr.py即进入文档预处理子管线。3.2 PP-OCRv6 文本检测模块PaddlePaddle 引擎paddleocr text_detection -i ./general_ocr_001.png --engine paddleTransformers 引擎paddleocr text_detection -i ./general_ocr_001.png --engine transformers该子命令默认加载PP-OCRv6_medium_det检测模型见 paddleocr/_models/text_detection.py并额外支持--limit_side_len、--limit_type、--thresh、--box_thresh、--unclip_ratio、--input_shape等检测参数定义见 paddleocr/_models/_text_detection.py。3.3 PP-OCRv6 文本识别模块PaddlePaddle 引擎paddleocr text_recognition -i ./general_ocr_rec_001.png --engine paddleTransformers 引擎paddleocr text_recognition -i ./general_ocr_rec_001.png --engine transformers该子命令默认加载PP-OCRv6_medium_rec识别模型见 paddleocr/_models/text_recognition.py。3.4 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_wirelesspp_structurev3子命令的参数极为丰富除了上表列出的通用参数外还包括布局检测--layout_threshold、--layout_nms、--layout_unclip_ratio、表格识别--wired_table_structure_recognition_model_name、--wireless_table_structure_recognition_model_name、印章识别--use_seal_recognition、--seal_det_thresh等、图表识别--use_chart_recognition、公式识别--use_formula_recognition、区域检测--use_region_detection等开关与模型配置完整定义见 paddleocr/_pipelines/pp_structurev3.py。四、Python 脚本使用CLI 之外PaddleOCR 3.x 提供面向对象 Python API。所有核心类均从 paddleocr/init.py 导出包括PaddleOCR、PPStructureV3、TextDetection、TextRecognition等。每个预测对象都遵循统一的predict模式返回结果列表每个结果支持print()打印、save_to_img()保存可视化图、save_to_json()保存 JSON。4.1 PP-OCRv6 整图 OCRPaddlePaddle 引擎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], ..., [ 1, 33]], ..., [[ 99, 455], ..., [ 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], ..., [ 1, 33]], ..., [[ 99, 455], ..., [ 99, 480]]], dtypeint16), rec_boxes: array([[ 1, ..., 33], ..., [ 99, ..., 480]], dtypeint16)}}结果字段解读字段含义doc_preprocessor_res文档预处理子结果angle为方向分类输出的旋转角度-1 表示无旋转dt_polys文本检测多边形坐标N×4×2int16text_det_params检测阶段的生效参数快照limit_side_len、thresh、box_thresh、unclip_ratio等rec_texts识别出的文本行列表rec_scores每行文本的置信度rec_polys/rec_boxes每行文本的多边形/矩形框坐标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([[[ 77, 551], ..., [ 78, 587]], ..., [[ 34, 408], ..., [ 36, 456]]], dtypeint16), dt_scores: [0.8562385635646694, 0.8818259002228059, 0.8406072284043453, 0.8855339313157491]}}检测结果包含dt_polys文本框多边形与dt_scores各框置信度。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: {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]}, ... ]}, overall_ocr_res: {input_path: None, page_index: None, model_settings: {use_doc_preprocessor: False, use_textline_orientation: False}, dt_polys: array([[[ 129, 42], ..., [ 129, 140]], ..., [[1156, 1330], ..., [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]), rec_polys: array([[[ 129, 42], ..., [ 129, 140]], ..., [[1156, 1330], ..., [1156, 1351]]], dtypeint16), rec_boxes: array([[ 129, ..., 140], ..., [1156, ..., 1351]], dtypeint16)}}}PP-StructureV3 的结果分两层layout_det_res输出版面分析结果cls_id对应paragraph_title、text、image、figure_title、doc_title等区域类别coordinate为 [x1, y1, x2, y2] 坐标overall_ocr_res输出整页 OCR 结果。此外相比 OCR 管线它还额外支持save_to_markdown()可直接产出结构化 Markdown便于喂给 LLM 或知识库。五、深入源码模型选择与关键参数5.1 默认模型与语言选择PaddleOCR在未显式指定检测/识别模型时会根据lang与ocr_version自动选择默认模型见 paddleocr/_pipelines/ocr.py不指定任何参数时默认使用PP-OCRv6 中量级模型对PP-OCRv6_medium_detPP-OCRv6_medium_rec支持ocr_version取PP-OCRv3/PP-OCRv4/PP-OCRv5/PP-OCRv6版本与语言不匹配如某语言尚无对应版本模型时会抛出明确错误支持 100 语言的lang参数PP-OCRv6 原生覆盖ch、chinese_cht、en、japan及全部拉丁语系其余语系韩语、泰语、希腊语、西里尔、阿拉伯、天城文等会自动回退到 PP-OCRv5 / PP-OCRv3 模型一旦显式传入text_detection_model_name/text_recognition_model_name或对应model_dirlang与ocr_version会被忽略并给出警告。单模型模块同理TextDetection默认PP-OCRv6_medium_detTextRecognition默认PP-OCRv6_medium_rec。5.2 旧版参数兼容为兼容 PaddleOCR 2.x 的调用习惯PaddleOCR内置了废弃参数映射表见 paddleocr/_pipelines/ocr.py如det_model_dir→text_detection_model_dir、rec_model_dir→text_recognition_model_dir、use_angle_cls→use_textline_orientation等。传入旧参数会触发弃用警告并自动映射但新旧参数同时传入会报错二者互斥。5.3 公共推理参数所有模型与管线均支持以下公共参数定义见 paddleocr/_common_args.py可用于性能与精度调优参数说明默认值--devicecpu/gpu/npu/gpu:0等有 GPU 用 GPU 0否则 CPU--use_tensorrt是否启用 Paddle Inference 的 TensorRT 子图加速视模型支持情况--precisionTensorRT 精度fp32/fp16默认值见 paddleocr/_constants.py--enable_mkldnnCPU 上启用 MKL-DNN 加速默认关闭--cpu_threadsCPU 推理线程数默认值见 paddleocr/_constants.py--enable_cinn是否启用 CINN 编译器默认关闭--enable_hpi是否启用高性能推理HPI默认关闭CLI 中的布尔参数如--use_doc_orientation_classify经由 paddleocr/_utils/cli.py 的str2bool解析接受true/yes/t/y/1等取值。六、常见注意事项引擎依赖不可混用--engine transformers要求已安装transformers5.8.0及其底层推理框架--engine paddle要求 PaddlePaddle ≥ 3.0。引擎缺失时预测器创建会因依赖检查失败而报错见 paddleocr/_models/base.py 的错误处理逻辑。PP-StructureV3 的 Transformers 适配尚未完全使用enginetransformers时需关闭公式识别use_formula_recognitionFalse并将无线表格结构识别模型替换为SLANeXt_wireless否则可能因模型未适配而失败。文档预处理是独立子管线use_doc_orientation_classify或use_doc_unwarping任一开启即会触发use_doc_preprocessorTrue增加前处理耗时对方向正常的单页图片官方示例通常显式关闭以追求速度。结果持久化单模型结果支持save_to_img/save_to_jsonPP-StructureV3 额外支持save_to_markdown适合直接作为 RAG/LLM 输入。至此你已经掌握了 PaddleOCR 3.x 的安装、CLI 与 Python API 用法以及关键参数的底层行为。更完整的模型清单、按需安装与性能调优指南可继续阅读 PaddleOCR 安装文档 与仓库中的 模型列表 等资料。【免费下载链接】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 快速上手指南：安装、命令行与 Python 推理实战
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 3.x 的官方快速入门指南对应仓库 docs/quick_start.en.md面向希望尽快把 OCR 能力跑起来的开发者。PaddleOCR 3.x 引入了统一推理引擎配置可在 PaddlePaddle 与 Hugging Face Transformers 之间自由切换底层运行时在此基础上本文会带你完成环境安装、命令行推理与 Python 脚本调用三个环节覆盖 PP-OCRv6 整图识别、文本检测、文本识别与 PP-StructureV3 文档结构化四条主线并结合仓库源码说明engine、use_doc_orientation_classify、use_doc_unwarping、use_textline_orientation等关键参数在底层是如何生效的。读完本文你将能够独立完成 PaddleOCR 3.x 的部署与二次开发。一、理解 PaddleOCR 3.x 的统一推理引擎机制PaddleOCR 3.x 在架构上最显著的变化是推理引擎与业务 API 解耦。无论是完整 OCR 管线PaddleOCR、文档结构化管线PPStructureV3还是单模型模块TextDetection/TextRecognition都通过一个统一的engine参数选择底层运行时。从源码看该机制实现在 paddleocr/_common_args.pySUPPORTED_INFERENCE_ENGINE_LIST [ paddle, paddle_static, paddle_dynamic, transformers, onnxruntime, ]即当前版本支持paddle默认、paddle_static、paddle_dynamic、transformers与onnxruntime五种引擎。所有模型与管线的公共参数device、engine、use_tensorrt、precision、enable_mkldnn、cpu_threads、enable_cinn等都会经过 parse_common_args 校验与归一化——例如引擎不在支持列表内会直接抛出ValueError。随后 prepare_common_init_args 会根据引擎类型与设备类型CPU/GPU自动组装engine_configGPU 上可选择 Paddle Inference 的 TensorRT 子图trt_fp32/trt_fp16CPU 上则可开启 MKL-DNN 加速。在命令行层面CLI 入口 paddleocr/_cli.py 会注册全部管线与模型子命令最终每个预测器的创建经由 paddleocr/_models/base.py 中的_create_paddlex_predictor调用 PaddleX 的create_predictor完成因此你既可以通过--engine paddle使用 PaddlePaddle也可以通过--engine transformers使用 Transformers。二、环境安装2.1 安装推理引擎PaddleOCR 支持统一推理引擎配置你可以按需选择底层运行时目前支持 PaddlePaddle 与 Transformers。选择一PaddlePaddleCPU 安装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/GPU 安装对 CUDA 版本有特定要求其他平台请参照 PaddlePaddle 官方安装文档进行。注意使用 PaddlePaddle 推理时PaddleOCR 3.x 依赖 PaddlePaddle3.0及以上版本。选择二Transformers使用 Transformers 引擎推理时安装 Hugging Face Transformerspython -m pip install transformers5.8.0多数情况下你还需要安装 Transformers 所依赖的底层推理框架具体请参见 Transformers 官方安装文档。2.2 安装paddleocr安装 PaddleOCR 的全部功能python -m pip install paddleocr[all]PaddleOCR 也支持按需安装特定功能如仅装 OCR 或仅装文档解析相关依赖详细说明见 PaddleOCR 安装文档。提示安装完成后可通过paddleocr -v或paddleocr --version查看版本信息版本号来源于 paddleocr/_version.py 中的importlib.metadata读取。三、命令行快速体验paddleocr安装后会注册同名 CLI 命令支持ocr、text_detection、text_recognition、pp_structurev3等子命令完整注册逻辑见 paddleocr/_cli.py。以下示例均以仓库演示图如general_ocr_002.png为输入。3.1 PP-OCRv6 整图 OCRPaddlePaddle 引擎paddleocr ocr -i ./general_ocr_002.png \ --use_doc_orientation_classify False \ --use_doc_unwarping False \ --use_textline_orientation False \ --engine paddleTransformers 引擎paddleocr ocr -i ./general_ocr_002.png \ --use_doc_orientation_classify False \ --use_doc_unwarping False \ --use_textline_orientation False \ --engine transformers参数说明均对应 paddleocr/_pipelines/ocr.py 中的 CLI 定义参数含义类型/默认行为-i, --input输入图片路径或 URL必填--engine推理引擎取值为paddle/paddle_static/paddle_dynamic/transformers/onnxruntime默认由 PaddleX 自动选择--use_doc_orientation_classify是否启用文档方向分类0°/90°/180°/270°布尔值True/False--use_doc_unwarping是否启用文档图像矫正去弯曲布尔值True/False--use_textline_orientation是否启用文本行方向分类解决单行文字倒置问题布尔值True/False--device推理设备如cpu、gpu、gpu:0默认 GPU 0 可用时用 GPU否则 CPU--save_path结果保存目录可选从源码看use_doc_orientation_classify与use_doc_unwarping二者任一为True时use_doc_preprocessor会被自动置为True见 paddleocr/_pipelines/ocr.py即进入文档预处理子管线。3.2 PP-OCRv6 文本检测模块PaddlePaddle 引擎paddleocr text_detection -i ./general_ocr_001.png --engine paddleTransformers 引擎paddleocr text_detection -i ./general_ocr_001.png --engine transformers该子命令默认加载PP-OCRv6_medium_det检测模型见 paddleocr/_models/text_detection.py并额外支持--limit_side_len、--limit_type、--thresh、--box_thresh、--unclip_ratio、--input_shape等检测参数定义见 paddleocr/_models/_text_detection.py。3.3 PP-OCRv6 文本识别模块PaddlePaddle 引擎paddleocr text_recognition -i ./general_ocr_rec_001.png --engine paddleTransformers 引擎paddleocr text_recognition -i ./general_ocr_rec_001.png --engine transformers该子命令默认加载PP-OCRv6_medium_rec识别模型见 paddleocr/_models/text_recognition.py。3.4 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_wirelesspp_structurev3子命令的参数极为丰富除了上表列出的通用参数外还包括布局检测--layout_threshold、--layout_nms、--layout_unclip_ratio、表格识别--wired_table_structure_recognition_model_name、--wireless_table_structure_recognition_model_name、印章识别--use_seal_recognition、--seal_det_thresh等、图表识别--use_chart_recognition、公式识别--use_formula_recognition、区域检测--use_region_detection等开关与模型配置完整定义见 paddleocr/_pipelines/pp_structurev3.py。四、Python 脚本使用CLI 之外PaddleOCR 3.x 提供面向对象 Python API。所有核心类均从 paddleocr/init.py 导出包括PaddleOCR、PPStructureV3、TextDetection、TextRecognition等。每个预测对象都遵循统一的predict模式返回结果列表每个结果支持print()打印、save_to_img()保存可视化图、save_to_json()保存 JSON。4.1 PP-OCRv6 整图 OCRPaddlePaddle 引擎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], ..., [ 1, 33]], ..., [[ 99, 455], ..., [ 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], ..., [ 1, 33]], ..., [[ 99, 455], ..., [ 99, 480]]], dtypeint16), rec_boxes: array([[ 1, ..., 33], ..., [ 99, ..., 480]], dtypeint16)}}结果字段解读字段含义doc_preprocessor_res文档预处理子结果angle为方向分类输出的旋转角度-1 表示无旋转dt_polys文本检测多边形坐标N×4×2int16text_det_params检测阶段的生效参数快照limit_side_len、thresh、box_thresh、unclip_ratio等rec_texts识别出的文本行列表rec_scores每行文本的置信度rec_polys/rec_boxes每行文本的多边形/矩形框坐标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([[[ 77, 551], ..., [ 78, 587]], ..., [[ 34, 408], ..., [ 36, 456]]], dtypeint16), dt_scores: [0.8562385635646694, 0.8818259002228059, 0.8406072284043453, 0.8855339313157491]}}检测结果包含dt_polys文本框多边形与dt_scores各框置信度。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: {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]}, ... ]}, overall_ocr_res: {input_path: None, page_index: None, model_settings: {use_doc_preprocessor: False, use_textline_orientation: False}, dt_polys: array([[[ 129, 42], ..., [ 129, 140]], ..., [[1156, 1330], ..., [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]), rec_polys: array([[[ 129, 42], ..., [ 129, 140]], ..., [[1156, 1330], ..., [1156, 1351]]], dtypeint16), rec_boxes: array([[ 129, ..., 140], ..., [1156, ..., 1351]], dtypeint16)}}}PP-StructureV3 的结果分两层layout_det_res输出版面分析结果cls_id对应paragraph_title、text、image、figure_title、doc_title等区域类别coordinate为 [x1, y1, x2, y2] 坐标overall_ocr_res输出整页 OCR 结果。此外相比 OCR 管线它还额外支持save_to_markdown()可直接产出结构化 Markdown便于喂给 LLM 或知识库。五、深入源码模型选择与关键参数5.1 默认模型与语言选择PaddleOCR在未显式指定检测/识别模型时会根据lang与ocr_version自动选择默认模型见 paddleocr/_pipelines/ocr.py不指定任何参数时默认使用PP-OCRv6 中量级模型对PP-OCRv6_medium_detPP-OCRv6_medium_rec支持ocr_version取PP-OCRv3/PP-OCRv4/PP-OCRv5/PP-OCRv6版本与语言不匹配如某语言尚无对应版本模型时会抛出明确错误支持 100 语言的lang参数PP-OCRv6 原生覆盖ch、chinese_cht、en、japan及全部拉丁语系其余语系韩语、泰语、希腊语、西里尔、阿拉伯、天城文等会自动回退到 PP-OCRv5 / PP-OCRv3 模型一旦显式传入text_detection_model_name/text_recognition_model_name或对应model_dirlang与ocr_version会被忽略并给出警告。单模型模块同理TextDetection默认PP-OCRv6_medium_detTextRecognition默认PP-OCRv6_medium_rec。5.2 旧版参数兼容为兼容 PaddleOCR 2.x 的调用习惯PaddleOCR内置了废弃参数映射表见 paddleocr/_pipelines/ocr.py如det_model_dir→text_detection_model_dir、rec_model_dir→text_recognition_model_dir、use_angle_cls→use_textline_orientation等。传入旧参数会触发弃用警告并自动映射但新旧参数同时传入会报错二者互斥。5.3 公共推理参数所有模型与管线均支持以下公共参数定义见 paddleocr/_common_args.py可用于性能与精度调优参数说明默认值--devicecpu/gpu/npu/gpu:0等有 GPU 用 GPU 0否则 CPU--use_tensorrt是否启用 Paddle Inference 的 TensorRT 子图加速视模型支持情况--precisionTensorRT 精度fp32/fp16默认值见 paddleocr/_constants.py--enable_mkldnnCPU 上启用 MKL-DNN 加速默认关闭--cpu_threadsCPU 推理线程数默认值见 paddleocr/_constants.py--enable_cinn是否启用 CINN 编译器默认关闭--enable_hpi是否启用高性能推理HPI默认关闭CLI 中的布尔参数如--use_doc_orientation_classify经由 paddleocr/_utils/cli.py 的str2bool解析接受true/yes/t/y/1等取值。六、常见注意事项引擎依赖不可混用--engine transformers要求已安装transformers5.8.0及其底层推理框架--engine paddle要求 PaddlePaddle ≥ 3.0。引擎缺失时预测器创建会因依赖检查失败而报错见 paddleocr/_models/base.py 的错误处理逻辑。PP-StructureV3 的 Transformers 适配尚未完全使用enginetransformers时需关闭公式识别use_formula_recognitionFalse并将无线表格结构识别模型替换为SLANeXt_wireless否则可能因模型未适配而失败。文档预处理是独立子管线use_doc_orientation_classify或use_doc_unwarping任一开启即会触发use_doc_preprocessorTrue增加前处理耗时对方向正常的单页图片官方示例通常显式关闭以追求速度。结果持久化单模型结果支持save_to_img/save_to_jsonPP-StructureV3 额外支持save_to_markdown适合直接作为 RAG/LLM 输入。至此你已经掌握了 PaddleOCR 3.x 的安装、CLI 与 Python API 用法以及关键参数的底层行为。更完整的模型清单、按需安装与性能调优指南可继续阅读 PaddleOCR 安装文档 与仓库中的 模型列表 等资料。【免费下载链接】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），仅供参考