mve-micro-docs/OCR_SETUP.md

Guía de Instalación y Configuración de OCR

<EFBFBD> ¿Usas Docker? (Recomendado)

Si usas Docker Compose, NO necesitas instalar nada localmente. Todo está incluido en el contenedor.

Instalación con Docker

1. Asegúrate de tener tu archivo .env configurado:

OCR_ENABLED=true
OCR_LANGUAGE=spa
OCR_DPI=300
OCR_TIMEOUT=300

2. Construir y levantar los contenedores:

docker-compose build
docker-compose up -d

3. Verificar que Tesseract está instalado en el contenedor:

docker exec mve-incrementables-parser tesseract --version
docker exec mve-incrementables-parser tesseract --list-langs

¡Eso es todo! El Dockerfile ya incluye:

• ✅ Tesseract OCR
• ✅ Paquete de idioma español (spa)
• ✅ Poppler-utils (para conversión PDF a imagen)
• ✅ Todas las dependencias Python

Salta al final de este documento para ver cómo probar.

---

💻 Instalación Local (Sin Docker)

Solo sigue estas instrucciones si NO usas Docker y ejecutas el servicio directamente en tu máquina.

<EFBFBD>📋 Requisitos

El sistema ahora soporta OCR (Reconocimiento Óptico de Caracteres) usando Tesseract para leer PDFs escaneados o no editables.

🔧 Instalación de Tesseract

Windows

1. Descargar el instalador:

   • Visita: https://github.com/UB-Mannheim/tesseract/wiki
   • Descarga tesseract-ocr-w64-setup-5.3.x.exe (versión más reciente)

2. Instalar Tesseract:

   • Ejecuta el instalador
   • IMPORTANTE: Asegúrate de instalar el paquete de idioma Español (spa) durante la instalación
   • Ruta recomendada: C:\Program Files\Tesseract-OCR

3. Agregar Tesseract al PATH:

   • Botón derecho en "Este equipo" → Propiedades → Configuración avanzada del sistema
   • Variables de entorno → Path → Editar → Nuevo
   • Agregar: C:\Program Files\Tesseract-OCR
   • Guardar y reiniciar la terminal

4. Verificar instalación:

   tesseract --version
   

   Deberías ver algo como: tesseract 5.3.x

5. Verificar idioma español:

   tesseract --list-langs
   

   Deberías ver spa en la lista

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install tesseract-ocr tesseract-ocr-spa
tesseract --version

macOS

brew install tesseract tesseract-lang

📦 Instalación de Dependencias Python

pip install -r requirements.txt

Esto instalará:

• pytesseract - Interface Python para Tesseract
• Pillow - Procesamiento de imágenes
• pdf2image - Conversión de PDF a imágenes

Nota para Windows: También necesitas instalar poppler:

1. Descarga poppler para Windows: https://github.com/oschwartz10612/poppler-windows/releases
2. Extrae el archivo ZIP
3. Agrega poppler-xx\Library\bin al PATH del sistema

⚙️ Configuración

Edita tu archivo .env para configurar el OCR:

# OCR Settings
OCR_ENABLED=true           # true para habilitar OCR, false para deshabilitarlo
OCR_LANGUAGE=spa           # "spa" para español, "eng" para inglés
OCR_DPI=300                # Calidad de escaneo (300 recomendado, más alto = más lento)
OCR_TIMEOUT=300            # Tiempo máximo en segundos para procesar

🚀 Cómo Funciona

El sistema ahora funciona de manera inteligente y automática:

1. PDFs Editables (con texto seleccionable)

• Se extrae el texto normalmente usando PyMuPDF o pdfplumber
• Rápido y eficiente
• No usa OCR

2. PDFs Escaneados (imágenes, sin texto)

• El sistema detecta automáticamente que el PDF no tiene texto
• Activa el OCR automáticamente
• Extrae el texto de las imágenes usando Tesseract
• Más lento pero funcional

3. Proceso Automático

PDF recibido 
    ↓
Intentar extracción normal (PyMuPDF)
    ↓
¿Tiene texto? → SÍ → Retornar texto
    ↓
    NO
    ↓
