Si tus agentes se atragantan con PDFs escaneados, texto mal extraído o documentos gordos, aquí tienes una forma local de clasificarlos, sacar texto y dejarlos en Markdown sin depender de servicios externos.
Esto va para devs frikis, sysadmins caseros y gente de homelab que ya usa agentes o RAG y necesita meter documentos reales en el flujo sin que cada PDF sea una lotería. También te sirve si trabajas con documentación interna, escaneos viejos o informes que vienen en formatos distintos y quieres una tubería predecible antes de pasársela a un agente.
Al final tendrás un pipeline local que detecta si un PDF es escaneado o contiene texto, extrae lo que pueda sin romperse, aplica OCR cuando toca y deja el resultado en Markdown listo para indexar, resumir o meter en un agente. La idea es que tus documentos pasen de ser un caos a una entrada bastante limpia y reutilizable.
Para que veas dónde encaja esto en tu día a día antes de invertir el rato.
Escenario: Tienes manuales, procedimientos y anexos en PDF, pero unos son texto y otros son escaneos cutres.
Cómo: El pipeline clasifica cada archivo y decide si extrae texto directo o si necesita OCR, evitando que un documento escaneado se quede vacío.
Resultado: Tu base documental queda uniforme y los agentes dejan de inventarse cosas por culpa de PDFs mal leídos.
Escenario: Guardas apuntes de homelab, diagramas y PDFs de cursos que luego quieres consultar con un agente.
Cómo: Se convierten a Markdown con texto usable, así puedes buscar, resumir y enlazar contenido sin abrir cada PDF a mano.
Resultado: Recuperas información rápido y sin pelearte con visores de PDF.
Escenario: Recibes informes largos con tablas, capturas y texto incrustado, y quieres analizarlos localmente.
Cómo: Clasificar primero evita gastar OCR donde no hace falta y reduce errores en la extracción.
Resultado: Menos tiempo limpiando basura y más tiempo sacando conclusiones útiles.
Escenario: Tienes PDFs de proveedores, algunos generados por software y otros escaneados por una impresora vieja.
Cómo: El pipeline separa los casos y convierte el contenido a una forma más manejable para extraer campos o buscar referencias.
Resultado: Puedes automatizar búsquedas y validaciones sin depender de una API externa.
Escenario: Quieres meter documentos en un índice para que un agente responda con contexto real y no con humo.
Cómo: Markdown limpio y texto extraído de forma consistente mejora la segmentación, el chunking y la recuperación semántica.
Resultado: El sistema responde mejor porque entra menos ruido y más contenido útil.
Crea una estructura simple para separar entrada, salida y temporales. Esto te evita mezclar PDFs originales con resultados y luego no saber qué has procesado ya. Si luego lo automatizas con cron o systemd, esta separación te ahorra dolor.
mkdir -p ~/pdf-pipeline/{input,output,tmp}Antes de montar nada serio, prueba con varios tipos de documento: uno con texto real, uno escaneado y uno mixto. Así ves rápido si el pipeline distingue bien los casos y dónde falla. No empieces con el PDF más gordo de tu vida.
cp /ruta/a/tus/pdfs/*.pdf ~/pdf-pipeline/input/La primera decisión es saber si el PDF trae texto o si es una imagen disfrazada. Esa clasificación es clave para no lanzar OCR a todo lo que se mueve, porque eso te come tiempo y mete errores donde no hacen falta. Aquí puedes apoyarte en una librería o herramienta local que inspeccione el PDF y devuelva el tipo de contenido; si eliges una librería concreta, sigue su documentación oficial para integrarla en tu script.
docker run --rm -v ~/pdf-pipeline:/work alpine sh -lc 'ls -la /work/input'Para los PDFs con texto embebido, lo ideal es sacar el contenido sin pasar por OCR. Eso suele ser más rápido y más fiel, sobre todo en documentos generados digitalmente. Si tu herramienta de extracción tiene opciones de limpieza o preservación de saltos de línea, pruébalas con dos o tres muestras antes de automatizar.
docker run --rm -v ~/pdf-pipeline:/work alpine sh -lc 'ls /work/input'Cuando el PDF sea una imagen, toca OCR. Aquí es donde suelen aparecer los problemas de calidad: rotación, contraste malo, páginas partidas o fuentes raras. La clave es tratar el OCR como un fallback, no como el camino principal, y revisar siempre un par de resultados para medir si merece la pena ajustar preprocesado.
docker run --rm -v ~/pdf-pipeline:/work alpine sh -lc 'ls /work/input'Una vez tienes texto limpio, pásalo a Markdown para que sea más cómodo de trocear, indexar y meter en agentes. No intentes conservar una maquetación perfecta si el objetivo es recuperación de información; prioriza títulos, listas, párrafos y bloques de código. Si el documento tiene tablas complejas, asume que habrá pérdida y documenta esa limitación.
docker run --rm -v ~/pdf-pipeline:/work alpine sh -lc 'ls /work/output'Procesa todos los PDFs de entrada y deja un log con qué se ha extraído bien, qué ha ido por OCR y qué ha fallado. Esto te permite reintentar solo los rotos y no volver a pasar todo el lote. Si luego quieres dejarlo fino, lo normal es envolverlo en un script y lanzarlo con systemd timer o cron.
systemctl --user statusEs el error clásico: funciona, pero lento y con más ruido. Primero clasifica, luego decide. Si todo pasa por OCR, vas a perder tiempo y calidad sin necesidad.
No la conserva. Sirve para texto y estructura básica, no para reproducir un informe con diseño complejo. Si necesitas tablas perfectas o layout exacto, ese es otro problema distinto.
Luego no sabes qué era original, qué estaba procesado y qué ha fallado. Mantén carpetas separadas desde el minuto uno o acabarás borrando cosas por accidente.
Si el PDF está borroso, torcido o con poco contraste, el OCR no hace milagros. Puedes mejorar algo con preprocesado, pero hay documentos que simplemente vienen mal y punto.
Si lo montas así, tus agentes dejan de depender de PDFs caprichosos y trabajas con una entrada bastante más controlada. El siguiente nivel sería añadir chunking inteligente, metadatos por página y un índice local para búsqueda semántica.
Recibir un tutorial así cada semana →