Cómo lee OCR un PDF escaneado — y por qué esta herramienta devuelve Markdown

Un PDF escaneado guarda las páginas como imágenes raster: fotografías de texto, no caracteres seleccionables. El OCR (reconocimiento óptico de caracteres) examina esos píxeles, deduce qué formas son caracteres y emite texto real. En PDF123 esto funciona como herramienta gratuita en el navegador y como POST /api/v1/misc/ocr-pdf; la respuesta es Markdown, no un PDF reescrito.

El escaneo sigue siendo una imagen

El OCR no limpia, no enfoca ni sustituye el mapa de bits. Un escaneo nítido que el OCR lee mal sigue viéndose nítido: el cuello de botella nunca fue la imagen, sino el reconocimiento. Cambiar el motor de reconocimiento sobre el mismo lote de escaneos puede desplazar la precisión en un margen amplio, sin que los píxeles cambien en absoluto.

El OCR clásico de PDF escribe una segunda capa de texto invisible, alineada bajo la imagen, para que seleccionar y buscar acierten en las palabras correctas. Eso es lo que muestra el diagrama, y así siguen trabajando muchas herramientas de escritorio.

Qué devuelve en realidad este endpoint

La ruta OCR llama a /api/v1/misc/ocr-pdf, que se ejecuta sobre un crate de Rust independiente, pdf-inspector (compilado con su función ocr). No le entrega el PDF completo a un modelo de reconocimiento. pdf-inspector primero clasifica cada página como con texto nativo extraíble o como solo imagen. Las páginas con texto nativo conservan ese texto tal cual y nunca tocan el modelo de reconocimiento; las páginas de solo imagen pasan por el pipeline de reconocimiento: PDFium (el mismo renderizador de código abierto que Chrome usa internamente) rasteriza la página, y ONNX Runtime ejecuta el modelo PP-OCRv6 Small para leerla. Ambos tipos de página se cosen en orden en un único documento Markdown, por lo que la respuesta es text/markdown y la descarga termina en .md.

Ese contrato es nuevo en esta reescritura. El backend en Java/Spring Boot que este proyecto usaba antes llamaba a OCRmyPDF, el enfoque clásico de "imagen más capa de texto oculta", y devolvía un PDF. La reescritura en Rust sustituyó por completo esa ruta por el OCR selectivo de pdf-inspector, y la salida pasó de PDF a Markdown junto con ese cambio. El antiguo backend en Java ya se eliminó del repositorio; no es un interruptor que se pueda volver a activar.

Si necesitas un PDF buscable (imagen más capa de texto), esta salida no te sirve. Si necesitas texto que un agente o un pipeline puedan leer, Markdown es justamente el objetivo.

Auto frente a Force OCR

El formulario tiene un campo ocrType:

• Normal (cualquier valor distinto de force-ocr) corresponde a Auto: usa el texto existente donde el archivo ya lo tiene y ejecuta OCR en las páginas que son solo imagen. En un PDF nativo digital limpio, Auto no carga el runtime de OCR.
• Force OCR (ocrType=force-ocr) vuelve a ejecutar el reconocimiento en todas las páginas, incluidas las que ya tienen capa de texto. En páginas realmente de solo imagen pagas tiempo, no más precisión; a cambio, obtienes una pasada que ignora una capa existente rota o parcial.

El valor predeterminado del portal es Force OCR. No hay control de idioma: los códigos tessdata que quedaron del antiguo camino Java se ignoran.

El reparto entre Auto y Force ocurre dentro de la propia solicitud, y ni el portal ni la sonda de capacidades de la API lo comprueban de antemano. GET /api/v1/settings/get-endpoints-status siempre informa que ocr-pdf está habilitado, sin verificar realmente si PDFium, ONNX Runtime o el modelo PP-OCRv6 están instalados. La comprobación real ocurre en el momento en que una solicitud dispara el reconocimiento: si falta alguno de ellos, el endpoint devuelve 503, no un Markdown degradado que caiga en silencio solo al texto nativo. El modelo PP-OCRv6 Small pesa unos 31 MB; a menos que se haya precargado en la caché local al desplegar, se descarga por red la primera vez que una página realmente necesita reconocimiento. Una máquina sin conexión y sin el modelo precargado probablemente falle justo ahí, en su primera solicitud Force, en lugar de simplemente ir más lenta.

El reconocimiento es probabilístico

Los motores comparan patrones de píxeles con modelos de letras y palabras. Rinden bien con impresión limpia, de alto contraste y fuente estándar, y peor con:

• Escaneos de baja resolución o bajo contraste (calidad de fax frente a un original a 300 DPI)
• Escritura a mano, fuentes decorativas y maquetaciones raras (tablas a varias columnas, texto girado, formularios densos)
• Páginas torcidas que deforman los glifos lo justo para confundir la comparación

Un fax borroso no dará el mismo OCR que un escaneo limpio, elijas Auto o Force. Eso es una limitación del propio modelo, no algo que un parámetro pueda arreglar.

Qué no hace el OCR

El OCR te da texto. No reconstruye párrafos, encabezados, tablas ni un documento de Word reflowable. La maquetación editable es un problema de conversión que se suma al error de reconocimiento, no la misma tarea que leer un escaneo.

OCR de un PDF se ejecuta en el servidor y no pide cuenta. La descarga es Markdown. Si una capa de texto existente parece incorrecta, usa Force OCR para que Auto no confíe en ella; para comprobar si una máquina concreta tiene realmente instalados PDFium y el modelo, ejecutar una solicitud real es más fiable que leer la sonda de capacidades, ya que esta solo confirma que el endpoint existe, no que su runtime esté listo. Para claves de automatización y OpenAPI, consulta Desarrolladores.