PaddleOCR 快速开始：基于 PaddleX 低代码产线的一行命令与 Python 推理实战指南

PaddleOCR 快速开始：基于 PaddleX 低代码产线的一行命令与 Python 推理实战指南

【免费下载链接】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 3.x 的 PaddleX 低代码产线能力展开，聚焦于安装环境、统一命令行推理、Python 脚本推理三大主线，并延伸到产线配置文件的导出与加载等进阶用法。读完本文，你将掌握如何用一条命令或几行 Python 代码，快速跑通通用 OCR、表格识别、公式识别、版面解析、印章识别等产线，同时了解这些产线在仓库源码中的真实注册与调用机制。

一、前置认知：什么是 PaddleX 产线

PaddleX 是飞桨（PaddlePaddle）推出的低代码开发工具，依托 PaddleOCR 的先进技术，支持 OCR 领域的低代码全流程开发——模型的使用、组合与定制都可以通过简单高效的方式完成。本仓库文档 PaddleOCR 与 PaddleX 明确指出：PaddleOCR 在模型推理、前后处理及多模型组合等底层能力上主要依赖 PaddleX，安装 PaddleOCR 时 PaddleX 会作为依赖一并安装，且两者在产线名称上保持一致。

模型产线（Pipeline）是指一系列预定义好的、针对特定 AI 任务的开发流程，包含能够独立完成某类任务的单模型（单功能模块）组合。PaddleX 致力于实现产线级别的模型训练、推理与部署，本文档（quick_start.en.md）提供OCR 相关产线的快速推理使用指南，覆盖以下产线：

在仓库源码中，PaddleOCR 通过PaddleXPipelineWrapper这一基类将上述产线逐一封装，见 paddleocr/_pipelines/base.py 与 paddleocr/_pipelines/init.py：其中注册了PaddleOCR（对应产线OCR）、DocPreprocessor、TableRecognitionPipelineV2、FormulaRecognitionPipeline、SealRecognition、PPStructureV3、PPChatOCRv4Doc等类，每个类通过_paddlex_pipeline_name属性声明自己对应的 PaddleX 产线注册名，例如 paddleocr/_pipelines/ocr.py 中_paddlex_pipeline_name返回"OCR"。

二、环境安装：PaddlePaddle + PaddleX

❗ 在安装 PaddleX 之前，请确保已具备基本的Python 运行环境（目前支持 Python 3.8 至 Python 3.13）。PaddleX 3.2 版本依赖的 PaddlePaddle 版本为3.0.0 及以上。

2.1 安装 PaddlePaddle

根据运行设备选择对应的飞桨安装命令：

# CPU 版本 python -m pip install paddlepaddle==3.0.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ # GPU 版本（cu118），需显卡驱动程序版本 ≥450.80.02（Linux）或 ≥452.39（Windows） python -m pip install paddlepaddle-gpu==3.0.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/ # GPU 版本（cu126），需显卡驱动程序版本 ≥550.54.14（Linux 或 Windows） python -m pip install paddlepaddle-gpu==3.0.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/

❗关键提示：无需关注物理机上的 CUDA 版本，只需关注显卡驱动程序版本。驱动版本满足要求即可运行对应 Wheel 包，这大幅降低了 GPU 环境的搭建门槛。

2.2 安装 PaddleX

pip install "paddlex[ocr]"

[ocr]是 PaddleX 的可选依赖标记，表示只安装 OCR 类任务所需依赖，避免无关依赖导致体积膨胀。这一点与 PaddleOCR 与 PaddleX 关系文档 的说明一致：安装paddleocrPython 分发包时只会安装 OCR 类任务需要使用的 PaddleX 依赖。

安装完成后，即可使用paddlex命令行工具，或通过from paddlex import create_pipeline进行 Python 开发。

三、命令行使用：一行命令快速体验产线

PaddleX 提供了统一的命令行格式，一条命令即可快速体验产线效果：

paddlex --pipeline [产线名称] --input [输入图片] --device [运行设备]

