使用不同推理引擎

引言¶

在 rapidocr>=3.0.0 版本之后，rapidocr 可以单独为文本检测、文本行方向分类和文本识别单独指定不同的推理引擎。

例如：文本检测使用 ONNX Runtime，文本识别使用 PaddlePaddle（params={"Rec.engine_type": EngineType.PADDLE}）。同时，不同版本的 OCR 也可以通过 Det.ocr_version 灵活指定。

rapidocr 支持 5 种推理引擎（ONNX Runtime / OpenVINO / PaddlePaddle / PyTorch / MNN (rapidocr>=3.6.0)），推荐首先使用 ONNX Runtime CPU 版。默认为 ONNX Runtime。

rapidocr 是通过指定不同参数来选择使用不同的推理引擎的。当然，使用不同推理引擎的前提是事先安装好对应的推理引擎库，并确保安装正确。

使用 ONNX Runtime¶

安装 ONNX Runtime。推荐用 CPU 版的 ONNX Runtime，GPU 版不推荐在 rapidocr 中使用，相关原因参见：ONNX Runtime GPU 推理。
1
pip install onnxruntime

ONNX Runtime 作为默认推理引擎，无需显式指定即可使用。

CPUNPUDirectML CoreML

from rapidocr import RapidOCR

engine = RapidOCR()

img_url = "https://www.modelscope.cn/models/RapidAI/RapidOCR/resolve/master/resources/test_files/ch_en_num.jpg"
result = engine(img_url)
print(result)

result.vis('vis_result.jpg')

Tip

仅在 rapidocr>=3.1.0 中支持。ONNX Runtime 官方相关文档：link

安装
1
pip install rapidocr onnxruntime-cann

使用

from rapidocr import RapidOCR

engine = RapidOCR(params={"EngineConfig.onnxruntime.use_cann": True})

img_url = "https://img1.baidu.com/it/u=3619974146,1266987475&fm=253&fmt=auto&app=138&f=JPEG?w=500&h=516"
result = engine(img_url)
print(result)

result.vis("vis_result.jpg")

Tip

DirectML 仅能 Windows 10 Build 18362 及以上使用。 ONNX Runtime 官方相关文档：link

安装

pip install rapidocr onnxruntime-directml

使用

from rapidocr import RapidOCR

engine = RapidOCR(params={"EngineConfig.onnxruntime.use_dml": True})

img_url = "https://img1.baidu.com/it/u=3619974146,1266987475&fm=253&fmt=auto&app=138&f=JPEG?w=500&h=516"
result = engine(img_url)
print(result)

result.vis("vis_result.jpg")

Warning

仅在 rapidocr>=3.7.0 中 实验性 支持。ONNX Runtime 官方相关文档：CoreML Execution Provider。详细 Benchmark 参见：基于 ONNX Runtime 来看 CoreML Provider 和 CPU Provider 在 RapidOCR 表现

安装

从 onnxruntime>=1.16 开始， ONNX Runtime 本身已支持 macOS Apple Silicon（M1 / M2 / M3）的 CoreML 后端，无需额外安装 coreml 包。
1
pip install onnxruntime

使用

from rapidocr import RapidOCR

engine = RapidOCR(params={"EngineConfig.onnxruntime.use_coreml": True})

img_url = "https://img1.baidu.com/it/u=3619974146,1266987475&fm=253&fmt=auto&app=138&f=JPEG?w=500&h=516"
result = engine(img_url)
print(result)

result.vis("vis_result.jpg")

查看输出日志。以下日志中打印出了 Using engine_name: onnxruntime，则证明使用的推理引擎是 ONNX Runtime。

[INFO] 2025-03-21 09:28:03,457 base.py:30: Using engine_name: onnxruntime
[INFO] 2025-03-21 09:28:03,553 utils.py:35: File already exists in /Users/joshuawang/projects/_self/RapidOCR/python/rapidocr/models/ch_PP-OCRv4_det_infer.onnx
[INFO] 2025-03-21 09:28:03,767 base.py:30: Using engine_name: onnxruntime
[INFO] 2025-03-21 09:28:03,768 utils.py:35: File already exists in /Users/joshuawang/projects/_self/RapidOCR/python/rapidocr/models/ch_ppocr_mobile_v2.0_cls_infer.onnx
[INFO] 2025-03-21 09:28:03,861 base.py:30: Using engine_name: onnxruntime
[INFO] 2025-03-21 09:28:03,862 utils.py:35: File already exists in /Users/joshuawang/projects/_self/RapidOCR/python/rapidocr/models/ch_PP-OCRv4_rec_infer.onnx

使用 OpenVINO¶

安装 OpenVINO。
1
pip install openvino

指定 OpenVINO 作为推理引擎。

from rapidocr import RapidOCR, EngineType

