PaddleOCR 推理引擎与配置完全指南engine/engine_config使用详解【免费下载链接】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/PaddleOCRPaddleOCR 3.5 引入了一套统一的推理引擎配置机制通过engine参数选择底层推理引擎通过engine_config传入引擎专属的配置项该机制同时适用于单个模型与完整 Pipeline。本文以官方文档 inference_engine.en.md 为骨架结合仓库源码与测试用例系统讲解推理引擎的概念、支持清单、安装方式、全部配置字段、优先级与兼容性规则以及 CLI 与 Python API 的完整实战示例帮助你在 CPU / GPU / 多引擎场景下精准掌控 PaddleOCR 的推理行为。1. 什么是推理引擎在 PaddleOCR 中推理引擎Inference Engine指的是实际加载并执行模型的底层运行时。它决定了模型由哪一套运行时来驱动——你可以把它理解为“模型推理时真正使用的发动机”。引入推理引擎机制后用户通常只需要关心两件事选哪种推理引擎engine参数如何配置这个推理引擎engine_config参数。在 paddleocr/_common_args.py 中可以看到当前支持的引擎清单被硬编码为一个白名单SUPPORTED_INFERENCE_ENGINE_LIST [ paddle, paddle_static, paddle_dynamic, transformers, onnxruntime, ]任何不在该列表中的engine值都会在参数解析阶段直接被拒绝并抛出ValueError。1.1 默认行为不显式指定engine时如果没有显式指定enginePaddleOCR 保持与早期版本一致的默认行为除高性能推理、生成式 AI 客户端请求等少数场景外绝大多数情况下使用 PaddlePaddle 框架完成推理。从 paddleocr/_common_args.py 的prepare_common_init_args可以看出当engine为None或paddle时会默认构造一份paddle_static的配置并透传给底层也就是说“不指定”与“指定paddle”最终都会走到 PaddlePaddle 框架。一旦显式指定了engine初始化就会优先遵循所选引擎而不是走默认路径。2. PaddleOCR 当前支持的推理引擎| 引擎类别 |engine取值 | 说明 | | - | - | - | | PaddlePaddle 框架 |paddle、paddle_static、paddle_dynamic| 基于 PaddlePaddle 框架运行 | | Transformers |transformers| 基于 Hugging Face Transformers 运行 | | ONNX Runtime |onnxruntime| 基于 ONNX Runtime 运行 |各取值的具体含义如下paddlePaddlePaddle 框架的统一入口。它根据模型类型及模型目录中的文件自动选择paddle_static或paddle_dynamic两者同时可用时优先选择paddle_static。paddle_staticPaddlePaddle 静态图推理适合对推理性能有更高要求、或需要更细粒度性能调优的场景。paddle_dynamicPaddlePaddle 动态图推理相比静态图更灵活、更易调试。transformersHugging Face Transformers 推理便于与 Hugging Face 生态集成。onnxruntimeONNX Runtime 推理用于加载并执行 ONNX 格式的模型。3. 按推理引擎安装依赖注意不同推理引擎的依赖可能存在冲突建议每个环境只安装一种推理引擎。3.1 PaddlePaddle 框架使用 PaddlePaddle 框架推理时需要先安装 PaddlePaddle。安装步骤见 PaddlePaddle 框架安装PaddlePaddle 版本要求见 PaddleOCR 与 PaddleX 的关系说明。3.2 Transformers使用 Transformers 作为推理引擎时需要安装 Hugging Face Transformers5.10.0python -m pip install transformers5.10.0很多情况下还需要安装其底层的推理框架如 PyTorch 等具体请参考 Transformers 官方安装文档。3.3 ONNX Runtime使用 ONNX Runtime 作为推理引擎时安装 ONNX Runtime 包即可。以下命令适用于CUDA 12.x 环境下的 NVIDIA GPUpython -m pip install onnxruntime-gpu其他设备或环境的安装方式请参考 ONNX Runtime 官方安装文档。CPU 场景可选用onnxruntimeCPU 版安装。4.engine与engine_config的配置及取值4.1engine参数engine用于指定推理引擎支持的值如下| 取值 | 含义 | 说明 | | - | - | - | |None| 未显式指定引擎 | 自动决定推理引擎保持 PaddleOCR 3.4 的行为多数情况下使用 PaddlePaddle 框架推理 | |paddle| PaddlePaddle 框架统一入口 | 自动选择paddle_static或paddle_dynamic| |paddle_static| 静态图推理 | 使用 Paddle 静态图推理 | |paddle_dynamic| 动态图推理 | 使用 Paddle 动态图推理 | |transformers| Transformers 推理 | 使用 Hugging Face Transformers 推理 | |onnxruntime| ONNX Runtime 推理 | 使用 ONNX Runtime 推理 |在 CLI 层面--engine参数同样受到SUPPORTED_INFERENCE_ENGINE_LIST白名单约束见 paddleocr/_common_args.py传错值会直接报错。同时要注意CLI 的引擎专属配置需要在 PaddleX YAML 配置文件中设置--engine只负责选引擎。4.2engine_config参数engine_config用于配置推理引擎建议与engine配套使用。下面按引擎分类列出常用字段。paddle_static常用字段run_mode执行模式如paddle、trt_fp32、trt_fp16、mkldnndevice_type/device_id设备类型与设备索引cpu_threadsCPU 推理线程数delete_pass需要手动关闭的图优化 pass 列表enable_new_ir是否启用新 IRenable_cinn是否启用 CINN 编译器trt_cfg_setting底层 TensorRT 配置trt_use_dynamic_shapes是否启用 TensorRT 动态形状trt_collect_shape_range_info是否收集形状范围信息trt_discard_cached_shape_range_info是否丢弃已有形状范围信息并重新收集trt_dynamic_shapes动态形状配置trt_dynamic_shape_input_data收集动态形状时用于填充输入张量的数据trt_shape_range_info_path形状范围信息文件路径trt_allow_rebuild_at_runtime是否允许运行时重建 TensorRT 引擎mkldnn_cache_capacityoneDNNMKLDNN缓存容量。paddle_dynamic常用字段device_type/device_id动态图执行时使用的设备类型与设备索引。transformers常用字段dtype模型权重 / 推理使用的数据类型如float16device_type/device_id推理设备类型与设备索引trust_remote_code是否信任并执行模型仓库中的自定义代码attn_implementation注意力实现方式如flash_attention_2generation_config生成参数如max_new_tokens、temperaturemodel_kwargs传给模型加载 API 的额外参数processor_kwargs传给 processor / image processor 加载 API 的额外参数tokenizer_kwargs为保持兼容而保留的字段会与processor_kwargs合并。onnxruntime常用字段device_type/device_id推理设备类型与设备索引providers执行提供方列表如CUDAExecutionProvider、CPUExecutionProviderprovider_options执行提供方专属配置graph_optimization_level图优化级别intra_op_num_threads算子内线程数inter_op_num_threads算子间线程数execution_mode执行模式如sequential、parallellog_severity_level日志级别enable_mem_pattern是否启用内存模式memory patternenable_cpu_mem_arena是否启用 CPU 内存 arenasession_optionsONNX Runtime 会话选项。4.2.1 扁平式Flat与分桶式Bucketedengine_config在同一层级engine_config可以是两种形态之一扁平式Flat一个字典其键仅为最终解析出的引擎所需的键。例如只使用静态图时顶层键就是run_mode、cpu_threads这类字段。分桶式Bucketed顶层键只能是已注册的引擎名如paddle_static、paddle_dynamic、transformers、onnxruntime每个键对应一个嵌套字典。严禁在同一层级混用桶键与扁平键——例如{paddle_static: {...}, run_mode: paddle}是非法的。当引擎被解析确定后只使用对应的那份配置扁平式配置整体校验分桶式配置只取该引擎对应的条目。仓库中的默认路径也印证了这一点在 paddleocr/_common_args.py 中当用户没有显式传入engine_config、而engine为None或paddle时会自动构造{paddle_static: built}这种分桶结构把基于use_tensorrt、precision、enable_mkldnn、cpu_threads、enable_cinn等兼容参数构建出的静态图配置装进paddle_static桶里。4.3 优先级与覆盖规则对于 Pipeline通过CLI 参数或 Python API 初始化参数传入的engine与engine_config优先于Pipeline 配置文件中同名字段。在 Pipeline 配置文件中顶层的engine/engine_config作为全局设置子模块或子 Pipeline中的engine/engine_config可以覆盖上层设置。关于优先级、覆盖及 Pipeline 配置行为的更完整规则可参考 PaddleX 的 Pipeline Python API 使用文档。4.4 兼容性规则显式设置engine后enable_hpi高性能推理不再生效。显式提供engine_config后所选引擎对应的兼容性参数被忽略。例如在paddle/paddle_static场景下use_tensorrt、precision、enable_mkldnn、mkldnn_cache_capacity、cpu_threads、enable_cinn等兼容参数不再生效。这一点在源码中有直接体现prepare_common_init_args在用户显式传入engine_config时会原样透传用户配置init_kwargs[engine_config] user_engine_config而不再把兼容参数折算成静态图配置见 paddleocr/_common_args.py。也就是说一旦你决定用engine_config精细控制就该把所有关键选项写进engine_config而不是依赖旧的兼容参数。5. 使用示例5.1 单个模型CLI用--engine选择引擎paddleocr text_detection -i general_ocr_001.png --engine transformers paddleocr text_detection -i general_ocr_001.png --engine onnxruntime5.2 单个模型Python显式指定transformersfrom paddleocr import TextDetection model TextDetection( model_namePP-OCRv5_server_det, enginetransformers, ) result model.predict(general_ocr_001.png)5.3 单个模型Python显式指定onnxruntimefrom paddleocr import TextDetection model TextDetection( model_namePP-OCRv5_server_det, engineonnxruntime, ) result model.predict(general_ocr_001.png)5.4 单个模型Python指定paddle_static并搭配engine_configfrom paddleocr import TextDetection model TextDetection( model_namePP-OCRv5_server_det, enginepaddle_static, engine_config{ device_type: cpu, cpu_threads: 4, run_mode: mkldnn, }, ) result model.predict(general_ocr_001.png)在这个例子中run_mode: mkldnn表示启用 oneDNNMKLDNN加速cpu_threads: 4指定 4 个 CPU 推理线程device_type: cpu明确在 CPU 上执行。5.5 PipelineCLI用--engine选择引擎paddleocr ocr -i general_ocr_001.png --engine paddle_static5.6 PipelinePython API为 Pipeline 中某个具体模块配置推理引擎如果想为 Pipeline 内的某个具体模块指定engine和engine_config可以先导出配置文件 → 修改对应模块配置 → 再加载该配置。导出、编辑、加载配置文件的完整流程可参考 使用 PaddleX Pipeline 配置文件。首先导出 Pipeline 配置文件from paddleocr import PaddleOCR pipeline PaddleOCR() pipeline.export_paddlex_config_to_yaml(ocr_config.yaml)然后在ocr_config.yaml中为TextDetection模块单独设置engine与engine_configpipeline_name: OCR SubModules: TextDetection: engine: paddle_static engine_config: device_type: cpu cpu_threads: 4 run_mode: mkldnn最后用更新后的配置文件进行推理from paddleocr import PaddleOCR pipeline PaddleOCR(paddlex_configocr_config.yaml) result pipeline.predict(general_ocr_001.png)这种“按子模块分桶”的写法正是 4.2.1 节所述分桶式配置的典型应用在 Pipeline 配置中每个子模块拥有独立的engine/engine_config互不干扰便于在同一个 Pipeline 内为不同环节检测 / 识别 / 方向分类等选择最合适的引擎。6. 源码级验证参数如何流转到底层为了更透彻地理解这套机制可以顺着源码把调用链走一遍参数解析与校验无论是 CLI 还是 Python API公共参数都会经过 parse_common_args 处理。它完成三件事检查未知参数名、校验engine是否在白名单内、校验precision是否在SUPPORTED_PRECISION_LIST内并把use_tensorrt/precision映射为 PaddleX 内部的use_pptrt/pptrt_precision。构建引擎配置_build_paddle_static_engine_config 根据设备类型gpu/cpu/ 其他与兼容参数自动推导静态图配置GPU 上开启 TensorRT 时映射为trt_fp32或trt_fp16CPU 上开启 MKLDNN 时设置mkldnn_cache_capacity否则回退到paddle模式并统一设置cpu_threads与enable_cinn。初始化透传prepare_common_init_args 把解析结果整理成底层 PaddleX predictor 的初始化参数。用户显式传入engine_config时原样透传未传入时按engine取值自动构造分桶或扁平配置。模型侧接入在 paddleocr/_models/base.py 中prepare_common_init_args的结果会与额外的 predictor 初始化参数合并最终以engine...、engine_config...的形式传给 PaddleX 的 predictor。也就是说PaddleOCR 的模型 / Pipeline 是 PaddleX 推理能力的一层封装engine机制的实际解析与执行由 PaddleX 完成。测试验证仓库的集成测试如 tests/pipelines/test_ocr.py通过PaddleOCR.predict校验检测框dt_polys与识别文本rec_texts的输出结构间接验证了默认引擎路径下模型可正常推理。如果你在自定义引擎下遇到问题可以参照这些测试的断言结构来编写自己的最小复现用例。7. 选型建议与注意事项追求开箱即用不指定engine保持默认的 PaddlePaddle 框架路径即可行为与 3.4 一致。追求极致推理性能优先考虑paddle_static并结合run_modetrt_fp32/trt_fp16、trt_use_dynamic_shapes、enable_cinn、cpu_threads等字段做细粒度调优。已有 Hugging Face 生态 / 需要生成式能力选transformers利用dtype、attn_implementation、generation_config控制精度、注意力实现与生成策略。需要 ONNX 模型互通选onnxruntime用providers指定执行提供方如CUDAExecutionProvider/CPUExecutionProvider。务必记住兼容性规则显式设置engine后enable_hpi失效显式提供engine_config后旧兼容参数use_tensorrt、precision、enable_mkldnn、cpu_threads等不再生效请把关键配置写入engine_config。环境隔离不同引擎依赖可能冲突建议一个环境只安装一种推理引擎。至此你已经掌握了 PaddleOCR 3.5 推理引擎机制的完整脉络从概念、引擎清单、安装到engine/engine_config的全部字段、优先级与兼容性规则再到 CLI / Python API / Pipeline 配置文件的实战用法以及源码级的参数流转链路。接下来就可以根据你的硬件与业务场景为 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），仅供参考
PaddleOCR 推理引擎与配置完全指南：`engine` / `engine_config` 使用详解
PaddleOCR 推理引擎与配置完全指南engine/engine_config使用详解【免费下载链接】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/PaddleOCRPaddleOCR 3.5 引入了一套统一的推理引擎配置机制通过engine参数选择底层推理引擎通过engine_config传入引擎专属的配置项该机制同时适用于单个模型与完整 Pipeline。本文以官方文档 inference_engine.en.md 为骨架结合仓库源码与测试用例系统讲解推理引擎的概念、支持清单、安装方式、全部配置字段、优先级与兼容性规则以及 CLI 与 Python API 的完整实战示例帮助你在 CPU / GPU / 多引擎场景下精准掌控 PaddleOCR 的推理行为。1. 什么是推理引擎在 PaddleOCR 中推理引擎Inference Engine指的是实际加载并执行模型的底层运行时。它决定了模型由哪一套运行时来驱动——你可以把它理解为“模型推理时真正使用的发动机”。引入推理引擎机制后用户通常只需要关心两件事选哪种推理引擎engine参数如何配置这个推理引擎engine_config参数。在 paddleocr/_common_args.py 中可以看到当前支持的引擎清单被硬编码为一个白名单SUPPORTED_INFERENCE_ENGINE_LIST [ paddle, paddle_static, paddle_dynamic, transformers, onnxruntime, ]任何不在该列表中的engine值都会在参数解析阶段直接被拒绝并抛出ValueError。1.1 默认行为不显式指定engine时如果没有显式指定enginePaddleOCR 保持与早期版本一致的默认行为除高性能推理、生成式 AI 客户端请求等少数场景外绝大多数情况下使用 PaddlePaddle 框架完成推理。从 paddleocr/_common_args.py 的prepare_common_init_args可以看出当engine为None或paddle时会默认构造一份paddle_static的配置并透传给底层也就是说“不指定”与“指定paddle”最终都会走到 PaddlePaddle 框架。一旦显式指定了engine初始化就会优先遵循所选引擎而不是走默认路径。2. PaddleOCR 当前支持的推理引擎| 引擎类别 |engine取值 | 说明 | | - | - | - | | PaddlePaddle 框架 |paddle、paddle_static、paddle_dynamic| 基于 PaddlePaddle 框架运行 | | Transformers |transformers| 基于 Hugging Face Transformers 运行 | | ONNX Runtime |onnxruntime| 基于 ONNX Runtime 运行 |各取值的具体含义如下paddlePaddlePaddle 框架的统一入口。它根据模型类型及模型目录中的文件自动选择paddle_static或paddle_dynamic两者同时可用时优先选择paddle_static。paddle_staticPaddlePaddle 静态图推理适合对推理性能有更高要求、或需要更细粒度性能调优的场景。paddle_dynamicPaddlePaddle 动态图推理相比静态图更灵活、更易调试。transformersHugging Face Transformers 推理便于与 Hugging Face 生态集成。onnxruntimeONNX Runtime 推理用于加载并执行 ONNX 格式的模型。3. 按推理引擎安装依赖注意不同推理引擎的依赖可能存在冲突建议每个环境只安装一种推理引擎。3.1 PaddlePaddle 框架使用 PaddlePaddle 框架推理时需要先安装 PaddlePaddle。安装步骤见 PaddlePaddle 框架安装PaddlePaddle 版本要求见 PaddleOCR 与 PaddleX 的关系说明。3.2 Transformers使用 Transformers 作为推理引擎时需要安装 Hugging Face Transformers5.10.0python -m pip install transformers5.10.0很多情况下还需要安装其底层的推理框架如 PyTorch 等具体请参考 Transformers 官方安装文档。3.3 ONNX Runtime使用 ONNX Runtime 作为推理引擎时安装 ONNX Runtime 包即可。以下命令适用于CUDA 12.x 环境下的 NVIDIA GPUpython -m pip install onnxruntime-gpu其他设备或环境的安装方式请参考 ONNX Runtime 官方安装文档。CPU 场景可选用onnxruntimeCPU 版安装。4.engine与engine_config的配置及取值4.1engine参数engine用于指定推理引擎支持的值如下| 取值 | 含义 | 说明 | | - | - | - | |None| 未显式指定引擎 | 自动决定推理引擎保持 PaddleOCR 3.4 的行为多数情况下使用 PaddlePaddle 框架推理 | |paddle| PaddlePaddle 框架统一入口 | 自动选择paddle_static或paddle_dynamic| |paddle_static| 静态图推理 | 使用 Paddle 静态图推理 | |paddle_dynamic| 动态图推理 | 使用 Paddle 动态图推理 | |transformers| Transformers 推理 | 使用 Hugging Face Transformers 推理 | |onnxruntime| ONNX Runtime 推理 | 使用 ONNX Runtime 推理 |在 CLI 层面--engine参数同样受到SUPPORTED_INFERENCE_ENGINE_LIST白名单约束见 paddleocr/_common_args.py传错值会直接报错。同时要注意CLI 的引擎专属配置需要在 PaddleX YAML 配置文件中设置--engine只负责选引擎。4.2engine_config参数engine_config用于配置推理引擎建议与engine配套使用。下面按引擎分类列出常用字段。paddle_static常用字段run_mode执行模式如paddle、trt_fp32、trt_fp16、mkldnndevice_type/device_id设备类型与设备索引cpu_threadsCPU 推理线程数delete_pass需要手动关闭的图优化 pass 列表enable_new_ir是否启用新 IRenable_cinn是否启用 CINN 编译器trt_cfg_setting底层 TensorRT 配置trt_use_dynamic_shapes是否启用 TensorRT 动态形状trt_collect_shape_range_info是否收集形状范围信息trt_discard_cached_shape_range_info是否丢弃已有形状范围信息并重新收集trt_dynamic_shapes动态形状配置trt_dynamic_shape_input_data收集动态形状时用于填充输入张量的数据trt_shape_range_info_path形状范围信息文件路径trt_allow_rebuild_at_runtime是否允许运行时重建 TensorRT 引擎mkldnn_cache_capacityoneDNNMKLDNN缓存容量。paddle_dynamic常用字段device_type/device_id动态图执行时使用的设备类型与设备索引。transformers常用字段dtype模型权重 / 推理使用的数据类型如float16device_type/device_id推理设备类型与设备索引trust_remote_code是否信任并执行模型仓库中的自定义代码attn_implementation注意力实现方式如flash_attention_2generation_config生成参数如max_new_tokens、temperaturemodel_kwargs传给模型加载 API 的额外参数processor_kwargs传给 processor / image processor 加载 API 的额外参数tokenizer_kwargs为保持兼容而保留的字段会与processor_kwargs合并。onnxruntime常用字段device_type/device_id推理设备类型与设备索引providers执行提供方列表如CUDAExecutionProvider、CPUExecutionProviderprovider_options执行提供方专属配置graph_optimization_level图优化级别intra_op_num_threads算子内线程数inter_op_num_threads算子间线程数execution_mode执行模式如sequential、parallellog_severity_level日志级别enable_mem_pattern是否启用内存模式memory patternenable_cpu_mem_arena是否启用 CPU 内存 arenasession_optionsONNX Runtime 会话选项。4.2.1 扁平式Flat与分桶式Bucketedengine_config在同一层级engine_config可以是两种形态之一扁平式Flat一个字典其键仅为最终解析出的引擎所需的键。例如只使用静态图时顶层键就是run_mode、cpu_threads这类字段。分桶式Bucketed顶层键只能是已注册的引擎名如paddle_static、paddle_dynamic、transformers、onnxruntime每个键对应一个嵌套字典。严禁在同一层级混用桶键与扁平键——例如{paddle_static: {...}, run_mode: paddle}是非法的。当引擎被解析确定后只使用对应的那份配置扁平式配置整体校验分桶式配置只取该引擎对应的条目。仓库中的默认路径也印证了这一点在 paddleocr/_common_args.py 中当用户没有显式传入engine_config、而engine为None或paddle时会自动构造{paddle_static: built}这种分桶结构把基于use_tensorrt、precision、enable_mkldnn、cpu_threads、enable_cinn等兼容参数构建出的静态图配置装进paddle_static桶里。4.3 优先级与覆盖规则对于 Pipeline通过CLI 参数或 Python API 初始化参数传入的engine与engine_config优先于Pipeline 配置文件中同名字段。在 Pipeline 配置文件中顶层的engine/engine_config作为全局设置子模块或子 Pipeline中的engine/engine_config可以覆盖上层设置。关于优先级、覆盖及 Pipeline 配置行为的更完整规则可参考 PaddleX 的 Pipeline Python API 使用文档。4.4 兼容性规则显式设置engine后enable_hpi高性能推理不再生效。显式提供engine_config后所选引擎对应的兼容性参数被忽略。例如在paddle/paddle_static场景下use_tensorrt、precision、enable_mkldnn、mkldnn_cache_capacity、cpu_threads、enable_cinn等兼容参数不再生效。这一点在源码中有直接体现prepare_common_init_args在用户显式传入engine_config时会原样透传用户配置init_kwargs[engine_config] user_engine_config而不再把兼容参数折算成静态图配置见 paddleocr/_common_args.py。也就是说一旦你决定用engine_config精细控制就该把所有关键选项写进engine_config而不是依赖旧的兼容参数。5. 使用示例5.1 单个模型CLI用--engine选择引擎paddleocr text_detection -i general_ocr_001.png --engine transformers paddleocr text_detection -i general_ocr_001.png --engine onnxruntime5.2 单个模型Python显式指定transformersfrom paddleocr import TextDetection model TextDetection( model_namePP-OCRv5_server_det, enginetransformers, ) result model.predict(general_ocr_001.png)5.3 单个模型Python显式指定onnxruntimefrom paddleocr import TextDetection model TextDetection( model_namePP-OCRv5_server_det, engineonnxruntime, ) result model.predict(general_ocr_001.png)5.4 单个模型Python指定paddle_static并搭配engine_configfrom paddleocr import TextDetection model TextDetection( model_namePP-OCRv5_server_det, enginepaddle_static, engine_config{ device_type: cpu, cpu_threads: 4, run_mode: mkldnn, }, ) result model.predict(general_ocr_001.png)在这个例子中run_mode: mkldnn表示启用 oneDNNMKLDNN加速cpu_threads: 4指定 4 个 CPU 推理线程device_type: cpu明确在 CPU 上执行。5.5 PipelineCLI用--engine选择引擎paddleocr ocr -i general_ocr_001.png --engine paddle_static5.6 PipelinePython API为 Pipeline 中某个具体模块配置推理引擎如果想为 Pipeline 内的某个具体模块指定engine和engine_config可以先导出配置文件 → 修改对应模块配置 → 再加载该配置。导出、编辑、加载配置文件的完整流程可参考 使用 PaddleX Pipeline 配置文件。首先导出 Pipeline 配置文件from paddleocr import PaddleOCR pipeline PaddleOCR() pipeline.export_paddlex_config_to_yaml(ocr_config.yaml)然后在ocr_config.yaml中为TextDetection模块单独设置engine与engine_configpipeline_name: OCR SubModules: TextDetection: engine: paddle_static engine_config: device_type: cpu cpu_threads: 4 run_mode: mkldnn最后用更新后的配置文件进行推理from paddleocr import PaddleOCR pipeline PaddleOCR(paddlex_configocr_config.yaml) result pipeline.predict(general_ocr_001.png)这种“按子模块分桶”的写法正是 4.2.1 节所述分桶式配置的典型应用在 Pipeline 配置中每个子模块拥有独立的engine/engine_config互不干扰便于在同一个 Pipeline 内为不同环节检测 / 识别 / 方向分类等选择最合适的引擎。6. 源码级验证参数如何流转到底层为了更透彻地理解这套机制可以顺着源码把调用链走一遍参数解析与校验无论是 CLI 还是 Python API公共参数都会经过 parse_common_args 处理。它完成三件事检查未知参数名、校验engine是否在白名单内、校验precision是否在SUPPORTED_PRECISION_LIST内并把use_tensorrt/precision映射为 PaddleX 内部的use_pptrt/pptrt_precision。构建引擎配置_build_paddle_static_engine_config 根据设备类型gpu/cpu/ 其他与兼容参数自动推导静态图配置GPU 上开启 TensorRT 时映射为trt_fp32或trt_fp16CPU 上开启 MKLDNN 时设置mkldnn_cache_capacity否则回退到paddle模式并统一设置cpu_threads与enable_cinn。初始化透传prepare_common_init_args 把解析结果整理成底层 PaddleX predictor 的初始化参数。用户显式传入engine_config时原样透传未传入时按engine取值自动构造分桶或扁平配置。模型侧接入在 paddleocr/_models/base.py 中prepare_common_init_args的结果会与额外的 predictor 初始化参数合并最终以engine...、engine_config...的形式传给 PaddleX 的 predictor。也就是说PaddleOCR 的模型 / Pipeline 是 PaddleX 推理能力的一层封装engine机制的实际解析与执行由 PaddleX 完成。测试验证仓库的集成测试如 tests/pipelines/test_ocr.py通过PaddleOCR.predict校验检测框dt_polys与识别文本rec_texts的输出结构间接验证了默认引擎路径下模型可正常推理。如果你在自定义引擎下遇到问题可以参照这些测试的断言结构来编写自己的最小复现用例。7. 选型建议与注意事项追求开箱即用不指定engine保持默认的 PaddlePaddle 框架路径即可行为与 3.4 一致。追求极致推理性能优先考虑paddle_static并结合run_modetrt_fp32/trt_fp16、trt_use_dynamic_shapes、enable_cinn、cpu_threads等字段做细粒度调优。已有 Hugging Face 生态 / 需要生成式能力选transformers利用dtype、attn_implementation、generation_config控制精度、注意力实现与生成策略。需要 ONNX 模型互通选onnxruntime用providers指定执行提供方如CUDAExecutionProvider/CPUExecutionProvider。务必记住兼容性规则显式设置engine后enable_hpi失效显式提供engine_config后旧兼容参数use_tensorrt、precision、enable_mkldnn、cpu_threads等不再生效请把关键配置写入engine_config。环境隔离不同引擎依赖可能冲突建议一个环境只安装一种推理引擎。至此你已经掌握了 PaddleOCR 3.5 推理引擎机制的完整脉络从概念、引擎清单、安装到engine/engine_config的全部字段、优先级与兼容性规则再到 CLI / Python API / Pipeline 配置文件的实战用法以及源码级的参数流转链路。接下来就可以根据你的硬件与业务场景为 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），仅供参考
