RapidOCR with PP-OCRv5 ONNX fails after upgrading Docling 2.45.0 → 2.51.0 (dict_url missing)

[ROMBombo]

I’m using RapidOCR with PP-OCRv5 (ONNX) inside a Docling pipeline (PDF processing).

Here’s how I initialize the options:

rapidocr_options = RapidOcrOptions(
    lang=["en", "id", "ch", "chinese_cht"],
    force_full_page_ocr=True,
    det_model_path=f"{config.rapidocr_model_storage_directory}/det.onnx",
    rec_model_path=f"{config.rapidocr_model_storage_directory}/rec.onnx",
    cls_model_path=f"{config.rapidocr_model_storage_directory}/cls.onnx",
    rec_keys_path=f"{config.rapidocr_model_storage_directory}/ppocrv5_dict.txt",
    bitmap_area_threshold=config.bitmap_area_threshold,
    text_score=config.confidence_threshold
)

This worked fine on Docling 2.45.0, but after upgrading to Docling 2.51.0 I encountered the following error:

Traceback

...
omegaconf.errors.ConfigKeyError: Missing key dict_url
    full_key: onnxruntime.PP-OCRv4.rec.ch_PP-OCRv4_rec_infer.onnx.dict_url
    object_type=dict
...
RuntimeError: No class found with the name 'rapidocr', known classes are:
        'easyocr' => <class 'docling.models.easyocr_model.EasyOcrModel'>
        'ocrmac' => <class 'docling.models.ocr_mac_model.OcrMacModel'>
        'rapidocr' => <class 'docling.models.rapid_ocr_model.RapidOcrModel'>
        'tesserocr' => <class 'docling.models.tesseract_ocr_model.TesseractOcrModel'>
        'tesseract' => <class 'docling.models.tesseract_ocr_cli_model.TesseractOcrCliModel'>

So what’s the correct way to use a local file (e.g., ppocrv5_dict.txt) without modifying the library source code?

Thanks in advance 🙏

[dosubot[bot]]

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

Docling 2.51.0 upgraded to RapidOCR 3.x and now passes your dictionary file path to RapidOCR using the rec_keys_path option in RapidOcrOptions—this is still the correct way to use a local file like ppocrv5_dict.txt without modifying Docling source code see code.

The 'dict_url' error isn't triggered by Docling itself; it's likely coming from RapidOCR's own config or its default_models.yaml file, which may expect a dict_url entry for certain models in newer RapidOCR versions see PR. If you provide all model paths and the dictionary file via RapidOcrOptions, Docling will pass them to RapidOCR as expected.

To resolve the error:

• Double-check that your model and dictionary file paths are correct and match the backend you selected.
• Make sure you are using compatible versions of RapidOCR and its dependencies (Docling now requires rapidocr>=3.3,<4.0.0 and onnxruntime).
• If the error persists, check if RapidOCR expects a config file (like default_models.yaml) with a dict_url entry for your chosen model. You may need to add this key or ensure your local setup matches RapidOCR's expectations.

You do not need to modify Docling source code—just ensure your local files and RapidOCR version are set up correctly.

To reply, just mention @dosu.

---

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

[ROMBombo]

Hi @dosu, thanks for the clarification.

I’ve tested with RapidOCR 3.4.0 and onnxruntime 1.22.1, but I think the issue might be related to how Docling 2.51.0 instantiates RapidOCR.

In Docling 2.51.0, the code docling/models/rapid_ocr_model.py looks like this:

class RapidOcrModel(BaseOcrModel):
    def __init__(
        self,
        enabled: bool,
        artifacts_path: Optional[Path],
        options: RapidOcrOptions,
        accelerator_options: AcceleratorOptions,
    ):
        ...
        if self.enabled:
            try:
                from rapidocr import EngineType, RapidOCR  # type: ignore
            except ImportError:
                raise ImportError(
                    "RapidOCR is not installed. Please install it via `pip install rapidocr onnxruntime` to use this OCR engine. "
                    "Alternatively, Docling has support for other OCR engines. See the documentation."
                )
            ...
            self.reader = RapidOCR(
                params={
                    # Global settings (these are still correct)
                    "Global.text_score": self.options.text_score,
                    # "Global.verbose": self.options.print_verbose,
                    # Detection model settings
                    "Det.model_path": self.options.det_model_path,
                    "Det.use_cuda": use_cuda,
                    "Det.use_dml": use_dml,
                    "Det.intra_op_num_threads": intra_op_num_threads,
                    # Classification model settings
                    "Cls.model_path": self.options.cls_model_path,
                    "Cls.use_cuda": use_cuda,
                    "Cls.use_dml": use_dml,
                    "Cls.intra_op_num_threads": intra_op_num_threads,
                    # Recognition model settings
                    "Rec.model_path": self.options.rec_model_path,
                    "Rec.font_path": self.options.rec_font_path,
                    "Rec.keys_path": self.options.rec_keys_path,
                    "Rec.use_cuda": use_cuda,
                    "Rec.use_dml": use_dml,
                    "Rec.intra_op_num_threads": intra_op_num_threads,
                    "Det.engine_type": backend_enum,
                    "Cls.engine_type": backend_enum,
                    "Rec.engine_type": backend_enum,
                }
            )

Meanwhile, in Docling 2.45.0, the code used to be:

class RapidOcrModel(BaseOcrModel):
    def __init__(
        self,
        enabled: bool,
        artifacts_path: Optional[Path],
        options: RapidOcrOptions,
        accelerator_options: AcceleratorOptions,
    ):
        ...
        if self.enabled:
            try:
                from rapidocr_onnxruntime import RapidOCR  # type: ignore
            except ImportError:
                raise ImportError(
                    "RapidOCR is not installed. Please install it via `pip install rapidocr_onnxruntime` to use this OCR engine. "
                    "Alternatively, Docling has support for other OCR engines. See the documentation."
                )
            ...
            self.reader = RapidOCR(
                text_score=self.options.text_score,
                cls_use_cuda=use_cuda,
                rec_use_cuda=use_cuda,
                det_use_cuda=use_cuda,
                det_use_dml=use_dml,
                cls_use_dml=use_dml,
                rec_use_dml=use_dml,
                intra_op_num_threads=intra_op_num_threads,
                print_verbose=self.options.print_verbose,
                det_model_path=self.options.det_model_path,
                cls_model_path=self.options.cls_model_path,
                rec_model_path=self.options.rec_model_path,
                rec_keys_path=self.options.rec_keys_path,
            )

The key difference is:

• 2.51.0 → instantiation relies on the new rapidocr library (with params={...}), which seems to always pull in the default config from RapidOCR (and triggers the dict_url issue).

• 2.45.0 → instantiation relied on rapidocr_onnxruntime and directly passed all options as arguments, which worked fine with local dictionary files.

That might be why the dict_url error appears even though I already provided rec_keys_path.
Is there a recommended way for me to work around this issue?

[dosubot[bot]]

You're correct—the switch to RapidOCR 3.x in Docling 2.51.0 means RapidOCR now expects its own config (like default_models.yaml) and may require a dict_url entry for certain models, even if you provide a local dictionary file via rec_keys_path. Docling itself only passes your local file path to RapidOCR and doesn't interact with or override RapidOCR's internal config system see code.

If you hit the dict_url error, it's because RapidOCR is looking for a config entry it can't find see PR. There's no Docling-side workaround—your best bet is to ensure RapidOCR's config (especially default_models.yaml) includes the necessary dict_url for your model, or patch RapidOCR's config to point to your local dictionary file. Docling will pass your local file if you set rec_keys_path, but any missing config keys must be handled in RapidOCR's own files.

In short: Docling can't bypass RapidOCR's config checks, so you may need to provide or edit default_models.yaml to satisfy RapidOCR's requirements when using custom/local models and dictionaries.

To reply, just mention @dosu.

---

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