mve-micro-docs/DOCKER_OCR.md

🐳 Guía Rápida: OCR con Docker

✅ Lo que YA está incluido en Docker

Cuando usas Docker Compose, TODO está incluido automáticamente:

• ✅ Tesseract OCR
• ✅ Idioma español (spa)
• ✅ Poppler (conversión PDF a imagen)
• ✅ Todas las dependencias Python
• ✅ PyMuPDF y pdfplumber

No necesitas instalar nada en tu máquina local.

🚀 Uso Rápido

1. Configurar variables de entorno

Edita tu .env:

# OCR ya viene habilitado por defecto
OCR_ENABLED=true
OCR_LANGUAGE=spa
OCR_DPI=300
OCR_TIMEOUT=300

2. Construir y ejecutar

# Primera vez o después de cambios en Dockerfile
docker-compose build

# Iniciar servicios
docker-compose up -d

# Ver logs
docker-compose logs -f

3. Verificar que OCR funciona

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

# Verificar idiomas instalados
docker exec mve-incrementables-parser tesseract --list-langs

# Verificar en el worker de Celery
docker exec mve-celery-worker tesseract --version

Deberías ver:

tesseract 5.x.x
...
spa
eng
osd

🧪 Probar con un PDF Escaneado

# 1. Primero obtén un token
curl -X POST http://localhost:9876/api/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=tu_password"

# 2. Usa el token para subir un PDF
curl -X POST http://localhost:9876/api/v1/incrementables/parse \
  -H "Authorization: Bearer TU_TOKEN_AQUI" \
  -F "file=@/ruta/al/documento.pdf"

📊 Ver logs del OCR

# Ver logs del contenedor principal
docker-compose logs -f mve-incrementables-parser

# Ver logs del worker (procesamiento asíncrono)
docker-compose logs -f celery-worker

# Buscar logs específicos de OCR
docker-compose logs | grep -i "ocr"
docker-compose logs | grep -i "tesseract"

🔧 Configuración Avanzada

Cambiar idioma del OCR

Edita .env:

OCR_LANGUAGE=eng  # Para inglés
# o
OCR_LANGUAGE=spa  # Para español

Reinicia los contenedores:

docker-compose restart

Ajustar rendimiento OCR

Para mayor velocidad (menos calidad):

OCR_DPI=200

Para mayor calidad (más lento):

OCR_DPI=600

Reinicia:

docker-compose restart

Deshabilitar OCR

Si solo quieres procesar PDFs con texto seleccionable:

OCR_ENABLED=false

🐛 Solución de Problemas

El servicio no inicia después de agregar OCR

# Reconstruir la imagen
docker-compose down
docker-compose build --no-cache
docker-compose up -d

Error: "tesseract command not found"

Esto significa que la imagen no se construyó correctamente.

# Ver si Tesseract está en la imagen
docker exec mve-incrementables-parser which tesseract

# Si no está, reconstruir
docker-compose build --no-cache mve-incrementables-parser

OCR muy lento

El OCR es naturalmente más lento que la extracción de texto normal. Para PDFs escaneados:

• Usa el endpoint asíncrono (/parse-async)
• El worker de Celery procesará en background
• Reduce OCR_DPI si no necesitas máxima calidad

Ver qué método se usó (texto vs OCR)

El campo extraction_method en la respuesta te dice:

• "pymupdf" o "pdfplumber" → PDF con texto (rápido)
• "ocr" → PDF escaneado procesado con Tesseract (lento)

📝 Ejemplo de Respuesta

Cuando el sistema usa OCR automáticamente:

{
  "status": "success",
  "message": "Incrementables extraídos exitosamente",
  "data": {
    "incrementables": {
      "fletes": 1591.20,
      "seguros": 0.0,
      "almacenaje": 0.0,
      "regalias": 0.0,
      "currency": "USD",
      "total": 1591.20
    },
    "document_info": {
      "filename": "documento_escaneado.pdf",
      "pages": 5,
      "file_hash": "abc123...",
      "file_size_bytes": 524288
    },
    "extraction_info": {
      "method": "ocr",  // ← Indica que se usó OCR
      "anchors_found": ["AJUSTE DE INCREMENTABLES EN:"],
      "warnings": []
    }
  }
}

🎯 Resumen

Con Docker:

• ✅ Todo incluido automáticamente
• ✅ Sin instalación manual
• ✅ Funciona igual en Windows, Mac, Linux
• ✅ OCR listo para usar desde el primer docker-compose up

Comandos clave:

docker-compose build          # Construir imagen
docker-compose up -d          # Iniciar servicios
docker-compose logs -f        # Ver logs
docker-compose restart        # Reiniciar después de cambios en .env
docker-compose down           # Detener todo

¡Eso es todo! 🎉