Cómo convertir PDF a Markdown en Python

Por qué Markdown, y por qué es más difícil de lo que parece

Los LLM manejan Markdown excepcionalmente bien: los encabezados marcan los límites de sección, las tablas de tuberías mantienen alineados los datos tabulares y las listas siguen siendo listas. Alimentar un modelo con texto crudo extraído de un PDF pierde todo eso — y pasarle el binario del PDF no es una opción en la mayoría de pipelines. Por eso casi todo stack de RAG serio convierte los documentos a Markdown antes de trocearlos y generar embeddings.

La parte difícil es que los PDF no contienen estructura — contienen caracteres colocados en coordenadas x/y. Un conversor tiene que deducir qué líneas son encabezados (por el tamaño de fuente), qué palabras forman una tabla (por la alineación) y cuál es el orden de lectura (por el análisis del diseño). Las librerías difieren enormemente en lo bien que lo hacen, y por eso la elección importa.

Una segunda complicación: los PDF escaneados no contienen texto en absoluto, solo imágenes de páginas. Solo algunas de las opciones de abajo los manejan, mediante OCR.

Opción 1: PyMuPDF4LLM — rápida y ligera

PyMuPDF4LLM es una capa fina sobre PyMuPDF (fitz) creada específicamente para pipelines de LLM: pip install pymupdf4llm, y después md = pymupdf4llm.to_markdown("doc.pdf") — una línea, y es muy rápida: procesa la mayoría de documentos en bastante menos de un segundo.

Detecta encabezados por el tamaño de fuente, renderiza las tablas como tablas de tuberías y puede emitir fragmentos por página con metadatos para ingerirlos directamente en LlamaIndex o LangChain. Para PDF de origen digital con diseños sencillos — informes, documentación, papers sin formato exótico — es una opción por defecto excelente.

Límites: no tiene OCR, así que las páginas escaneadas vuelven vacías. Los diseños complejos de varias columnas y las tablas intrincadas pueden salir revueltos, porque sus heurísticas priorizan la velocidad sobre el análisis profundo del diseño. Nota de licencia: PyMuPDF es AGPL — bien para herramientas internas, pero consulta con tu equipo legal antes de incluirla en un producto comercial.

Opción 2: Marker — la mayor calidad, necesita GPU

Marker usa un pipeline de modelos de aprendizaje profundo para la detección de diseño, el orden de lectura y la estructura de tablas, y produce el Markdown más fiel de todas las opciones de código abierto — maneja papers académicos de varias columnas, tablas complejas e incluso ecuaciones.

El coste es la infraestructura: pesos de modelo de varios gigabytes, una GPU para tener una velocidad razonable (funciona en CPU, pero lento — a menudo decenas de segundos por documento) y un árbol de dependencias pesado que cuesta un esfuerzo real desplegar en producción o en entornos serverless.

Elige Marker cuando la calidad de salida en documentos difíciles sea la máxima prioridad y tengas el hardware — convertir en bloque un corpus académico en una máquina con GPU es su punto fuerte. Para un servicio ligero o una función serverless, el peso operativo normalmente lo descarta.

Opción 3: MarkItDown — el conversor multiformato de Microsoft

MarkItDown es la librería de código abierto de Microsoft para convertir de todo a Markdown: pip install markitdown, y después MarkItDown().convert("doc.pdf").text_content. Su fuerza es la amplitud — la misma API convierte PDF, DOCX, PPTX, XLSX, HTML y más, y por eso se hizo viral para preparar datos para LLM.

Para PDF en concreto, su extracción es más simple que la de las opciones dedicadas: se apoya en extracción de texto básica, así que la detección de encabezados y la fidelidad de las tablas quedan por detrás de PyMuPDF4LLM y Marker, y los PDF escaneados necesitan configurar OCR aparte.

Elige MarkItDown cuando necesites una sola dependencia que cubra muchos tipos de archivo con calidad moderada — un script de ingestión interno que debe aceptar "lo que suba la gente" — y no la mejor salida posible de PDF.

Opción 4: una API alojada — sin dependencia alguna

La cuarta opción es no ejecutar la conversión en local: envía el PDF con POST a una API de parseo y recibe el Markdown de vuelta. Con ParseJet: resp = httpx.post("https://api.parsejet.com/v1/parse/auto/file", headers={"Authorization": "Bearer KEY"}, files={"file": open("doc.pdf", "rb")}) — el campo "text" de la respuesta JSON es el Markdown.

Esta vía trae OCR integrado para las páginas escaneadas, no requiere instalar pesos de modelo ni librerías nativas, y funciona exactamente igual en una función serverless, un contenedor o un notebook. También esquiva por completo la cuestión de la AGPL. La contrapartida es un viaje de red y un coste por documento después del nivel gratuito (300 créditos/mes gratis; un PDF cuesta 3 créditos).

Elige la API cuando quieras el pipeline funcionando hoy, cuando entre tus PDF haya escaneados o cuando despliegues en un entorno donde las dependencias pesadas duelen — Lambda, Cloud Run, Vercel.

¿Cuál deberías usar?

PDF de origen digital, diseños de sencillos a moderados, la velocidad importa: PyMuPDF4LLM. Es la mejor relación esfuerzo-calidad en Python puro.

Documentos difíciles (papers de varias columnas, tablas complejas) y tienes una GPU: Marker. Nada de código abierto supera su calidad de salida.

Muchos tipos de archivo distintos con una sola librería, y una calidad moderada te basta: MarkItDown.

PDF escaneados de por medio, despliegue serverless o cero ganas de gestionar dependencias: la API alojada. Una llamada HTTP, OCR incluido y el mismo esquema de salida para todos los documentos.

Ejemplo completo: de una carpeta de PDF a archivos Markdown

Elijas la vía que elijas, la forma del pipeline es la misma — iterar, convertir, escribir. Aquí está con la API (cambia la llamada interna por pymupdf4llm.to_markdown() para ejecutarlo en local):

import httpx; from pathlib import Path — y después, por cada pdf en Path("pdfs/").glob("*.pdf"): resp = httpx.post("https://api.parsejet.com/v1/parse/auto/file", headers={"Authorization": "Bearer KEY"}, files={"file": pdf.read_bytes()}); Path("md/", pdf.stem + ".md").write_text(resp.json()["text"], encoding="utf-8").

Para la ingestión en RAG, trocea el Markdown por encabezados en lugar de por número fijo de caracteres — los fragmentos que respetan los encabezados mantienen las secciones intactas y se recuperan muchísimo mejor. Esa fidelidad estructural es exactamente el motivo por el que valía la pena hacer la conversión con cuidado.