engine = RapidOCR(
    params={
        "Det.engine_type": EngineType.OPENVINO,
        "Cls.engine_type": EngineType.OPENVINO,
        "Rec.engine_type": EngineType.OPENVINO,
    }
)

img_url = "https://www.modelscope.cn/models/RapidAI/RapidOCR/resolve/master/resources/test_files/ch_en_num.jpg"
result = engine(img_url)
print(result)

result.vis('vis_result.jpg')

查看输出日志。以下日志中打印出了 Using engine_name: openvino，则证明使用的推理引擎是 OpenVINO。

[INFO] 2025-03-21 09:28:03,457 base.py:30: Using engine_name: openvino
[INFO] 2025-03-21 09:28:03,553 utils.py:35: File already exists in /Users/joshuawang/projects/_self/RapidOCR/python/rapidocr/models/ch_PP-OCRv4_det_infer.onnx
[INFO] 2025-03-21 09:28:03,767 base.py:30: Using engine_name: openvino
[INFO] 2025-03-21 09:28:03,768 utils.py:35: File already exists in /Users/joshuawang/projects/_self/RapidOCR/python/rapidocr/models/ch_ppocr_mobile_v2.0_cls_infer.onnx
[INFO] 2025-03-21 09:28:03,861 base.py:30: Using engine_name: openvino
[INFO] 2025-03-21 09:28:03,862 utils.py:35: File already exists in /Users/joshuawang/projects/_self/RapidOCR/python/rapidocr/models/ch_PP-OCRv4_rec_infer.onnx

使用 MNN¶

Tip

rapidocr>=3.6.0 支持。

安装 MNN
1
pip install MNN

指定 MNN 作为推理引擎。

CPUGPU

from rapidocr import EngineType, RapidOCR

engine = RapidOCR(
    params={
        "Det.engine_type": EngineType.MNN,
        "Cls.engine_type": EngineType.MNN,
        "Rec.engine_type": EngineType.MNN,
    }
)

img_url = "https://www.modelscope.cn/models/RapidAI/RapidOCR/resolve/master/resources/test_files/ch_en_num.jpg"
result = engine(img_url)
print(result)

result.vis('vis_result.jpg')

敬请期待！

查看输出日志。以下日志中打印出了 Using engine_name: mnn，则证明使用的推理引擎是 MNN。

[INFO] 2025-03-21 09:28:03,457 base.py:30: Using engine_name: mnn
[INFO] 2025-03-21 09:28:03,553 utils.py:35: File already exists in /Users/joshuawang/projects/_self/RapidOCR/python/rapidocr/models/ch_PP-OCRv4_det_infer.mnn
[INFO] 2025-03-21 09:28:03,767 base.py:30: Using engine_name: mnn
[INFO] 2025-03-21 09:28:03,768 utils.py:35: File already exists in /Users/joshuawang/projects/_self/RapidOCR/python/rapidocr/models/ch_ppocr_mobile_v2.0_cls_infer.mnn
[INFO] 2025-03-21 09:28:03,861 base.py:30: Using engine_name: mnn
[INFO] 2025-03-21 09:28:03,862 utils.py:35: File already exists in /Users/joshuawang/projects/_self/RapidOCR/python/rapidocr/models/ch_PP-OCRv4_rec_infer.mnn

使用 PaddlePaddle¶

安装 PaddlePaddle。

参见 PaddlePaddle 官方安装文档 → 快速安装

大家可以根据实际情况，选择安装需要的版本。

指定 PaddlePaddle 作为推理引擎。

CPUGPUNPU

from rapidocr import EngineType, RapidOCR

engine = RapidOCR(
    params={
        "Det.engine_type": EngineType.PADDLE,
        "Cls.engine_type": EngineType.PADDLE,
        "Rec.engine_type": EngineType.PADDLE,
    }
)

img_url = "https://www.modelscope.cn/models/RapidAI/RapidOCR/resolve/master/resources/test_files/ch_en_num.jpg"
result = engine(img_url)
print(result)

result.vis('vis_result.jpg')

from rapidocr import EngineType, RapidOCR

engine = RapidOCR(
    params={
    "Det.engine_type": EngineType.PADDLE,
    "EngineConfig.paddle.use_cuda": True,  # 使用PaddlePaddle GPU版推理
    "EngineConfig.paddle.cuda_ep_cfg.device_id": 0,  # 指定GPU id
    }
)

img_url = "https://www.modelscope.cn/models/RapidAI/RapidOCR/resolve/master/resources/test_files/ch_en_num.jpg"
result = engine(img_url)
print(result)

result.vis('vis_result.jpg')

Tip

仅在 rapidocr>=3.3.0 中支持。对应版本的 PaddlePaddle 安装文档：link

from rapidocr import EngineType, RapidOCR

