PaddleOCR × PaddleX 快速上手指南：OCR 流水线的低代码推理实战（CLI 与 Python 双路径）

PaddleOCR × PaddleX 快速上手指南：OCR 流水线的低代码推理实战（CLI 与 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

PaddleX 是 PaddlePaddle 推出的低代码开发工具，它深度融合了 PaddleOCR 的先进 OCR 技术，为用户提供端到端低代码开发能力，覆盖模型的使用、组合与定制。本文以 docs/version3.x/paddlex/quick_start.en.md 为骨架，完整讲解 OCR 相关 Pipeline 的环境安装、统一 CLI 命令、Python 脚本调用三种使用方式，并深入 paddleocr/_pipelines 源码揭示paddlex与 PaddleOCR 的底层协作机制。读完本文，你将掌握：一条命令跑通通用 OCR、表格识别、版面解析、公式识别等 8 条 Pipeline，以及用几行 Python 代码完成推理并将结果输出为图片与 JSON 的完整技能。

一、PaddleOCR 与 PaddleX 的关系：先理解“Pipeline”是什么

在开始使用之前，需要先厘清两个概念：

• PaddleX：PaddlePaddle 官方推出的低代码开发工具，承载了 PaddleOCR 的先进技术，在 OCR 领域支持端到端低代码开发，让用户能够简单、高效地实现模型的使用、组合与定制。PaddleX 与 PaddleOCR 的完整关系说明可参见 docs/version3.x/paddleocr_and_paddlex.md。
• 模型 Pipeline（模型流水线）：指针对特定 AI 任务预先定义的一系列开发流程，由多个可以独立完成特定任务的**单模型（单功能模块）**组合而成。PaddleX 致力于生产级的模型训练、推理与部署，本指南聚焦于OCR 相关 Pipeline 的快速推理使用；单功能模块的快速使用与更多特性，可参阅 docs/version3.x/paddlex/overview.md。

从仓库源码可以印证这一设计：在 paddleocr/_pipelines/init.py 中，PaddleOCR 的各类 Pipeline 均以独立类形式导出，包括DocPreprocessor（文档图像预处理）、PaddleOCR（通用 OCR）、PPChatOCRv4Doc（文档场景信息抽取）、PPStructureV3（版面解析）、SealRecognition（印章识别）、TableRecognitionPipelineV2（表格识别 v2）、FormulaRecognitionPipeline（公式识别）等。这些类统一包装自 PaddleX 的create_pipeline能力（见 paddleocr/_pipelines/base.py 中的PaddleXPipelineWrapper），也就是说PaddleOCR 的 Pipeline API 底层就是 PaddleX Pipeline，二者是同一套推理体系的一体两面。

二、环境准备与安装

2.1 前置条件

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

2.2 安装 PaddlePaddle

根据硬件环境选择对应的安装命令（==3.0.0为文档对应版本，其余兼容版本可参考 PaddlePaddle 官方安装说明）：

# CPU 版本 python -m pip install paddlepaddle==3.0.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ # GPU 版本（CUDA 11.8），需要 GPU 驱动 ≥ 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 版本（CUDA 12.6），需要 GPU 驱动 ≥ 550.54.14（Linux 或 Windows） python -m pip install paddlepaddle-gpu==3.0.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/

❗ 安装时无需关注物理机上的 CUDA 版本，只需关注 GPU 驱动版本。PaddlePaddle 的 Wheel 版本说明详见其官方网站安装文档。

2.3 安装 PaddleX

pip install "paddlex[ocr]"

其中[ocr]为 OCR 相关附加依赖组，安装完成后即可获得paddlex命令行工具。其他安装方式（如源码安装、docker 镜像等）请参考 PaddleX 官方安装指南。

三、CLI 命令行使用：一条命令体验 Pipeline

3.1 统一命令行格式

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

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

每条 Pipeline 都有其对应的专属参数，可在各 Pipeline 文档中查看详细说明。所有 Pipeline 都必须指定以下三个必要参数：

3.2 以 OCR Pipeline 为例

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

该命令的含义：

• --pipeline OCR：调用通用 OCR Pipeline；
• --input：直接传入一张网络 URL 图片（也支持本地路径与目录，paddlex会自动下载并处理）；
• --use_doc_orientation_classify False：关闭文档方向分类（适合输入图片方向已正确的情况，可省去一次前处理推理）；
• --use_doc_unwarping False：关闭文档去扭曲（弯曲文档矫正）；
• --use_textline_orientation False：关闭文本行方向分类；
• --save_path ./output：可视化结果与 JSON 结果输出目录；
• --device gpu:0：指定使用第 0 块 GPU。

运行后将输出结构化推理结果，其核心字段（与仓库源码 paddleocr/_pipelines/ocr.py 中predict_iter暴露的参数一一对应）如下：