每条产线对应特定的参数，可在各自产线文档中查看详细说明。每条产线都必须指定以下三个必要参数：

3.1 通用 OCR 产线示例

以通用 OCR 产线为例，一条命令即可完成“文档方向分类 + 文档矫正 + 文本行方向分类 + 文本检测 + 文本识别”的全流程推理：

paddlex --pipeline OCR \ --input https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_002.png \ --use_doc_orientation_classify False \ --use_doc_unwarping False \ --use_textline_orientation False \ --save_path ./output \ --device gpu:0

其中--use_doc_orientation_classify、--use_doc_unwarping、--use_textline_orientation分别控制是否启用文档方向分类、文档扭曲矫正、文本行方向分类；--save_path指定可视化结果与 JSON 结果的保存目录。当输入为一般场景图（无旋转、无扭曲）时，将这三项设为False可跳过不必要的子产线，提升推理效率。

运行结束后，终端会输出类似如下的结构化结果（节选）：

{'res': {'input_path': 'general_ocr_002.png', 'page_index': None, 'model_settings': {'use_doc_preprocessor': False, 'use_textline_orientation': False}, 'doc_preprocessor_res': {'input_path': None, 'model_settings': {'use_doc_orientation_classify': True, 'use_doc_unwarping': False}, 'angle': 0}, 'dt_polys': [array([[ 3, 10], [82, 10], [82, 33], [ 3, 33]], dtype=int16), ...], 'text_det_params': {'limit_side_len': 960, 'limit_type': 'max', 'thresh': 0.3, 'box_thresh': 0.6, 'unclip_ratio': 2.0}, 'text_type': 'general', 'textline_orientation_angles': [-1, ...], 'text_rec_score_thresh': 0.0, 'rec_texts': ['www.99*', ...], 'rec_scores': [0.8980069160461426, ...], 'rec_polys': [array([[ 3, 10], [82, 10], [82, 33], [ 3, 33]], dtype=int16), ...], 'rec_boxes': array([[ 3, 10, 82, 33], ...], dtype=int16)}}

对结果进行解读：

• dt_polys/rec_polys：文本检测与识别得到的四边形框坐标（4 个顶点，dtype=int16）；
• text_det_params：本次文本检测子模块使用的实际参数，包括limit_side_len=960、limit_type='max'、thresh=0.3、box_thresh=0.6、unclip_ratio=2.0，对应检测后处理中的阈值与文本框扩张系数；
• rec_texts/rec_scores：识别出的文本内容及置信度（如0.898）；
• rec_boxes：识别框以[x1, y1, x2, y2]形式输出的数组。

同时，--save_path ./output指定的目录下会生成可视化标注结果，方便直接检查检测与识别效果。

3.2 各 OCR 相关产线的命令行一览

其他产线的命令行使用，只需将pipeline参数调整为相应产线名称，并修改为对应产线的参数即可。下表汇总了本仓库文档给出的全部产线命令：

从命令可以观察到一个规律：通用 OCR、版面解析、PP-StructureV3 等产线共享--use_doc_orientation_classify、--use_doc_unwarping、--use_textline_orientation三个开关参数；公式识别产线还额外引入了版面检测参数（--use_layout_detection、--layout_threshold、--layout_nms、--layout_unclip_ratio、--layout_merge_bboxes_mode），用于先定位公式所在区域再执行识别。

四、Python 脚本使用：几行代码完成快速推理

除了命令行，PaddleX 还提供了统一的 Python 脚本接口，几行代码即可完成产线的快速推理，统一格式如下：

from paddlex import create_pipeline pipeline = create_pipeline(pipeline=[产线名称]) output = pipeline.predict([输入图片名称]) for res in output: res.print() res.save_to_img("./output/") res.save_to_json("./output/")

脚本执行了如下三个步骤：

1. create_pipeline()实例化产线对象；
2. 传入图片并调用产线对象的predict()方法进行推理预测；
3. 对预测结果进行处理：res.print()在终端打印结构化结果，res.save_to_img()保存可视化图片，res.save_to_json()保存 JSON 格式的推理结果。

