Motores OCR de Docling

Los PDF digitales (texto) a menudo no necesitan OCR: prueba primero --no-ocr para máxima velocidad y añade un motor solo para páginas escaneadas.

OCR está activado por defecto (--ocr). Tres flags controlan dónde corre y qué motor lo ejecuta. Equivalente Python: PdfPipelineOptions().do_ocr = True más uno de RapidOcrOptions / EasyOcrOptions / TesseractOcrOptions / TesseractCliOcrOptions / OcrMacOptions / NemotronOcrOptions con mode=OcrMode.FULL_PAGE para página completa. Depura lo que ve OCR con --debug-visualize-ocr.

Binario Tesseract según SO. Pasos completos por SO en la visión general y guías de SO. Pre-descarga modelos OCR para máquinas sin conexión o CI: docling-tools models download --all, o dirigidos --easyocr-lang de / --rapidocr-backend-lang onnxruntime:el. Ver la referencia CLI.

Windows: instala la build UB Mannheim, añádela al PATH y apunta TESSDATA_PREFIX a su carpeta tessdata\. Si tesserocr no compila: pip uninstall tesserocr y pip install --no-binary :all: tesserocr.

RapidOCR envuelve modelos PP-OCR. Dos cosas varían por separado: el backend (runtime) y la versión PP-OCR (generación del modelo).

Tokens de idioma (códigos nativos): v4: arabic, ch, chinese_cht, cyrillic, devanagari, en, japan, ka, korean, latin, ta, te. v5: arabic, ch, cyrillic, devanagari, el, en, eslav, korean, latin, ta, te, th. v6: ch, chinese_cht, en, japan + unos 45 códigos europeos (de, fr, es, it, pt, nl, pl …) con alias zh→ch, zh_cn→ch, zh_tw→chinese_cht, ja/jp→japan, ko→korean (ojo: coreano en v6 solo existe como alias). de/german y fr/french existen por duplicado.

Familias de escritura (un token cubre muchos idiomas): cyrillic (34: ruso, ucraniano, kazajo … + inglés), devanagari (14: hindi, maratí, sánscrito … + inglés), arabic (9: árabe, persa, urdu … + inglés), eslav (eslavo oriental: ruso, bielorruso, ucraniano + inglés).

Un idioma por pasada: RapidOCR usa la primera entrada de lang y avisa del resto. Python: RapidOcrOptions(lang=["eslav"], backend="onnxruntime"); admite checkpoints propios (ver ejemplo de modelos propios).

EasyOCR (checkpoints gen2, detector craft_mlt_25k.pth) acepta varios idiomas a la vez, pero la resolución elige el único checkpoint que cubra todos los pedidos. Un idioma innecesario degrada el modelo en silencio: ["en"] selecciona el preciso english_g2.pth, mientras ["en","de"] cae al genérico latin_g2.pth.

• Dos sabores, un motor: tesseract invoca la CLI del sistema (sin extra pip); tesserocr enlaza la librería en proceso (más rápido, requiere el binding compilado). Misma precisión, misma traineddata.
• Idioma = stem traineddata: deu, chi_sim, chi_tra, srp_latn, aze_cyrl, deu_latf, frk, jpn_vert, script/Latin, script/Cyrillic, más cualquier fichero entrenado propio. Lo instalado en .traineddata es lo usable.
• Comprobación al construir: los ficheros ausentes fallan de inmediato con el conjunto instalado en el mensaje, no a mitad de conversión.
• lang vacío = detección de escritura: --ocr-lang "" ejecuta detección de orientación/escritura por página, que requiere la traineddata osd.
• Detección automática de idioma en el ejemplo oficial.

OcrMac es una capa fina sobre Apple Vision: sin binarios ni modelos descargables. Los reconocedores vienen con el SO, así que la cobertura es propiedad de tu versión de macOS, no del release ocrmac.

• Instalación: pip install "docling[ocrmac]"; Python: OcrMacOptions.
• Coincidencia por BCP-47 con regiones: iso:de encuentra de-DE, iso:pt encuentra pt-BR, iso:zh-CN encuentra zh-Hans.
• Códigos de región raros como vi-VT deben pasarse nativos (sin prefijo). lang vacío deja elegir a Vision.

Requiere Linux x86_64 con CUDA 13.x y el índice torch cu130 (línea de instalación en sección 4). Un idioma por pasada (gana la primera entrada). Python: NemotronOcrOptions.

• KServe v2: para equipos cuyo OCR corre como microservicio remoto. lang no se valida ni mapea: la primera entrada sale tal cual, el resto se descarta con aviso. Usa los códigos de tu despliegue; iso: solo vale si el servidor lo habla (ninguno lo hace).
• Plugin OnnxTR: pip install "docling-ocr-onnxtr[cpu]", activa --allow-external-plugins y elige por el nombre del plugin. Ver el repo docling-OCR-OnnxTR.
• SuryaOCR con modelos propios en el ejemplo oficial; lista opciones de terceros con --show-external-plugins.