{'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/rec_boxes：与识别结果对齐的文本框坐标；
• rec_texts：识别出的文本内容列表；
• rec_scores：每条文本的置信度分数；
• text_det_params：本次运行使用的检测后处理参数（limit_side_len=960限制最长边、thresh=0.3二值化阈值、box_thresh=0.6框过滤阈值、unclip_ratio=2.0框外扩系数）；
• textline_orientation_angles：文本行方向分类输出的角度；
• model_settings/doc_preprocessor_res：记录各子模块是否启用的运行配置。

这些参数与 paddleocr/_pipelines/ocr.py 中predict_iter的可覆盖参数完全对应：use_doc_orientation_classify、use_doc_unwarping、use_textline_orientation、text_det_limit_side_len、text_det_limit_type、text_det_thresh、text_det_box_thresh、text_det_unclip_ratio、text_rec_score_thresh、return_word_box。也就是说，CLI 里的--use_doc_orientation_classify等参数最终会传递到 PaddleX Pipeline 的predict调用中，与 Python API 完全等价。

3.3 各 Pipeline 的 CLI 命令一览

使用命令行调用其他 Pipeline 时，只需将pipeline参数改为对应 Pipeline 名称并调整相关参数即可。下表为 8 条常用 OCR 相关 Pipeline 的完整命令：

使用提示：

• 公式识别 Pipeline 额外暴露了版面检测参数（--layout_threshold、--layout_nms、--layout_unclip_ratio、--layout_merge_bboxes_mode），因为公式往往嵌在版面中，需要先做版面分析定位公式区域；
• 所有命令中的--input均可替换为本地图片路径或目录，PaddleX 会批量处理目录下的所有图片；
• 命令后未指定--save_path时仍会在终端打印结构化结果，指定后额外保存可视化图与 JSON。

3.4 CLI 的通用可选参数（来自仓库实现）

从 paddleocr/_common_args.py 的add_common_cli_opts可以看到，所有 Pipeline 子命令还支持以下通用选项（默认值定义于 paddleocr/_constants.py）：

这些参数最终会通过 paddleocr/_common_args.py 的prepare_common_init_args转换为 PaddleX 的初始化参数（如设备解析、paddle_static 引擎配置、TensorRT 运行模式trt_fp32/trt_fp16等），并随create_pipeline一同生效。

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

4.1 统一脚本模板

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

脚本依次执行了以下步骤：

1. create_pipeline()实例化 Pipeline 对象；
2. 传入图片并调用 Pipeline 对象的predict()方法进行推理预测；
3. 处理预测结果：res.print()在终端打印结构化结果，res.save_to_img("./output/")保存可视化结果图，res.save_to_json("./output/")将完整结果导出为 JSON 文件。

4.2 各 Pipeline 的 Python 参数名一览

使用 Python 脚本调用其他 Pipeline 时，只需调整create_pipeline()中的 Pipeline 参数名。下表汇总了 10 条流水线的参数名与详细说明位置：

各 Pipeline 的 Python 脚本集成示例详见 PaddleX 官方对应 Pipeline 的“Python 脚本集成”章节（文档中以外部链接给出）。

4.3 在 PaddleOCR 仓库内的等价写法

如果你已经安装了本仓库的paddleocr包，可以直接使用 PaddleOCR 自带的 Pipeline 类完成等价推理。例如通用 OCR：

from paddleocr import PaddleOCR ocr = PaddleOCR( text_detection_model_name="PP-OCRv5_server_det", text_recognition_model_name="PP-OCRv5_server_rec", use_doc_orientation_classify=False, use_doc_unwarping=False, use_textline_orientation=False, ) result = ocr.predict("demo.png") res = result[0] res.print() res.save_to_img("./output/") res.save_to_json("./output/")

这在仓库测试 tests/pipelines/test_ocr.py 中有完整印证：测试用PP-OCRv5_server_det+PP-OCRv5_server_rec组合实例化PaddleOCR，并断言dt_polys、rec_texts非空。该测试还逐一验证了use_doc_orientation_classify、use_doc_unwarping、use_textline_orientation、text_det_limit_side_len、text_det_thresh、text_det_box_thresh、text_det_unclip_ratio、text_rec_score_thresh等参数的透传行为（tests/pipelines/test_ocr.py），可作为你调参时的官方参考用例。

五、源码级原理剖析：paddlex 命令与 Pipeline 是怎么串起来的

5.1 CLI 入口与子命令注册

paddlex命令行工具安装后即注册为系统命令。在仓库中，PaddleOCR 自带的paddleocr命令入口定义于 pyproject.toml：paddleocr = "paddleocr.__main__:console_entry"。而 paddleocr/_cli.py 中的_register_pipelines会把 paddleocr/_pipelines/init.py 导出的全部 Pipeline 类逐一注册为 argparse 子命令，每个子命令再通过各自的get_cli_subcommand_executor()绑定参数解析与执行逻辑。

5.2 Python API 与 PaddleX 的对接

在 paddleocr/_pipelines/base.py 中，PaddleXPipelineWrapper是 PaddleOCR 所有 Pipeline 类的公共基类：

• 初始化时通过load_pipeline_config加载 PaddleX 的 Pipeline 默认配置，再与用户覆盖参数合并（_get_merged_paddlex_config）；
• 最终调用 PaddleX 的create_pipeline(config=..., **kwargs)完成 Pipeline 实例化（paddleocr/_pipelines/base.py）；
• 依赖缺失时会抛出DependencyError并提示“请参考安装文档补齐依赖”，这正是前文强调安装paddlex[ocr]的原因。

以 OCR 为例，paddleocr/_pipelines/ocr.py 中PaddleOCR类的_paddlex_pipeline_name返回"OCR"（paddleocr/_pipelines/ocr.py），即其包装的正是 PaddleX 的 OCR Pipeline。此外该类还内置了版本与语言约束：支持PP-OCRv3 / PP-OCRv4 / PP-OCRv5 / PP-OCRv6四个 OCR 版本（paddleocr/_pipelines/ocr.py），并针对拉丁语系、阿拉伯语系、西里尔语系等做语言到模型名的自动映射，方便多语言场景开箱即用。

5.3 推理调用链

一次pipeline.predict(input)的完整调用链为：

CLI: paddlex --pipeline OCR ... └─ Pipeline 子命令参数解析（argparse） └─ PaddleX OCR Pipeline 的 predict() ├─ doc_preprocessor（文档方向分类 / 去扭曲，可开关） ├─ text_detection（文本检测，输出 dt_polys） ├─ textline_orientation（文本行方向分类，可开关） └─ text_recognition（文本识别，输出 rec_texts / rec_scores） └─ 结果对象：res.print() / res.save_to_img() / res.save_to_json()

在 paddleocr/_pipelines/ocr.py 中可以看到，predict_iter将用户传入的开关与调参参数（use_doc_orientation_classify等）原样转发给底层 PaddleX Pipeline 的predict，随后predict将其收集为列表返回（paddleocr/_pipelines/ocr.py）。这也解释了为什么 CLI 参数名与 Python API 参数名完全一致——它们最终流向同一个 PaddleX 推理内核。

六、常见使用技巧与注意事项

1. 设备选择：机器没有 GPU 时将--device gpu:0换成--device cpu即可运行，无需修改其他参数；NPU（npu:0）与 XPU（xpu:0）设备同理。
2. 输入形态：--input同时支持本地单图、本地目录（批量）与 URL；Python 的predict()同样接受这些输入形态。
3. 关闭不必要的子模块：方向正确、无扭曲的扫描件建议关闭use_doc_orientation_classify与use_doc_unwarping，可以显著减少前处理推理耗时；use_textline_orientation用于倾斜文本行矫正，普通横排文本可关闭。
4. 结果落盘：CLI 通过--save_path指定输出目录；Python 通过res.save_to_img()/res.save_to_json()分别保存可视化结果与结构化 JSON，便于后续接入业务系统。
5. 定制与扩展：Pipeline 支持单模型（单功能模块）的自由组合与定制，例如替换检测/识别模型（text_detection_model_name、text_recognition_model_name）、调整检测后处理阈值（text_det_thresh、text_det_box_thresh、text_det_unclip_ratio）或识别置信度阈值（text_rec_score_thresh），均可在 CLI 参数与 Python API 中直接覆盖，详见 paddleocr/_pipelines/ocr.py。
6. 从低代码走向生产：PaddleX Pipeline 的能力不止于快速推理，还覆盖训练、部署等生产环节；单功能模块使用、模型组合定制等更完整的低代码开发玩法，可继续阅读 docs/version3.x/paddlex/overview.md 与 docs/version3.x/paddleocr_and_paddlex.md。

七、小结

PaddleX 把 PaddleOCR 的检测、识别、方向分类、去扭曲、版面分析、表格/公式/印章识别等能力封装为开箱即用的 Pipeline：安装只需pip install "paddlex[ocr]"并搭配 PaddlePaddle 3.0.0+；使用既有一行命令的 CLI（paddlex --pipeline OCR --input <img> --device gpu:0），也有create_pipeline+predict的 Python 脚本；底层通过 paddleocr/_pipelines/base.py 的PaddleXPipelineWrapper与 PaddleX 推理内核无缝衔接。掌握本文的安装、CLI、Python 三种用法与关键参数后，你即可在通用 OCR、文档预处理、表格识别、公式识别、印章识别、版面解析、PP-StructureV3 等场景中快速落地生产级 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