4.1 各产线的 Python 脚本参数一览

其他产线的 Python 脚本使用，只需将create_pipeline()方法的pipeline参数调整为相应产线的名称即可。下表汇总了文档给出的全部产线参数：

4.2 源码视角：产线对象是如何创建的

从源码层面看，PaddleOCR 的产线封装基于PaddleXPipelineWrapper基类（见 paddleocr/_pipelines/base.py）：

• 初始化时通过paddlex的load_pipeline_config加载产线默认配置，再调用create_pipeline(config=...)创建真实的 PaddleX 产线对象（_create_paddlex_pipeline方法）；
• 子类通过_get_paddlex_config_overrides()返回配置覆盖项，例如 paddleocr/_pipelines/ocr.py 中定义了一整张STRUCTURE映射，把PaddleOCR的 Python 参数（如text_det_thresh、text_rec_score_thresh）映射到 PaddleX 产线配置的SubModules.TextDetection.thresh、SubModules.TextRecognition.score_thresh等键上，从而实现参数的无缝透传；
• 基类还提供export_paddlex_config_to_yaml()方法，可将合并后的完整产线配置导出为 YAML 文件，便于深度调参与版本管理。

这也解释了为什么命令行参数与 Python 参数能够保持高度一致：它们最终都汇入同一条 PaddleX 产线配置。

五、进阶用法：产线配置文件的导出与加载

当默认参数无法满足需求时，可以通过产线配置文件实现深度定制。相关能力在 PaddleOCR 与 PaddleX 关系文档 中有完整说明：

5.1 导出产线配置文件

方式一：调用 PaddleOCR 产线对象的export_paddlex_config_to_yaml方法：

from paddleocr import PaddleOCR pipeline = PaddleOCR() pipeline.export_paddlex_config_to_yaml("ocr_config.yaml")

上述代码会在工作目录下生成ocr_config.yaml产线配置文件。

方式二：通过 PaddleX CLI 获取，指定产线注册名即可：

paddlex --get_pipeline_config OCR

5.2 加载产线配置文件

• CLI 方式：通过--paddlex_config参数指定配置文件路径，PaddleOCR 会将其内容作为产线默认配置（优先级高于各参数默认初始化值）：

paddleocr ocr --paddlex_config ocr_config.yaml ...

• Python API 方式：初始化产线对象时通过paddlex_config参数传入配置文件路径或配置字典：

from paddleocr import PaddleOCR pipeline = PaddleOCR(paddlex_config="ocr_config.yaml")

从源码实现看（paddleocr/_pipelines/base.py），当paddlex_config为字符串时按路径调用load_pipeline_config加载，为字典时直接作为配置，随后与子类的配置覆盖项通过_merge_dicts合并，最终传给create_pipeline。

六、版本对应关系与更多资源

PaddleOCR 与 PaddleX、飞桨框架的版本对应关系（摘录自 PaddleOCR 与 PaddleX 关系文档）：

建议在安装时保持三者版本匹配，避免 API 差异导致的问题。

如需进一步深入，可以在本仓库中继续阅读以下资源：

• 低代码全流程开发总览：产线能力矩阵、OCR 相关单功能模块清单；
• PaddleOCR 与 PaddleX 关系介绍：两者定位区别、产线注册名对应关系与版本对应表；
• 产线封装源码：paddleocr/_pipelines/base.py、paddleocr/_pipelines/ocr.py、paddleocr/_pipelines/init.py；
• 产线单元测试：tests/pipelines/test_ocr.py、tests/pipelines/test_doc_preprocessor.py、tests/pipelines/test_table_recognition_v2.py 等，可用于验证各产线的正确调用方式与参数行为。

结语

通过本文，你已掌握 PaddleX 低代码产线从安装、命令行体验到 Python 脚本推理的完整路径，并理解了产线在 PaddleOCR 仓库中的底层封装机制（PaddleXPipelineWrapper→create_pipeline→ 参数映射）。无论是快速验证预训练模型效果，还是通过配置文件深度定制推理参数，都可以基于统一的产线 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