engine = RapidOCR(
    params={
    "Det.engine_type": EngineType.PADDLE,
    "EngineConfig.paddle.use_npu": True,  # 使用PaddlePaddle NPU版推理
    "EngineConfig.paddle.npu_ep_cfg.device_id": 0,  # 指定NPU id
    }
)

img_url = "https://www.modelscope.cn/models/RapidAI/RapidOCR/resolve/master/resources/test_files/ch_en_num.jpg"
result = engine(img_url)
print(result)

result.vis('vis_result.jpg')

查看输出日志。以下日志中打印出了 Using engine_name: paddle，则证明使用的推理引擎是 PaddlePaddle。

[INFO] 2025-03-22 15:20:45,528 utils.py:35: File already exists in /Users/SWHL/projects/RapidOCR/python/rapidocr/models/ch_PP-OCRv4_det_infer/inference.pdmodel
[INFO] 2025-03-22 15:20:45,529 utils.py:35: File already exists in /Users/SWHL/projects/RapidOCR/python/rapidocr/models/ch_PP-OCRv4_det_infer/inference.pdiparams
[INFO] 2025-03-22 15:20:45,746 base.py:30: Using engine_name: paddle
[INFO] 2025-03-22 15:20:45,746 utils.py:35: File already exists in /Users/SWHL/projects/RapidOCR/python/rapidocr/models/ch_ppocr_mobile_v2_cls_infer/inference.pdmodel
[INFO] 2025-03-22 15:20:45,746 utils.py:35: File already exists in /Users/SWHL/projects/RapidOCR/python/rapidocr/models/ch_ppocr_mobile_v2_cls_infer/inference.pdiparams
[INFO] 2025-03-22 15:20:45,903 base.py:30: Using engine_name: paddle
[INFO] 2025-03-22 15:20:45,904 utils.py:35: File already exists in /Users/SWHL/projects/RapidOCR/python/rapidocr/models/ch_PP-OCRv4_rec_infer/inference.pdmodel
[INFO] 2025-03-22 15:20:45,904 utils.py:35: File already exists in /Users/SWHL/projects/RapidOCR/python/rapidocr/models/ch_PP-OCRv4_rec_infer/inference.pdiparams

使用 PyTorch¶

安装 PyTorch。

参见 PyTorch 官方安装文档 → Install PyTorch。

大家可以根据实际情况，选择安装需要的版本。

指定 PyTorch 作为推理引擎。

CPUGPUNPUMPS

from rapidocr import RapidOCR

engine = RapidOCR(
    params={
        "Det.engine_type": EngineType.TORCH,
        "Cls.engine_type": EngineType.TORCH,
        "Rec.engine_type": EngineType.TORCH,
    }
)

img_url = "https://www.modelscope.cn/models/RapidAI/RapidOCR/resolve/master/resources/test_files/ch_en_num.jpg"
result = engine(img_url)
print(result)

result.vis('vis_result.jpg')

from rapidocr import EngineType, RapidOCR

engine = RapidOCR(
    params={
        "Det.engine_type": EngineType.TORCH,
        "Cls.engine_type": EngineType.TORCH,
        "Rec.engine_type": EngineType.TORCH,
        "EngineConfig.torch.use_cuda": True,  # 使用 torch GPU 版推理
        "EngineConfig.torch.cuda_ep_cfg.device_id": 0,  # 指定GPU id
    }
)

img_url = "https://www.modelscope.cn/models/RapidAI/RapidOCR/resolve/master/resources/test_files/ch_en_num.jpg"
result = engine(img_url)
print(result)

result.vis('vis_result.jpg')

Tip

仅在 rapidocr>=3.4.2 中支持。torch_npu 官方相关文档：link

安装 torch_npu，参见：docs。

使用

from rapidocr import EngineType, RapidOCR

engine = RapidOCR(
    params={
        "Det.engine_type": EngineType.TORCH,
        "Cls.engine_type": EngineType.TORCH,
        "Rec.engine_type": EngineType.TORCH,
        "EngineConfig.torch.use_npu": True,  # 使用torch NPU版推理
        "EngineConfig.torch.npu_ep_cfg.device_id": 0,  # 指定NPU id
    }
)

img_url = "https://www.modelscope.cn/models/RapidAI/RapidOCR/resolve/master/resources/test_files/ch_en_num.jpg"
result = engine(img_url)
print(result)

result.vis('vis_result.jpg')

Tip

仅在 rapidocr>=3.7.0 中支持。详细 Benchmark 参见：RapidOCR 支持 PyTorch MPS 作为计算后端

安装 torch，参见：docs。小伙伴们可以在安装之后，运行下面脚本来确定机器是否可以用 Apple GPU：

import torch

print(f"PyTorch 版本: {torch.**version**}")
print(f"MPS 可用性: {torch.backends.mps.is_available()}")

