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/PaddleOCRPaddleX 是 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”是什么在开始使用之前需要先厘清两个概念PaddleXPaddlePaddle 官方推出的低代码开发工具承载了 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 paddlepaddle3.0.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ # GPU 版本CUDA 11.8需要 GPU 驱动 ≥ 450.80.02Linux或 ≥ 452.39Windows python -m pip install paddlepaddle-gpu3.0.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/ # GPU 版本CUDA 12.6需要 GPU 驱动 ≥ 550.54.14Linux 或 Windows python -m pip install paddlepaddle-gpu3.0.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/❗ 安装时无需关注物理机上的 CUDA 版本只需关注 GPU 驱动版本。PaddlePaddle 的 Wheel 版本说明详见其官方网站安装文档。2.3 安装 PaddleXpip install paddlex[ocr]其中[ocr]为 OCR 相关附加依赖组安装完成后即可获得paddlex命令行工具。其他安装方式如源码安装、docker 镜像等请参考 PaddleX 官方安装指南。三、CLI 命令行使用一条命令体验 Pipeline3.1 统一命令行格式PaddleX 提供了统一格式的命令行入口一条命令即可快速体验 Pipeline 效果paddlex --pipeline [Pipeline 名称] --input [输入图片] --device [运行设备]每条 Pipeline 都有其对应的专属参数可在各 Pipeline 文档中查看详细说明。所有 Pipeline 都必须指定以下三个必要参数参数说明pipelinePipeline 的名称或 Pipeline 的配置文件路径input输入文件的本地路径、目录或 URL如图片device使用的硬件设备及索引例如gpu:0表示使用第 0 块 GPU也可以选择 NPUnpu:0、XPUxpu:0、CPUcpu等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]], dtypeint16), ...], 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]], dtypeint16), ...], rec_boxes: array([[ 3, 10, 82, 33], ...], dtypeint16)}}结果字段速查dt_polys文本检测得到的四边形框顶点坐标检测阶段输出rec_polys/rec_boxes与识别结果对齐的文本框坐标rec_texts识别出的文本内容列表rec_scores每条文本的置信度分数text_det_params本次运行使用的检测后处理参数limit_side_len960限制最长边、thresh0.3二值化阈值、box_thresh0.6框过滤阈值、unclip_ratio2.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 名称命令OCRpaddlex --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:0Document Image Preprocessor文档图像预处理paddlex --pipeline doc_preprocessor --input https://paddle-model-ecology.bj.bcebos.com/paddlex/demo_image/doc_test_rotated.jpg --use_doc_orientation_classify True --use_doc_unwarping True --save_path ./output --device gpu:0Table Recognition表格识别paddlex --pipeline table_recognition --input https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/table_recognition.jpg --save_path ./output --device gpu:0Table Recognition v2表格识别 v2paddlex --pipeline table_recognition_v2 --input https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/table_recognition.jpg --save_path ./output --device gpu:0Formula Recognition公式识别paddlex --pipeline formula_recognition --input https://paddle-model-ecology.bj.bcebos.com/paddlex/demo_image/general_formula_recognition.png --use_layout_detection True --use_doc_orientation_classify False --use_doc_unwarping False --layout_threshold 0.5 --layout_nms True --layout_unclip_ratio 1.0 --layout_merge_bboxes_mode large --save_path ./output --device gpu:0Seal Recognition印章识别paddlex --pipeline seal_recognition --input https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/seal_text_det.png --use_doc_orientation_classify False --use_doc_unwarping False --device gpu:0 --save_path ./outputLayout Parsing版面解析paddlex --pipeline layout_parsing --input https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/demo_paper.png --use_doc_orientation_classify False --use_doc_unwarping False --use_textline_orientation False --save_path ./output --device gpu:0PP-StructureV3paddlex --pipeline PP-StructureV3 --input https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/pp_structure_v3_demo.png --use_doc_orientation_classify False --use_doc_unwarping False --use_textline_orientation False --save_path ./output --device gpu:0使用提示公式识别 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参数默认值说明--device自动GPU 0 可用则用之否则 CPU支持cpu、gpu、npu、gpu:0多设备写法gpu:0,1可并行推理部分 Pipeline 不支持并行--engine空自动推理引擎paddle、paddle_static、paddle_dynamic、transformers、onnxruntime--enable_hpi视版本是否启用高性能推理HPI--use_tensorrtFalse是否使用 Paddle Inference 的 TensorRT 子图加速--precisionfp32TensorRT 精度可选fp32/fp16--enable_mkldnnTrueCPU 推理是否启用 MKL-DNN 加速--mkldnn_cache_capacity10MKL-DNN 缓存容量--cpu_threads10CPU 推理线程数--enable_cinnFalse是否使用 CINN 编译器这些参数最终会通过 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/)脚本依次执行了以下步骤create_pipeline()实例化 Pipeline 对象传入图片并调用 Pipeline 对象的predict()方法进行推理预测处理预测结果res.print()在终端打印结构化结果res.save_to_img(./output/)保存可视化结果图res.save_to_json(./output/)将完整结果导出为 JSON 文件。4.2 各 Pipeline 的 Python 参数名一览使用 Python 脚本调用其他 Pipeline 时只需调整create_pipeline()中的 Pipeline 参数名。下表汇总了 10 条流水线的参数名与详细说明位置Pipeline 名称对应参数详细说明OCROCR通用 OCR Pipeline Python 脚本使用说明文档图像预处理doc_preprocessor文档图像预处理 Pipeline Python 脚本使用说明表格识别table_recognition通用表格识别 Pipeline Python 脚本使用说明表格识别 v2table_recognition_v2通用表格识别 v2 Pipeline Python 脚本使用说明公式识别formula_recognition公式识别 Pipeline Python 脚本使用说明印章识别seal_recognition印章文本识别 Pipeline Python 脚本使用说明版面解析layout_parsing通用版面解析 Pipeline Python 脚本使用说明PP-StructureV3PP-StructureV3PP-StructureV3 Pipeline Python 脚本使用说明PP-ChatOCRv3-docPP-ChatOCRv3-doc文档场景信息抽取 v3 Pipeline Python 脚本使用说明PP-ChatOCRv4-docPP-ChatOCRv4-doc文档场景信息抽取 v4 Pipeline Python 脚本使用说明各 Pipeline 的 Python 脚本集成示例详见 PaddleX 官方对应 Pipeline 的“Python 脚本集成”章节文档中以外部链接给出。4.3 在 PaddleOCR 仓库内的等价写法如果你已经安装了本仓库的paddleocr包可以直接使用 PaddleOCR 自带的 Pipeline 类完成等价推理。例如通用 OCRfrom paddleocr import PaddleOCR ocr PaddleOCR( text_detection_model_namePP-OCRv5_server_det, text_recognition_model_namePP-OCRv5_server_rec, use_doc_orientation_classifyFalse, use_doc_unwarpingFalse, use_textline_orientationFalse, ) 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_detPP-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.tomlpaddleocr 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返回OCRpaddleocr/_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 推理内核。六、常见使用技巧与注意事项设备选择机器没有 GPU 时将--device gpu:0换成--device cpu即可运行无需修改其他参数NPUnpu:0与 XPUxpu:0设备同理。输入形态--input同时支持本地单图、本地目录批量与 URLPython 的predict()同样接受这些输入形态。关闭不必要的子模块方向正确、无扭曲的扫描件建议关闭use_doc_orientation_classify与use_doc_unwarping可以显著减少前处理推理耗时use_textline_orientation用于倾斜文本行矫正普通横排文本可关闭。结果落盘CLI 通过--save_path指定输出目录Python 通过res.save_to_img()/res.save_to_json()分别保存可视化结果与结构化 JSON便于后续接入业务系统。定制与扩展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。从低代码走向生产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使用既有一行命令的 CLIpaddlex --pipeline OCR --input img --device gpu:0也有create_pipelinepredict的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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/PaddleOCRPaddleX 是 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”是什么在开始使用之前需要先厘清两个概念PaddleXPaddlePaddle 官方推出的低代码开发工具承载了 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 paddlepaddle3.0.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ # GPU 版本CUDA 11.8需要 GPU 驱动 ≥ 450.80.02Linux或 ≥ 452.39Windows python -m pip install paddlepaddle-gpu3.0.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/ # GPU 版本CUDA 12.6需要 GPU 驱动 ≥ 550.54.14Linux 或 Windows python -m pip install paddlepaddle-gpu3.0.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/❗ 安装时无需关注物理机上的 CUDA 版本只需关注 GPU 驱动版本。PaddlePaddle 的 Wheel 版本说明详见其官方网站安装文档。2.3 安装 PaddleXpip install paddlex[ocr]其中[ocr]为 OCR 相关附加依赖组安装完成后即可获得paddlex命令行工具。其他安装方式如源码安装、docker 镜像等请参考 PaddleX 官方安装指南。三、CLI 命令行使用一条命令体验 Pipeline3.1 统一命令行格式PaddleX 提供了统一格式的命令行入口一条命令即可快速体验 Pipeline 效果paddlex --pipeline [Pipeline 名称] --input [输入图片] --device [运行设备]每条 Pipeline 都有其对应的专属参数可在各 Pipeline 文档中查看详细说明。所有 Pipeline 都必须指定以下三个必要参数参数说明pipelinePipeline 的名称或 Pipeline 的配置文件路径input输入文件的本地路径、目录或 URL如图片device使用的硬件设备及索引例如gpu:0表示使用第 0 块 GPU也可以选择 NPUnpu:0、XPUxpu:0、CPUcpu等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]], dtypeint16), ...], 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]], dtypeint16), ...], rec_boxes: array([[ 3, 10, 82, 33], ...], dtypeint16)}}结果字段速查dt_polys文本检测得到的四边形框顶点坐标检测阶段输出rec_polys/rec_boxes与识别结果对齐的文本框坐标rec_texts识别出的文本内容列表rec_scores每条文本的置信度分数text_det_params本次运行使用的检测后处理参数limit_side_len960限制最长边、thresh0.3二值化阈值、box_thresh0.6框过滤阈值、unclip_ratio2.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 名称命令OCRpaddlex --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:0Document Image Preprocessor文档图像预处理paddlex --pipeline doc_preprocessor --input https://paddle-model-ecology.bj.bcebos.com/paddlex/demo_image/doc_test_rotated.jpg --use_doc_orientation_classify True --use_doc_unwarping True --save_path ./output --device gpu:0Table Recognition表格识别paddlex --pipeline table_recognition --input https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/table_recognition.jpg --save_path ./output --device gpu:0Table Recognition v2表格识别 v2paddlex --pipeline table_recognition_v2 --input https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/table_recognition.jpg --save_path ./output --device gpu:0Formula Recognition公式识别paddlex --pipeline formula_recognition --input https://paddle-model-ecology.bj.bcebos.com/paddlex/demo_image/general_formula_recognition.png --use_layout_detection True --use_doc_orientation_classify False --use_doc_unwarping False --layout_threshold 0.5 --layout_nms True --layout_unclip_ratio 1.0 --layout_merge_bboxes_mode large --save_path ./output --device gpu:0Seal Recognition印章识别paddlex --pipeline seal_recognition --input https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/seal_text_det.png --use_doc_orientation_classify False --use_doc_unwarping False --device gpu:0 --save_path ./outputLayout Parsing版面解析paddlex --pipeline layout_parsing --input https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/demo_paper.png --use_doc_orientation_classify False --use_doc_unwarping False --use_textline_orientation False --save_path ./output --device gpu:0PP-StructureV3paddlex --pipeline PP-StructureV3 --input https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/pp_structure_v3_demo.png --use_doc_orientation_classify False --use_doc_unwarping False --use_textline_orientation False --save_path ./output --device gpu:0使用提示公式识别 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参数默认值说明--device自动GPU 0 可用则用之否则 CPU支持cpu、gpu、npu、gpu:0多设备写法gpu:0,1可并行推理部分 Pipeline 不支持并行--engine空自动推理引擎paddle、paddle_static、paddle_dynamic、transformers、onnxruntime--enable_hpi视版本是否启用高性能推理HPI--use_tensorrtFalse是否使用 Paddle Inference 的 TensorRT 子图加速--precisionfp32TensorRT 精度可选fp32/fp16--enable_mkldnnTrueCPU 推理是否启用 MKL-DNN 加速--mkldnn_cache_capacity10MKL-DNN 缓存容量--cpu_threads10CPU 推理线程数--enable_cinnFalse是否使用 CINN 编译器这些参数最终会通过 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/)脚本依次执行了以下步骤create_pipeline()实例化 Pipeline 对象传入图片并调用 Pipeline 对象的predict()方法进行推理预测处理预测结果res.print()在终端打印结构化结果res.save_to_img(./output/)保存可视化结果图res.save_to_json(./output/)将完整结果导出为 JSON 文件。4.2 各 Pipeline 的 Python 参数名一览使用 Python 脚本调用其他 Pipeline 时只需调整create_pipeline()中的 Pipeline 参数名。下表汇总了 10 条流水线的参数名与详细说明位置Pipeline 名称对应参数详细说明OCROCR通用 OCR Pipeline Python 脚本使用说明文档图像预处理doc_preprocessor文档图像预处理 Pipeline Python 脚本使用说明表格识别table_recognition通用表格识别 Pipeline Python 脚本使用说明表格识别 v2table_recognition_v2通用表格识别 v2 Pipeline Python 脚本使用说明公式识别formula_recognition公式识别 Pipeline Python 脚本使用说明印章识别seal_recognition印章文本识别 Pipeline Python 脚本使用说明版面解析layout_parsing通用版面解析 Pipeline Python 脚本使用说明PP-StructureV3PP-StructureV3PP-StructureV3 Pipeline Python 脚本使用说明PP-ChatOCRv3-docPP-ChatOCRv3-doc文档场景信息抽取 v3 Pipeline Python 脚本使用说明PP-ChatOCRv4-docPP-ChatOCRv4-doc文档场景信息抽取 v4 Pipeline Python 脚本使用说明各 Pipeline 的 Python 脚本集成示例详见 PaddleX 官方对应 Pipeline 的“Python 脚本集成”章节文档中以外部链接给出。4.3 在 PaddleOCR 仓库内的等价写法如果你已经安装了本仓库的paddleocr包可以直接使用 PaddleOCR 自带的 Pipeline 类完成等价推理。例如通用 OCRfrom paddleocr import PaddleOCR ocr PaddleOCR( text_detection_model_namePP-OCRv5_server_det, text_recognition_model_namePP-OCRv5_server_rec, use_doc_orientation_classifyFalse, use_doc_unwarpingFalse, use_textline_orientationFalse, ) 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_detPP-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.tomlpaddleocr 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返回OCRpaddleocr/_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 推理内核。六、常见使用技巧与注意事项设备选择机器没有 GPU 时将--device gpu:0换成--device cpu即可运行无需修改其他参数NPUnpu:0与 XPUxpu:0设备同理。输入形态--input同时支持本地单图、本地目录批量与 URLPython 的predict()同样接受这些输入形态。关闭不必要的子模块方向正确、无扭曲的扫描件建议关闭use_doc_orientation_classify与use_doc_unwarping可以显著减少前处理推理耗时use_textline_orientation用于倾斜文本行矫正普通横排文本可关闭。结果落盘CLI 通过--save_path指定输出目录Python 通过res.save_to_img()/res.save_to_json()分别保存可视化结果与结构化 JSON便于后续接入业务系统。定制与扩展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。从低代码走向生产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使用既有一行命令的 CLIpaddlex --pipeline OCR --input img --device gpu:0也有create_pipelinepredict的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考