¿OCR habilitado? → NO → Error
    ↓
    SÍ
    ↓
Convertir PDF a imágenes
    ↓
Aplicar OCR a cada página
    ↓
Retornar texto extraído

📝 Ejemplo de Uso

from app.services.pdf_text import extract_text_from_pdf

# Leer PDF
with open("documento.pdf", "rb") as f:
    pdf_bytes = f.read()

# Extraer texto (OCR automático si es necesario)
text, pages, method = extract_text_from_pdf(
    pdf_bytes,
    enable_ocr=True,      # Habilitar OCR
    ocr_lang="spa"        # Idioma español
)

print(f"Método usado: {method}")  # "pymupdf", "pdfplumber", o "ocr"
print(f"Páginas: {pages}")
print(f"Texto extraído: {text[:500]}...")

🔍 Métodos de Extracción

El sistema retorna uno de estos métodos en method:

• pymupdf: Extracción exitosa con PyMuPDF (texto seleccionable)
• pdfplumber: Extracción con pdfplumber (fallback)
• ocr: Texto extraído usando OCR (PDF escaneado)

⚡ Rendimiento

PDFs Editables

• ⚡ Muy rápido: < 1 segundo para documentos de 10 páginas
• 💾 Bajo uso de CPU y memoria

PDFs Escaneados (OCR)

• 🐌 Más lento: 5-30 segundos por página (depende de DPI)
• 💻 Mayor uso de CPU y memoria
• 📊 Calidad depende de:
  • Resolución del escaneo original
  • Claridad del texto en la imagen
  • DPI configurado (más alto = mejor pero más lento)

Optimización

Para mejorar velocidad del OCR:

• Reducir OCR_DPI a 200 (menos calidad, más rápido)
• Usar procesamiento asíncrono con Celery (ya implementado)

🧪 Pruebas

Con Docker

# Verificar Tesseract en el contenedor
docker exec mve-incrementables-parser tesseract --version
docker exec mve-incrementables-parser tesseract --list-langs

# Probar el endpoint con un PDF
curl -X POST http://localhost:9876/api/v1/incrementables/parse \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@documento_escaneado.pdf"

Local (sin Docker)

Para probar con un PDF escaneado:

# Usando el endpoint síncrono
curl -X POST http://localhost:8000/api/v1/incrementables/parse \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@documento_escaneado.pdf"

# Usando el endpoint asíncrono (recomendado para OCR)
curl -X POST http://localhost:8000/api/v1/incrementables/parse-async \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@documento_escaneado.pdf"

🐛 Solución de Problemas

Error: "tesseract is not installed"

• Verifica que Tesseract esté instalado: tesseract --version
• Verifica que esté en el PATH del sistema
• Reinicia la terminal/IDE después de agregar al PATH

Error: "Failed to load language 'spa'"

• Instala el paquete de idioma español
• Windows: Reinstala Tesseract y marca la opción "Spanish language data"
• Linux: sudo apt install tesseract-ocr-spa

Error: "Unable to load library 'libpoppler'"

• Windows: Instala poppler y agrégalo al PATH
• Linux: sudo apt install poppler-utils
• macOS: brew install poppler

OCR muy lento

• Reduce OCR_DPI en el archivo .env
• Usa el endpoint asíncrono para procesar en background
• Considera procesar solo las páginas necesarias

OCR no detecta texto correctamente

• Aumenta OCR_DPI a 400 o 600
• Verifica que el PDF escaneado tenga buena calidad
• Prueba con otro idioma si el documento está en inglés: OCR_LANGUAGE=eng

📚 Recursos Adicionales

• Documentación Tesseract
• pytesseract GitHub
• pdf2image Documentation

🎯 Próximos Pasos

Para mejorar aún más:

1. Pre-procesamiento de imágenes: Aplicar filtros para mejorar calidad
2. Detección de idioma automática
3. Caché de resultados OCR para evitar reprocesar el mismo PDF
4. Procesamiento paralelo de páginas para mayor velocidad
5. Migrar a servicios cloud (AWS Textract) para mejor precisión