Microservicios - Visión General

IRIS orquesta un pipeline IDP autónomo en 6 fases: de imágenes a datos estructurados y predicciones listo para integrarse en tus sistemas. Esta arquitectura por microservicios permite escala independiente por fase, despliegue flexible y time-to-value acelerado.

Los microservicios Python de IRIS implementan las 6 fases especializadas del pipeline. Cada servicio es independiente, escalable y optimizado para tareas específicas de machine learning y procesamiento de imágenes.

🏗️ Arquitectura de Microservicios

Filosofía de Diseño

Separación de Responsabilidades: Cada fase tiene un microservicio dedicado
Tecnología Especializada: Stack optimizado para cada tipo de procesamiento
Escalabilidad Independiente: Cada servicio puede escalarse según la demanda
Tolerancia a Fallos: Fallos en una fase no afectan otras fases
Desarrollo Paralelo: Teams pueden trabajar independientemente en cada servicio

Mapa de Servicios

🔬 Fase 1: Preprocesamiento de Imágenes

`image-processor` (Puerto 8001)

Responsabilidad: Corrección geométrica y preparación de imágenes para procesamiento posterior.

Tecnologías utilizadas (image-processor)

OpenCV: Procesamiento de imágenes y visión por computadora
NumPy: Operaciones matriciales de alto rendimiento
FastAPI: API REST con validación automática
Pillow: Manipulación de formatos de imagen

Funciones principales

Detección de Esquinas: Identificación automática de bordes del documento
Corrección de Perspectiva: Transformación geométrica para enderezar documentos
Unwarping: Corrección de distorsiones por curvatura o ángulo
Normalización: Ajuste de contraste, brillo y resolución
Filtrado de Ruido: Eliminación de artefactos y ruido de la imagen

API endpoints (image-processor)

POST /process          # Procesar imagen completa
POST /detect-corners   # Solo detección de esquinas
POST /unwarp          # Solo corrección de perspectiva
GET  /health          # Health check del servicio

Ejemplo de uso

# Enviar imagen para procesamiento
files = {'file': open('document.jpg', 'rb')}
response = requests.post('http://localhost:8001/process', files=files)
processed_image = response.json()['processed_image']

🧠 Fase 2: Embeddings y Clustering

`ml-embeddings` (Puerto 8002)

Responsabilidad: Generación de representaciones vectoriales y descubrimiento automático de clases de documentos.

Tecnologías utilizadas (ml-embeddings)

PyTorch: Framework de deep learning
Transformers (Hugging Face): Vision Transformers pre-entrenados
scikit-learn: Algoritmos de clustering y métricas
TIMM: Modelos de visión por computadora de estado del arte
FAISS: Búsqueda vectorial eficiente para grandes datasets

Algoritmos implementados

Vision Transformer (ViT): Embeddings de alta calidad para imágenes
K-means Clustering: Agrupación automática de documentos similares
DBSCAN: Clustering basado en densidad para formas irregulares
Silhouette Analysis: Evaluación automática del número óptimo de clusters
t-SNE/UMAP: Visualización de embeddings en 2D

API endpoints (ml-embeddings)

POST /embed           # Generar embeddings para imagen
POST /cluster         # Ejecutar clustering en conjunto de imágenes
POST /find-similar    # Encontrar documentos similares
GET  /cluster-stats   # Estadísticas de clustering

Flujo de descubrimiento de clases

# 1. Generar embeddings para todas las imágenes
embeddings = []
for image in image_dataset:
    response = requests.post('/embed', files={'file': image})
    embeddings.append(response.json()['embedding'])

# 2. Ejecutar clustering automático
cluster_response = requests.post('/cluster', json={
    'embeddings': embeddings,
    'method': 'kmeans',
    'auto_k': True
})

# 3. Obtener clases descubiertas
discovered_classes = cluster_response.json()['clusters']

🎯 Fase 3-4: Entrenamiento y Clasificación

`ml-classifier` (Puerto 8003)

Responsabilidad: Entrenamiento de modelos supervisados y clasificación de tipos de documentos.

Tecnologías utilizadas (ml-classifier)