if torch.backends.mps.is_available():
    device = torch.device("mps")
    print(f"✅ 已成功使用 Apple GPU (MPS): {device}")
else:
    print("❌ 请检查你的 PyTorch 安装是否正确，可能需要重新安装支持 MPS 的版本。")

输出以下类似结果，表明机器可以使用 Apple GPU：

PyTorch 版本: 2.6.0
MPS 可用性: True
✅ 已成功使用 Apple GPU (MPS): mps

使用

from rapidocr import EngineType, RapidOCR

engine = RapidOCR(
    params={
        "Det.engine_type": EngineType.TORCH,
        "Cls.engine_type": EngineType.TORCH,
        "Rec.engine_type": EngineType.TORCH,
        "EngineConfig.torch.use_mps": True,  # 使用torch MPS版推理
    }
)

img_url = "https://www.modelscope.cn/models/RapidAI/RapidOCR/resolve/master/resources/test_files/ch_en_num.jpg"
result = engine(img_url)
print(result)

result.vis('vis_result.jpg')

查看输出日志。以下日志中打印出了 Using engine_name: torch，则证明使用的推理引擎是 PyTorch。

[INFO] 2025-03-22 15:39:13,241 base.py:30: Using engine_name: torch
[INFO] 2025-03-22 15:39:13,956 utils.py:35: File already exists in /Users/SWHL/projects/RapidOCR/python/rapidocr/models/ch_PP-OCRv4_det_infer.pth
[INFO] 2025-03-22 15:39:14,136 base.py:30: Using engine_name: torch
[INFO] 2025-03-22 15:39:14,136 utils.py:35: File already exists in /Users/SWHL/projects/RapidOCR/python/rapidocr/models/ch_ptocr_mobile_v2.0_cls_infer.pth
[INFO] 2025-03-22 15:39:14,168 base.py:30: Using engine_name: torch
[INFO] 2025-03-22 15:39:14,168 utils.py:35: File already exists in /Users/SWHL/projects/RapidOCR/python/rapidocr/models/ch_PP-OCRv4_rec_infer.pth

使用 TensorRT¶

Tip

rapidocr>=3.7.0 支持。相关博客：RapidOCR 支持 TensorRT 推理引擎。

安装 TensorRT 运行环境。

我在这里仅给出参考配置环境：
- Docker 镜像：@LocNgoXuan23 在 Discord 中给出的镜像：7.0-gc-triton-devel
- 设备配置：8 CPU / 256 GB
- NVIDIA 环境：(详细参见：link )
  - cuda: 12.2
  - tensorrt: 8.6.1
  - cuda-python: 12.2.0
大家可以根据实际情况，选择安装需要的版本。

指定 TensorRT 作为推理引擎。

运行以下代码，程序会自动下载对应的 ONNX 模型，并转换为 .engine 格式。该转换仅在首次运行时执行；因此，首次运行速度较慢，后续再次运行时将显著加快。

详细模型的支持情况，参见博客：RapidOCR 支持 TensorRT 推理引擎

from rapidocr import EngineType, RapidOCR

engine = RapidOCR(
    params={
        "Det.engine_type": EngineType.TENSORRT,
        "Cls.engine_type": EngineType.TENSORRT,
        "Rec.engine_type": EngineType.TENSORRT,
        "EngineConfig.tensorrt.use_fp16": False,
        "EngineConfig.tensorrt.device_id": 0,  # 指定GPU id
    }
)

img_url = "https://www.modelscope.cn/models/RapidAI/RapidOCR/resolve/master/resources/test_files/ch_en_num.jpg"
result = engine(img_url)
print(result)

result.vis('vis_result.jpg')

查看输出日志。以下日志中打印出了 Using engine_name: tensorrt，则证明使用的推理引擎是 PyTorch。

[INFO] 2025-03-22 15:39:13,241 base.py:30: Using engine_name: tensorrt
[INFO] 2025-03-22 15:39:13,956 utils.py:35: File already exists in /Users/SWHL/projects/RapidOCR/python/rapidocr/models/ch_PP-OCRv4_det_mobile_sm80_fp32.engine
[INFO] 2025-03-22 15:39:14,136 base.py:30: Using engine_name: tensorrt
[INFO] 2025-03-22 15:39:14,136 utils.py:35: File already exists in /Users/SWHL/projects/RapidOCR/python/rapidocr/models/ch_ptocr_mobile_v2.0_cls_sm80_fp32.engine
[INFO] 2025-03-22 15:39:14,168 base.py:30: Using engine_name: tensorrt
[INFO] 2025-03-22 15:39:14,168 utils.py:35: File already exists in /Users/SWHL/projects/RapidOCR/python/rapidocr/models/ch_PP-OCRv4_rec_mobile_sm80_fp32.engine