RapidOCR Model Management#

RapidOCR models in Docling are managed by RapidOcrModel in docling/models/stages/ocr/rapid_ocr_model.py. At runtime the model fetches artifacts from ModelScope and caches them locally; for offline or air-gapped environments they can be pre-downloaded and pointed to via artifacts_path.

Model Source: Hardcoded ModelScope URLs#

All model artifacts are downloaded from a single, pinned ModelScope release 1:

https://www.modelscope.cn/models/RapidAI/RapidOCR/resolve/<release>/<path>

The release tag is hardcoded as _RAPIDOCR_MODELSCOPE_RELEASE (currently v3.9.0). Per-file paths are assembled in _build_model_detail(); individual URLs are never user-configurable at the options level.

Three language model sets are defined — chinese, english, and latin — each for two backends (onnxruntime, torch) 2. Each set contains five artifact types: detection model, classification model, recognition model, recognition keys file, and a font file. The onnxruntime backend uses PP-OCRv6 assets for all three language sets; the torch backend (except Chinese) still uses PP-OCRv4 assets 3.

The download_models downloader 4 iterates both backends and chinese/english languages by default. The latin language set is not downloaded by default; it must be downloaded separately or pre-loaded via artifacts_path. This is a known gap — the docling-serve rocm72 image omitting the Latin model is what caused a regression in v1.25.0 (see Open WebUI Integration — v1.25.0 regression).

Pre-Downloading Models (artifacts_path)#

The artifacts_path option on PipelineOptions (inherited by PdfPipelineOptions) points the runtime to a directory containing pre-downloaded artifacts 5:

pipeline_options = PdfPipelineOptions(artifacts_path="/path/to/models")
converter = DocumentConverter(
    format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)}
)

When artifacts_path is set, RapidOcrModel.__init__ resolves each artifact as 6:

<artifacts_path>/RapidOcr/<relative-path-from-model-set>

Any per-model path override in RapidOcrOptions (e.g. det_model_path, rec_model_path) takes precedence over artifacts_path resolution.

CLI pre-download: Use docling-tools models download to populate the artifacts directory 7:

docling-tools models download -o /path/to/models rapidocr

This calls RapidOcrModel.download_models() for each backend/language combination. The method skips files that already exist unless --force is passed. The docling-serve container image pre-downloads rapidocr (and other models) during build time using this same CLI command 8.

For the latin language set (needed for French, German, Spanish, and other Latin-script languages), download must be triggered explicitly — the download_models() utility function does not include it in its default loop 4. The model file required is torch/PP-OCRv4/rec/latin_PP-OCRv3_rec_mobile.pth plus paddle/PP-OCRv4/rec/latin_PP-OCRv3_rec_mobile/latin_dict.txt 9.

Language Resolution#

Language codes are mapped to one of three internal model sets via _resolve_rapidocr_language(). The mapping covers ISO 639-1, ISO 639-2, and plain English names 10. If the requested language has no mapping, a warning is emitted and the chinese set is used as the default — which silently drops inter-word spaces in Latin-script text 11. When multiple requested languages span different model sets, only the first set is used 12.

When artifacts_path is not set, language type params are passed through the RapidOCR internal LangDet/LangRec typings API (if available) via _rapidocr_lang_type_params() so the correct models are selected by RapidOCR itself.

SSL Certificate Handling#

Model downloads go through download_url_with_progress(), which calls requests.get() with default SSL verification. There is no custom SSL configuration in the download path. Certificate failures are surfaced as unhandled requests exceptions.

The recommended fixes documented in the FAQ 13:

• Upgrade certifi: pip install --upgrade certifi
• Use system certificates with pip-system-certs
• Set SSL_CERT_FILE and REQUESTS_CA_BUNDLE to python -m certifi output

These workarounds apply equally to RapidOCR downloads from ModelScope and to Hugging Face downloads for other models.

Key Files#