PDF a Markdown para RAG
Convierte PDF en Markdown limpio y apto para chunking para recuperación e ingesta de LLM: tablas y fórmulas intactas, escaneos con OCR, muchos menos tokens que el texto en bruto del PDF. Contrólalo desde la API REST o el MCP alojado.
Markdown es la entrada limpia que RAG quiere
Incrustar texto en bruto de PDF le da al recuperador fragmentos ruidosos: encabezados, listas y tablas colapsan, el orden de lectura se rompe y se cuela basura binaria y de maquetación. Convierte el PDF a Markdown primero y la estructura del documento sobrevive, así puedes trocear por encabezados y secciones, mantener tablas y fórmulas como hechos, y gastar muchos menos tokens por pasaje. Fragmentos más limpios a la entrada, mejor recuperación a la salida.
Qué aporta el Markdown limpio a tu pipeline
Límites de fragmento limpios
Los encabezados y secciones sobreviven, así dividir por estructura produce fragmentos coherentes y autónomos en vez de cortes a mitad de frase.
Menos tokens
El Markdown plano es mucho más barato de incrustar y de enviar como contexto que los volcados de PDF en bruto o el HTML, así indexas y recuperas más por menos.
Las tablas siguen siendo hechos
Las columnas se convierten en tablas Markdown reales, no líneas revueltas, así los números tabulares siguen siendo recuperables en vez de quedar desordenados.
Fórmulas conservadas
La notación matemática se mantiene en vez de aplanarse en caracteres ilegibles que contaminan las incrustaciones.
Los escaneos se vuelven texto
El OCR convierte los PDF de solo imagen y escaneados en Markdown seleccionable en muchos idiomas, así los escaneos también son indexables.
Enlaces y notas al pie
Los hipervínculos y las notas al pie se conservan como enlaces Markdown en vez de descartarse, manteniendo las referencias intactas.
Ingiere un PDF en cuatro pasos
Un ciclo de vida predecible sobre HTTPS con una clave de API bearer. El MCP alojado expone los mismos pasos como herramientas de agente.
Crea un trabajo
Haz POST de la URL del PDF (o los bytes subidos) a /api/v2/jobs. Obtienes un id de trabajo y un estado.
Consulta hasta ready
Haz GET /api/v2/jobs/{id} hasta que status sea ready o error. En error, lee error_code/error_message. En planes de pago, registra un webhook en vez de consultar.
Obtén el Markdown
Haz GET /api/v2/jobs/{id}/download. Respeta truncated y pages: truncated significa que un documento largo se devolvió parcialmente hasta el límite de tiempo.
Trocea e incrusta
Divide por encabezados/secciones, incrusta los fragmentos e indéxalos en tu base de datos vectorial. La estructura de Markdown mantiene los límites limpios.
# 1. crear un trabajo desde una URL de PDF curl -s -X POST https://pdf2md.dev/api/v2/jobs \ -H "Authorization: Bearer p2m_your_key" \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com/paper.pdf"}' # -> { "job_id": "...", "status": "queued" } # 2. consultar el estado hasta ready o error curl -s https://pdf2md.dev/api/v2/jobs/JOB_ID \ -H "Authorization: Bearer p2m_your_key" # -> { "status": "ready", "pages": 24, "truncated": false } # en caso de fallo: { "status": "error", "error_code": "...", "error_message": "..." } # 3. obtener el Markdown, luego trocearlo + incrustarlo curl -s https://pdf2md.dev/api/v2/jobs/JOB_ID/download \ -H "Authorization: Bearer p2m_your_key"
¿Prefieres herramientas de agente? El MCP alojado expone el mismo ciclo de vida (pdf_to_markdown_create_job_from_url, _get_job, _get_markdown) para que Claude, ChatGPT y los frameworks de agentes ingieran PDF sin servidor local.
Estrategias de chunking para Markdown
El Markdown limpio te da costuras naturales por las que dividir, así los fragmentos quedan coherentes y recuperables.
Divide por encabezados
Usa la jerarquía de encabezados como límites de fragmento para que cada uno sea una sección autónoma con su propio contexto.
Mantén las tablas enteras
Nunca dividas dentro de una tabla Markdown; media tabla pierde su sentido. Mantén cada tabla, y su encabezado, en un solo fragmento.
Añade un poco de solape
Un pequeño solape de una o dos frases entre fragmentos adyacentes conserva el contexto en los límites y mejora la recuperación.
Lleva la ruta del encabezado
Antepone el encabezado de sección (o la ruta de encabezados) a cada fragmento para que la incrustación capture de dónde viene.
Tamaño adecuado
Apunta a unos pocos cientos de tokens por fragmento: demasiado grande diluye la relevancia, demasiado pequeño pierde contexto. La estructura de Markdown lo hace fácil de ajustar.
Elimina lo repetido
Quita encabezados y pies repetidos para que no dominen las incrustaciones; el conversor ya elimina la mayor parte del ruido de maquetación.
Una ingesta mínima en Python
Crear, consultar, obtener y luego dividir por encabezados, listo para incrustar e indexar en tu base de datos vectorial.
# pip install requests import requests, time, re API = "https://pdf2md.dev/api/v2" H = {"Authorization": "Bearer p2m_your_key"} job = requests.post(f"{API}/jobs", headers=H, json={"url": "https://example.com/paper.pdf"}).json() jid = job["job_id"] while True: j = requests.get(f"{API}/jobs/{jid}", headers=H).json() if j["status"] in ("ready", "error"): break time.sleep(3) md = requests.get(f"{API}/jobs/{jid}/download", headers=H).text # división simple por encabezados de nivel superior -> fragmentos listos para incrustar chunks = re.split(r"\n(?=# )", md)
Por qué las tablas se recuperan mejor
Una tabla revuelta se incrusta como ruido, así el número que necesitas rara vez coincide con una consulta. Como tabla Markdown real, las filas y los encabezados quedan alineados, así los datos tabulares como precios, métricas y fechas siguen siendo buscables y citables en las respuestas.
Consulta vs webhooks
Para unos pocos documentos, consulta GET /api/v2/jobs/{id} cada pocos segundos. Para pipelines masivos o de backend en un plan de pago, registra un webhook (o pasa callback_url) y te hacemos POST en ready o error, así te saltas la consulta por completo.
Intégralo en tu pipeline
El mismo conversor es una API REST y un endpoint MCP alojado, con descubrimiento legible por máquina para que scripts y agentes lo controlen directamente.
Preguntas habituales
¿Por qué Markdown para RAG en vez del texto en bruto del PDF?
La extracción en bruto pierde la estructura (los encabezados, listas y tablas colapsan y el orden de lectura se rompe), lo que produce fragmentos ruidosos. Markdown mantiene la estructura, así trocear por encabezados da pasajes más limpios y recuperables, y usa muchos menos tokens que los volcados en bruto o el HTML.
¿Sobreviven las tablas y fórmulas?
Sí. Las columnas se convierten en tablas Markdown reales en vez de líneas revueltas, y la notación matemática se conserva en vez de aplanarse, así los datos numéricos y tabulares siguen siendo recuperables. Más sobre extraer tablas.
¿Puedo automatizarlo en un pipeline?
Sí. Usa la API REST (crear, consultar, descargar) con una clave de API bearer, o el MCP alojado para frameworks de agentes. En planes de pago, un webhook elimina la consulta. No hay nada que alojar. Consulta el tutorial de Python para un ejemplo completo.
¿Cómo manejo los documentos largos?
Cada conversión se ejecuta hasta un presupuesto de tiempo por plan; un documento largo se devuelve parcialmente con truncated=true en vez de fallar. Lee truncated y divide los archivos muy grandes, o usa un plan superior con un presupuesto mayor.
¿Maneja PDF escaneados para la ingesta?
Sí. Los PDF de solo imagen y escaneados se procesan con OCR a Markdown seleccionable en muchos idiomas, así los escaneos se vuelven texto recuperable en tu índice.
¿Cómo debería trocear el Markdown para RAG?
Divide por la jerarquía de encabezados para que cada fragmento sea una sección autónoma, mantén las tablas enteras, añade un pequeño solape entre fragmentos y antepone el encabezado de la sección para que la incrustación conozca el contexto. Apunta a unos pocos cientos de tokens por fragmento.
¿Por qué las tablas Markdown se recuperan mejor que el texto en bruto?
La extracción en bruto revuelve las columnas en ruido, así el valor que necesitas rara vez coincide con una consulta. Una tabla Markdown real mantiene filas y encabezados alineados, así los datos tabulares siguen siendo buscables y citables.
¿Hay un plan gratuito para pruebas?
Sí. Una cuenta de Google gratuita habilita una clave de API y el MCP alojado: 3 espacios, archivos de 10 MB, un presupuesto de tiempo de 15 minutos y retención de 1 hora. Los planes de pago amplían cada límite y añaden webhooks y creación por lotes.