Cada motor recibe idiomas por un solo campo, OcrOptions.lang. Cada entrada tiene exactamente dos formas:

Código nativo (sin prefijo): la grafía propia del motor, pasada tal cual: ch (chino PP-OCR), deu (alemán Tesseract), ch_sim (EasyOCR), en-US (Vision).

Etiqueta portable: BCP-47 tras iso:, mapeada al motor: iso:de, iso:en-US, iso:zh-Hant. Incluye siempre la escritura cuando no es la defecto: el serbio latino debe ser iso:sr-Latn (el serbio por defecto es cirílico).

Cada motor informa lo que sirve: supported_ocr_languages() devuelve códigos nativos + BCP-47 en grafía lista para pegar en lang. Docling nunca sustituye en silencio: un idioma inservible lanza error nombrando lo que el motor sí sirve. RapidOCR y Nemotron corren un idioma a la vez (gana la primera etiqueta, el resto avisa).

from docling.datamodel.pipeline_options import TesseractCliOcrOptions
TesseractCliOcrOptions(lang=["deu", "eng"])       # nativo: tesseract -l deu+eng
TesseractCliOcrOptions(lang=["iso:de", "iso:en"]) # portable: lo mismo

Qué significa una lista vacía según el motor, y códigos que ocultan una etiqueta (desnudo = el modelo; iso: = el idioma):

• RapidOCR en CUDA: instala el ONNX Runtime GPU (pip install "docling[onnxruntime]"), confirma que CUDAExecutionProvider esté en ort.get_available_providers() y usa el backend onnxruntime con dispositivo CUDA. El backend torch es la alternativa (ojo: PP-OCRv5 + torch = solo chino).
• Nemotron es solo-GPU por diseño (CUDA 13.x, Linux x86_64).
• EasyOCR / Tesseract / OcrMac son en la práctica CPU: pon una CPU rápida y gasta el presupuesto GPU en etapas de layout/tablas. El ajuste fino (lotes, servidores VLM) está en la guía oficial GPU.

import onnxruntime as ort
assert "CUDAExecutionProvider" in ort.get_available_providers()

from docling.datamodel.accelerator_options import AcceleratorDevice, AcceleratorOptions
from docling.datamodel.pipeline_options import PdfPipelineOptions, RapidOcrOptions
pipeline_options = PdfPipelineOptions(
    accelerator_options=AcceleratorOptions(device=AcceleratorDevice.CUDA),
    ocr_options=RapidOcrOptions(backend="onnxruntime", lang=["eslav"]),
)

PDF escaneado, OCR de página completa. Elegir motor explícito. Omitir OCR en PDF digitales (lo más rápido). OCR en alemán + inglés, etiquetas portables:

Más ejemplos trabajados: forzar OCR de página completa, detección de idioma Tesseract, RapidOCR con modelos propios, biblioteca local y el configurador.

from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import (
    OcrMode, PdfPipelineOptions, RapidOcrOptions,
)
from docling.document_converter import DocumentConverter, PdfFormatOption

pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True
pipeline_options.ocr_options = RapidOcrOptions(mode=OcrMode.FULL_PAGE)
# Sustituye por EasyOcrOptions / TesseractOcrOptions / TesseractCliOcrOptions
# / OcrMacOptions (macOS) / NemotronOcrOptions (Linux CUDA) según necesites.

converter = DocumentConverter(
    format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)}
)
doc = converter.convert("scan.pdf").document
print(doc.export_to_markdown())

• Texto escaneado no reconocido: OCR apagado o el modo defecto no vio la capa ausente. Fuerza --ocr-mode full_page y prueba otro motor. Ver OCR de un PDF escaneado.
• El extra OCR no instala: RapidOCR/EasyOCR son solo pip; Tesseract requiere antes binario + TESSDATA_PREFIX. Ver error de instalación del paquete OCR.
• Conversión lenta: OCR y enriquecimientos son las etapas CPU más caras. --no-ocr en digitales, --table-mode fast o GPU. Ver conversión lenta.
• GPU ignorada: confirma torch.cuda.is_available() / CUDAExecutionProvider y usa --device cuda (mps en Apple Silicon). Ver GPU no usada.
• Salida en idioma erróneo: revisa sombras (ka frente a iso:ka-Geor), mantén cortas las listas EasyOCR y verifica con supported_ocr_languages().

Verificado con Docling v2.129.0 · Última comprobación 2026-09-22 · Fuente oficial