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.py：

SUPPORTED_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_config：GPU 上可选择 Paddle Inference 的 TensorRT 子图（trt_fp32/trt_fp16），CPU 上则可开启 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。

选择一：PaddlePaddle

CPU 安装：

python -m pip install paddlepaddle==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/

GPU 安装（以 Linux 平台 + CUDA 11.8 为例）：

python -m pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/

GPU 安装对 CUDA 版本有特定要求，其他平台请参照 PaddlePaddle 官方安装文档进行。注意：使用 PaddlePaddle 推理时，PaddleOCR 3.x 依赖 PaddlePaddle3.0及以上版本。

选择二：Transformers

使用 Transformers 引擎推理时，安装 Hugging Face Transformers：

python -m pip install "transformers>=5.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 整图 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

参数说明（均对应 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 paddle

Transformers 引擎：

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 paddle

Transformers 引擎：

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 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

pp_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 整图 OCR

PaddlePaddle 引擎：

from paddleocr import PaddleOCR ocr = PaddleOCR( use_doc_orientation_classify=False, use_doc_unwarping=False, use_textline_orientation=False, engine="paddle", ) 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_classify=False, use_doc_unwarping=False, use_textline_orientation=False, engine="transformers", ) 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]]], dtype=int16), '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]]], dtype=int16), 'rec_boxes': array([[ 1, ..., 33], ..., [ 99, ..., 480]], dtype=int16)}}

结果字段解读：

字段	含义
doc_preprocessor_res	文档预处理子结果，angle为方向分类输出的旋转角度（-1 表示无旋转）
dt_polys	文本检测多边形坐标（N×4×2，int16）
text_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(engine="paddle") 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(engine="transformers") 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]]], dtype=int16), '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(engine="paddle") output = model.predict(input="general_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(engine="transformers") output = model.predict(input="general_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_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") res.save_to_markdown(save_path="output")

Transformers 引擎（当前部分模型仍在适配中，需关闭公式识别并替换无线表格结构识别模型）：

from paddleocr import PPStructureV3 pipeline = PPStructureV3( use_doc_orientation_classify=False, use_doc_unwarping=False, use_formula_recognition=False, wireless_table_structure_recognition_model_name="SLANeXt_wireless", engine="transformers", ) output = pipeline.predict(input="./pp_structure_v3_demo.png") for res in output: res.print() res.save_to_json(save_path="output") res.save_to_markdown(save_path="output")

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]]], dtype=int16), '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]]], dtype=int16), 'rec_boxes': array([[ 129, ..., 140], ..., [1156, ..., 1351]], dtype=int16)}}}

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_det+PP-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_dir），lang与ocr_version会被忽略并给出警告。

单模型模块同理：TextDetection默认PP-OCRv6_medium_det，TextRecognition默认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），可用于性能与精度调优：

参数	说明	默认值
--device	cpu/gpu/npu/gpu:0等	有 GPU 用 GPU 0，否则 CPU
--use_tensorrt	是否启用 Paddle Inference 的 TensorRT 子图加速	视模型支持情况
--precision	TensorRT 精度（fp32/fp16）	默认值见 paddleocr/_constants.py
--enable_mkldnn	CPU 上启用 MKL-DNN 加速	默认关闭
--cpu_threads	CPU 推理线程数	默认值见 paddleocr/_constants.py
--enable_cinn	是否启用 CINN 编译器	默认关闭
--enable_hpi	是否启用高性能推理（HPI）	默认关闭

CLI 中的布尔参数（如--use_doc_orientation_classify）经由 paddleocr/_utils/cli.py 的str2bool解析，接受true/yes/t/y/1等取值。

六、常见注意事项

1. 引擎依赖不可混用：--engine transformers要求已安装transformers>=5.8.0及其底层推理框架；--engine paddle要求 PaddlePaddle ≥ 3.0。引擎缺失时，预测器创建会因依赖检查失败而报错（见 paddleocr/_models/base.py 的错误处理逻辑）。
2. PP-StructureV3 的 Transformers 适配尚未完全：使用engine="transformers"时，需关闭公式识别（use_formula_recognition=False）并将无线表格结构识别模型替换为SLANeXt_wireless，否则可能因模型未适配而失败。
3. 文档预处理是独立子管线：use_doc_orientation_classify或use_doc_unwarping任一开启即会触发use_doc_preprocessor=True，增加前处理耗时；对方向正常的单页图片，官方示例通常显式关闭以追求速度。
4. 结果持久化：单模型结果支持save_to_img/save_to_json；PP-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