PaddleOCR 与 PaddleX 协同开发指南依赖关系、版本对应与 Pipeline 配置文件的导出与加载【免费下载链接】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 文档系统讲解 PaddleOCR 与 PaddleX 的协同工作机制二者在推理部署阶段如何分工协作、版本如何一一对应、Pipeline 命名如何保持一致以及如何通过导出、编辑和加载 PaddleX Pipeline 配置文件实现深度定制。读完本文你将掌握export_paddlex_config_to_yaml、CLI 与 Python API 双入口的--paddlex_config/paddlex_config配置注入方式并能在生产环境中自主完成从默认配置到高级配置的完整部署链路。1. 为什么 PaddleOCR 需要 PaddleXPaddleX 是基于 PaddlePaddle 框架构建的低代码开发工具内置大量开箱即用的预训练模型支持从模型训练到推理的完整流水线开发并兼容国内外多种主流硬件。PaddleOCR 在推理部署阶段完全复用了 PaddleX 的能力二者因此形成分工明确、底层共用的关系推理底座复用PaddleOCR 依赖 PaddleX 提供模型推理、前后处理、多模型组合编排等底层能力高性能推理PaddleOCR 的高性能推理能力经由 PaddleX 的 Paddle2ONNX 插件与高性能推理插件HPI实现服务化部署PaddleOCR 的服务化部署方案基于 PaddleX 的实现展开。在源码层面这一复用体现在 PaddleOCR 每个 Pipeline 类都继承自PaddleXPipelineWrapper基类见 paddleocr/_pipelines/base.py基类在初始化时调用_get_merged_paddlex_config()合并配置再通过create_pipeline(config...)直接创建 PaddleX 底层流水线对象最终暴露为paddlex_pipeline属性。例如 paddleocr/_pipelines/ocr.py 中通用 OCR 流水线的_paddlex_pipeline_name返回OCR即对应的 PaddleX Pipeline 注册名。1.1 依赖体积可控可选依赖安装机制值得注意的是尽管底层使用 PaddleX但得益于 PaddleX 的可选依赖安装特性安装paddleocrPython 发行包并不会带入 PaddleX 的全部依赖仅安装 OCR 相关任务所需的依赖用户不必担心依赖体积过度膨胀。这一事实在仓库的打包配置中得到印证pyproject.toml 中基础依赖为paddlex[ocr-core]3.7.0,3.8.0而文档解析、IE信息抽取、翻译等额外能力则通过doc-parser、ie、trans等 optional extras 按需声明。官方在 2025 年 5 月测试x86-64 Linux Python 3.10 环境下所需依赖总体积仅从 717 MB 增至 738 MB约增加 21 MB。2. PaddleOCR、PaddleX 与 PaddlePaddle 的版本对应关系为保证推理部署阶段的兼容性PaddleOCR 与 PaddleX 及 PaddlePaddle 框架存在严格的版本对应关系如下表所示PaddleOCR 版本PaddleX 版本PaddlePaddle 版本3.0.03.0.0 3.0.03.0.13.0.1 3.0.03.0.23.0.2 3.0.03.0.3 3.0.3 3.0.03.1.x 3.1.0, 3.2.0 3.0.03.2.x 3.2.0, 3.3.0 3.0.03.3.x 3.3.0, 3.4.0 3.0.03.4.x 3.4.0, 3.5.0 3.0.03.5.x 3.5.0, 3.6.0 3.0.03.6.x 3.6.0, 3.7.0 3.0.03.7.x 3.7.0, 3.8.0 3.0.0可以看到从3.1.x开始PaddleX 采用区间约束如 3.1.0, 3.2.0允许小版本范围内的浮动兼容而 PaddlePaddle 侧统一要求 3.0.0。当前仓库的 pyproject.toml 正是按此约定声明paddlex[ocr-core]3.7.0,3.8.0。在实际部署时建议先确认 PaddleOCR 版本再按上表锁定 PaddleX 版本区间避免因版本错配导致 Pipeline 创建失败。3. PaddleOCR Pipeline 与 PaddleX 注册名的对应关系PaddleOCR 与 PaddleX 在 Pipeline 命名约定上保持一致。安装 PaddleOCR 时 PaddleX 会作为依赖一并安装在基础配置下快速体验时用户通常无需理解 PaddleX 的具体概念但在高级配置、服务化部署等场景下了解 PaddleX 会大有裨益。下表列出了 PaddleOCR 各 Pipeline 与 PaddleX Pipeline 注册名的一一对应关系PaddleOCR PipelinePaddleX Pipeline 注册名通用 OCROCRPP-StructureV3PP-StructureV3PP-ChatOCRv4PP-ChatOCRv4-doc通用表格识别 V2table_recognition_v2公式识别formula_recognition印章文本识别seal_recognition文档图像预处理doc_preprocessor文档理解doc_understandingPP-DocTranslationPP-DocTranslationPaddleOCR-VLPaddleOCR-VLPaddleOCR-VL-1.5PaddleOCR-VL-1.5PaddleOCR-VL-1.6PaddleOCR-VL-1.6这一注册名在源码中作为每个 Pipeline 子类的_paddlex_pipeline_name属性实现见 paddleocr/_pipelines/ocr.py基类PaddleXPipelineWrapper会用它来定位默认配置。当使用 PaddleX CLI 获取配置或通过 PaddleX 文档查询对应 Pipeline 教程时应使用注册名列。4. 使用 PaddleX Pipeline 配置文件深度定制在推理部署阶段PaddleOCR 支持导出与加载 PaddleX Pipeline 配置文件。通过编辑这些配置文件用户可以深度配置推理部署相关参数——其参数面不仅覆盖 PaddleOCR CLI 与 Python API 已暴露的参数还支持更高级的底层配置。4.1 导出 Pipeline 配置文件方式一调用 PaddleOCR Pipeline 对象的export_paddlex_config_to_yaml方法将当前 Pipeline 配置导出为 YAML 文件from paddleocr import PaddleOCR pipeline PaddleOCR() pipeline.export_paddlex_config_to_yaml(ocr_config.yaml)以上代码将在工作目录生成名为ocr_config.yaml的 Pipeline 配置文件。该方法的底层实现位于 paddleocr/_pipelines/base.py它将_merged_paddlex_config即合并了用户注入配置与 PaddleOCR 公共参数覆盖后的最终配置经_to_builtin递归转换为原生 Python 对象再以yaml.safe_dump写出。因此导出的 YAML 完整反映了当前 Pipeline 的默认参数与模型配置是排查问题与定制部署的权威参照。方式二通过 PaddleX CLI 直接获取对应 Pipeline 的配置文件# 指定 Pipeline 注册名 paddlex --get_pipeline_config OCROCR需替换为目标 Pipeline 的注册名如PP-StructureV3、table_recognition_v2等见第 3 节对照表。4.2 编辑 Pipeline 配置文件导出的 PaddleX Pipeline 配置文件不仅包含 PaddleOCR CLI 与 Python API 支持的参数还允许更高级的配置。典型可调项包括子模型的选择与权重路径、设备分配CPU/GPU 及多卡、批处理大小、推理后端插件Paddle2ONNX、高性能推理插件开关、前后处理阈值等。各参数的具体含义与调整方式请结合对应 Pipeline 的 PaddleX 使用教程如 PaddleX Pipeline 使用总览中的流水线开发指南按需查阅本文不再赘述。4.3 在 CLI 中加载 Pipeline 配置文件通过--paddlex_config参数指定 PaddleX Pipeline 配置文件路径PaddleOCR 将读取其内容作为该 Pipeline 的默认配置该配置优先于各初始化参数的默认值。示例paddleocr ocr --paddlex_config ocr_config.yaml ...该参数由PipelineCLISubcommandExecutor.add_subparser注册见 paddleocr/_pipelines/base.py类型为字符串帮助信息为Path to PaddleX pipeline configuration file.。因此所有继承该执行器的 PaddleOCR Pipeline 子命令如ocr、table_recognition_v2等均支持此参数。4.4 在 Python API 中加载 Pipeline 配置文件初始化 Pipeline 对象时可通过paddlex_config参数传入 PaddleX Pipeline 配置文件路径或配置字典PaddleOCR 将以此作为默认配置同样优先于各初始化参数的默认值。示例from paddleocr import PaddleOCR pipeline PaddleOCR(paddlex_configocr_config.yaml)从源码看paddlex_config支持三种取值形态见 paddleocr/_pipelines/base.pyNone加载与_paddlex_pipeline_name对应的 PaddleX 内置默认配置str视为配置文件路径通过load_pipeline_config加载dict直接作为配置字典使用。加载后的配置会与_get_paddlex_config_overrides()返回的公共参数覆盖项如设备、日志等经_merge_dicts递归合并最终作为create_pipeline的config入参创建底层 PaddleX Pipeline见 paddleocr/_pipelines/base.py。需要说明的是该合并是用户注入配置 PaddleOCR 公共参数覆盖的叠加若用户注入配置与公共参数冲突公共参数覆盖项优先。5. 常见问题与注意事项依赖安装paddleocr默认只安装paddlex[ocr-core]相关依赖若需使用文档解析、信息抽取、翻译等扩展能力请按需安装对应的 extras见 pyproject.toml避免运行时出现依赖缺失。若创建 Pipeline 时因依赖缺失失败PaddleOCR 会抛出带有安装指引提示的RuntimeError见 paddleocr/_pipelines/base.py。高性能推理插件PaddleOCR 的高性能推理能力依赖 PaddleX 的 Paddle2ONNX 插件与高性能推理插件相关插件可通过paddlex --install命令安装见 paddleocr/_cli.py。版本匹配务必按第 2 节版本对应表锁定 PaddleX 版本区间尤其是从3.1.x起采用的区间约束 3.1.0, 3.2.0等防止小版本行为差异导致配置不兼容。配置优先级--paddlex_config/paddlex_config指定的配置优先于各初始化参数的默认值但低于 PaddleOCR 公共参数的覆盖项在排查配置为何未生效时可先导出合并后的配置export_paddlex_config_to_yaml核对最终生效值。6. 总结PaddleOCR 与 PaddleX 的关系可以概括为任务聚焦 底座复用PaddleOCR 专注 OCR 相关任务检测、识别、结构化、文档理解等PaddleX 提供多模型组合推理、高性能插件与服务化部署等底层基础设施。通过export_paddlex_config_to_yaml导出配置、--paddlex_config/paddlex_config注入配置开发者可以在不改变 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），仅供参考