PaddleOCR Integration#

MinerU uses a PyTorch-native port of PaddleOCR (PP-OCRv6) — no PaddlePaddle runtime required. The core class is PytorchPaddleOCR, which extends TextSystem from MinerU's own pytorchocr inference stack. Models are resolved at runtime from models_config.yml and downloaded on demand.

PDF Classification: txt vs ocr Path#

Before any OCR runs, classify(pdf_bytes) in pdf_classify.py determines whether a PDF is text-extractable ("txt") or must go through full OCR ("ocr"). It samples up to 10 pages 1 and applies a waterfall of heuristic checks; the first failing check short-circuits to "ocr":

Only a PDF that clears all checks returns "txt".

Model Configuration and Language Support#

models_config.yml maps language keys to their detector, recognizer, and character-dictionary files. All detector paths for most languages reuse ch_PP-OCRv6_small_det_infer.safetensors 12. Recognizer weights vary by language family:

• Chinese (default, ch) — ch_PP-OCRv6_small_rec_infer.safetensors 13
• Server-grade Chinese (ch_server) — ch_PP-OCRv6_medium_rec_infer.safetensors 14
• Seal stamps (seal / seal_lite) — dedicated detector (seal_PP-OCRv4_det_server_infer.pth) with a specialized poly box pipeline 15 16
• Other scripts (Korean, Arabic, Cyrillic, Devanagari, Thai, Greek, etc.) — language-specific PP-OCRv5 recognizers with PP-OCRv6 detector 17

The seal mode changes several detection hyperparameters: det_limit_side_len=736, det_db_thresh=0.2, det_box_type='poly', and drop_score=0 16.

Confidence Threshold and Result Filtering#

OcrConfidence in ocr_utils.py sets two hard-coded thresholds:

• min_confidence = 0.5 — results below this score are dropped in get_ocr_result_list()
• min_width = 3 — bounding boxes narrower than 3 pixels are also discarded 18

Inside PytorchPaddleOCR.__call__(), there is a secondary filter using self.drop_score (inherited from TextSystem): only detection-recognition pairs where score >= drop_score are returned 19. For the seal pipeline, drop_score is forced to 0 so all detections pass through to downstream scoring 20.

Formula regions are masked white before the OCR detector runs to prevent interference with adjacent text lines via mask_formula_regions_for_ocr_det().

OCR Fallback for Text-Based PDFs#

For PDFs classified as "txt", MinerU still falls back to OCR at the span level in two scenarios handled by fill_char_in_spans() and _prepare_post_ocr_spans():

1. Empty spans after character mapping
After native characters are spatially mapped into layout spans, any span whose content is too sparse relative to its dimensions is queued for OCR 21.

2. Private-Use Area (PUA) characters
Spans containing U+E000–U+F8FF characters — a sign of missing or garbled font encoding — trigger _should_fallback_to_post_ocr_for_private_use_text(). The fallback activates when:

• pua_count ≥ 2 and either max_pua_run ≥ 2 or pua_ratio ≥ 0.05 22

When a span is flagged, its original native text is preserved in _post_ocr_fallback_content 23. If the OCR image has contrast below 0.17, the fallback restores the native text rather than discarding the span entirely via _restore_post_ocr_fallback() 24.

A hard cap of 65535 native characters per page (MAX_NATIVE_TEXT_CHARS_PER_PAGE) also forces a full-page OCR fallback to avoid processing pathological documents 25.

Key Source Files#