PyTorch Lightning: Framework para entrenamiento escalable
EfficientNet: Arquitectura de CNN optimizada para clasificación
ResNet/VGG: Arquitecturas clásicas para transfer learning
Optuna: Optimización automática de hiperparámetros
MLflow: Tracking de experimentos y gestión de modelos

Capacidades del modelo

Transfer Learning: Fine-tuning de modelos pre-entrenados en ImageNet
Data Augmentation: Aumento automático de datos de entrenamiento
Early Stopping: Prevención de overfitting con validación automática
Model Ensembling: Combinación de múltiples modelos para mejor accuracy
Quantization: Optimización de modelos para inferencia rápida

API endpoints (ml-classifier)

POST /train           # Entrenar nuevo modelo
POST /classify        # Clasificar imagen con modelo entrenado
POST /evaluate        # Evaluar rendimiento del modelo
GET  /models          # Listar modelos disponibles
POST /optimize        # Optimización automática de hiperparámetros

Proceso de entrenamiento

# Configuración de entrenamiento
training_config = {
    'model_architecture': 'efficientnet-b3',
    'batch_size': 32,
    'learning_rate': 0.001,
    'epochs': 50,
    'data_augmentation': True,
    'early_stopping': True
}

# Iniciar entrenamiento
response = requests.post('/train', json={
    'config': training_config,
    'dataset_path': '/data/training',
    'validation_split': 0.2
})

# Monitorear progreso
training_id = response.json()['training_id']
status = requests.get(f'/train/status/{training_id}')

📄 Fase 5-6: Extracción (IDP) con OCR

`ocr-extractor` (Puerto 8004)

Responsabilidad: Extracción IDP con OCR especializado por tipo de documento y normalización a JSON con scores de confianza.

Tecnologías utilizadas (ocr-extractor)

PaddleOCR 3.0: Motor OCR multi-idioma de última generación
Tesseract: OCR tradicional para casos específicos
spaCy: Procesamiento de lenguaje natural para extracción de entidades
regex: Patrones avanzados para extracción de datos específicos
pydantic: Validación de esquemas JSON extraídos

Configuraciones OCR especializadas

# Configuración por tipo de documento
ocr_configs = {
    'cedula': {
        'lang': 'es',
        'psm': 6,  # Uniform text block
        'dpi': 300,
        'preprocessing': ['denoise', 'sharpen']
    },
    'factura': {
        'lang': 'es+en',
        'psm': 4,  # Single column text
        'table_detection': True,
        'line_detection': True
    },
    'formulario': {
        'lang': 'es',
        'psm': 12,  # Sparse text
        'field_detection': True,
        'checkbox_detection': True
    }
}

API endpoints (ocr-extractor)

POST /extract         # OCR + extracción básica
POST /extract-json    # OCR + extracción estructurada a JSON
POST /configure-ocr   # Configurar OCR para tipo específico
GET  /supported-types # Tipos de documentos soportados

Ejemplo de extracción especializada

# Procesar cédula de identidad
files = {'file': open('cedula.jpg', 'rb')}
response = requests.post('/extract-json', 
    files=files,
    data={'document_type': 'cedula'}
)

# Resultado estructurado
extracted_data = {
    'tipo_documento': 'cedula',
    'numero_cedula': '12345678',
    'nombre_completo': 'Juan Pérez García',
    'fecha_nacimiento': '1990-05-15',
    'lugar_nacimiento': 'Madrid, España',
    'fecha_expedicion': '2020-01-10',
    'fecha_vencimiento': '2030-01-10',
    'confidence_scores': {
        'numero_cedula': 0.98,
        'nombre_completo': 0.95,
        'fecha_nacimiento': 0.92
    }
}

🔄 Comunicación Entre Servicios

Protocolo de Comunicación

HTTP REST: Comunicación síncrona entre servicios
JSON: Formato estándar para intercambio de datos
Request IDs: Trazabilidad completa de requests a través del pipeline
Health Checks: Monitoreo automático del estado de servicios
Circuit Breaker: Protección contra cascadas de fallos

Manejo de Datos

# Estructura estándar de respuesta
{
    "success": True,
    "data": {...},
    "processing_time": 1.25,
    "request_id": "req_123456",
    "service_version": "1.0.0",
    "timestamp": "2025-09-17T14:30:00Z"
}

