RapidOcrOptions documentation example doesn't work with custom models from monkt/paddleocr-onnx

[putassu]

Bug

RapidOcrOptions documentation example doesn't work with custom models from monkt/paddleocr-onnx

Steps to reproduce

The documentation example for RapidOcrOptions in [[docs/reference/models/ocr.md](https://docling-project.github.io/docling/examples/rapidocr_with_custom_models/)] shows how to use custom RapidOCR models, but the example is incomplete and doesn't work as written.

from docling.datamodel.pipeline_options import RapidOcrOptions

ocr_options = RapidOcrOptions(
    det_model_path=det_path,
    rec_model_path=rec_path,
    rec_keys_path=dict_path,
    cls_model_path=cls_path,
)

With models from monkt/paddleocr-onnx repository, the code fails with:

RuntimeError: No class found with the name 'rapidocr'
ConfigKeyError: Missing key dict_url

Root Cause:

The RapidOcrModel class in Docling requires the rapidocr library (not rapidocr_onnxruntime), which has a specific configuration format. The models from monkt/paddleocr-onnx are incompatible with the current RapidOcrModel implementation.

Expected Behavior:

Either:

The documentation should clarify that RapidOcrOptions only works with models from RapidAI/RapidOCR repository
Or support for rapidocr_onnxruntime should be added to use custom models like monkt/paddleocr-onnx
Current Workaround:

Docling version

2.64.0

Python version

3.12.5

[dosubot]

Hi @putassu! I'm Dosu and I’m helping the docling team.

The current RapidOcrOptions implementation in Docling only supports models from the RapidAI/RapidOCR repository and is tightly coupled to the rapidocr library, not rapidocr_onnxruntime. This means models from monkt/paddleocr-onnx are not compatible out of the box, which leads to errors like "No class found with the name 'rapidocr'" and "ConfigKeyError: Missing key dict_url" when you try to use them. The documentation example works only with RapidAI/RapidOCR models and should clarify this limitation citation citation.

If you need to use monkt/paddleocr-onnx models, you would have to manually patch the rapidocr config (such as default_models.yaml) to include the required dict_url or point to your local dictionary file, but this is not officially supported and may break with future updates citation.

Supporting rapidocr_onnxruntime or other custom models would require code changes to the RapidOcrModel class to handle different backends and configuration formats. For now, only RapidAI/RapidOCR models are tested and supported, and the only known working GPU setup is with the torch backend (backend="torch") citation.

If your use case requires a different OCR engine, consider using one of the other engines supported by Docling, such as EasyOCR or Tesseract.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[putassu]

@dosu Thank you for clarification. Could you provide guidance on how to properly configure the rapidocr config file to support custom models from monkt/paddleocr-onnx? Specifically, what fields need to be added to default_models.yaml and how should dict_url be handled for custom dictionary files?

[dosubot]

To configure RapidOCR to use custom models from monkt/paddleocr-onnx, you need to patch RapidOCR’s config file (default_models.yaml) so it includes all required fields for your model: det_model_path, cls_model_path, rec_model_path, and dict_url (which is the dictionary file for recognition). The dict_url field should point to your custom dictionary file, for example /path/to/latin_rec_keys.txt. This is necessary because RapidOCR expects a dict_url entry for each model, even if you provide the dictionary path via Docling’s rec_keys_path option see discussion.

Here’s a minimal example of what a custom entry in default_models.yaml might look like:

onnxruntime:
  custom_paddleocr_onnx_model:
    det_model_path: /path/to/your/det_model.onnx
    cls_model_path: /path/to/your/cls_model.onnx
    rec_model_path: /path/to/your/rec_model.onnx
    dict_url: /path/to/latin_rec_keys.txt

Make sure the backend (onnxruntime, torch, etc.) matches what you set in RapidOcrOptions. If you use a local dictionary file, set dict_url to its full path. If you still get a dict_url error, double-check that your config file is being loaded by RapidOCR and that all paths are correct see discussion.

As a workaround, you can also pass the dictionary path directly using Docling’s rapidocr_params option:

rapidocr_params = {"Rec.rec_keys_path": "/path/to/latin_rec_keys.txt"}

This approach is not officially documented and may break with future RapidOCR or Docling updates see issue.

Keep in mind: Docling does not parse default_models.yaml directly, but its internal config structure mirrors the same fields. You must keep your config in sync with RapidOCR’s expectations for your backend and model see code.

Let me know if you need help with a specific config or dictionary file!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}