# Manejo de errores
{
    "success": False,
    "error": {
        "code": "INVALID_IMAGE_FORMAT",
        "message": "Formato de imagen no soportado",
        "details": "Solo se aceptan formatos JPG, PNG, TIFF"
    },
    "request_id": "req_123456"
}

Optimizaciones de Rendimiento

Instancias Cacheadas: Modelos ML se cargan una vez y se reutilizan
Procesamiento Asíncrono: Tareas pesadas en background workers
Compresión de Respuestas: Gzip automático para reducir latencia
Connection Pooling: Reutilización de conexiones HTTP
GPU Sharing: Compartición eficiente de recursos GPU entre servicios

📊 Monitoreo y Observabilidad

Métricas por Servicio

Throughput: Imágenes procesadas por minuto
Latency: Tiempo de respuesta promedio por fase
Error Rate: Porcentaje de fallos por tipo de error
Resource Usage: CPU, memoria, GPU por servicio
Model Accuracy: Precisión de modelos ML en tiempo real

Dashboards Disponibles

Pipeline Overview: Estado general del pipeline completo
Phase Performance: Métricas detalladas por fase
Model Monitoring: Rendimiento de modelos ML
Error Tracking: Análisis de errores y fallos

🚀 Escalabilidad y Deployment

Estrategias de Escalado

Horizontal Scaling: Múltiples instancias por servicio
Load Balancing: Distribución inteligente de carga
Auto-scaling: Escalado automático basado en métricas
GPU Scheduling: Asignación eficiente de recursos GPU

Configuración Docker

# docker-compose.yml para microservicios
services:
  image-processor:
    image: iris/image-processor:latest
    ports: ["8001:8001"]
    environment:
      - OPENCV_THREADS=4
      - MAX_IMAGE_SIZE=10MB
    
  ml-embeddings:
    image: iris/ml-embeddings:latest
    ports: ["8002:8002"]
    environment:
      - MODEL_CACHE_SIZE=2GB
      - BATCH_SIZE=16
    deploy:
      resources:
        reservations:
          devices: [{"capabilities": ["gpu"]}]

📚 Próximos Pasos

Explora la documentación detallada de cada fase:

Fase 1: Preprocesamiento: Corrección geométrica y preparación de imágenes
Fase 2: Embeddings: Generación de vectores y clustering automático
Fase 3-4: Clasificación: Entrenamiento y clasificación supervisada
Fase 5-6: OCR: OCR especializado y extracción JSON

¿Necesitas ayuda con algún microservicio específico? Consulta las guías detalladas de cada fase o revisa los ejemplos de integración.

🏗️ Arquitectura de Microservicios​

Filosofía de Diseño​

Mapa de Servicios​

🔬 Fase 1: Preprocesamiento de Imágenes​

image-processor (Puerto 8001)​

Tecnologías utilizadas (image-processor)​

Funciones principales​

API endpoints (image-processor)​

Ejemplo de uso​

🧠 Fase 2: Embeddings y Clustering​

ml-embeddings (Puerto 8002)​

Tecnologías utilizadas (ml-embeddings)​

Algoritmos implementados​

API endpoints (ml-embeddings)​

Flujo de descubrimiento de clases​

🎯 Fase 3-4: Entrenamiento y Clasificación​

ml-classifier (Puerto 8003)​

Tecnologías utilizadas (ml-classifier)​

Capacidades del modelo​

API endpoints (ml-classifier)​

Proceso de entrenamiento​

📄 Fase 5-6: Extracción (IDP) con OCR​

ocr-extractor (Puerto 8004)​

Tecnologías utilizadas (ocr-extractor)​

Configuraciones OCR especializadas​

API endpoints (ocr-extractor)​

Ejemplo de extracción especializada​

🔄 Comunicación Entre Servicios​

Protocolo de Comunicación​

Manejo de Datos​

Optimizaciones de Rendimiento​

📊 Monitoreo y Observabilidad​

Métricas por Servicio​

Dashboards Disponibles​

🚀 Escalabilidad y Deployment​

Estrategias de Escalado​

Configuración Docker​

📚 Próximos Pasos​