ML Model Monitoring Framework

Descripción

Framework de monitoreo de modelos de Machine Learning en producción para detección de data drift, model drift y degradación de performance. El proyecto implementa un sistema completo de vigilancia que incluye tests estadísticos (Kolmogorov-Smirnov, PSI, Jensen-Shannon), monitoreo de métricas de clasificación, sistema de alertas multinivel y generación de reportes automatizados.

Contexto de negocio: Los modelos de ML desplegados en producción se degradan con el tiempo debido a cambios en los datos y en los patrones de comportamiento de los clientes. Este framework permite detectar proactivamente cuándo un modelo necesita ser reentrenado, evitando decisiones basadas en predicciones obsoletas.

Resultados Principales

Monitoreo de 12 meses de producción con drift gradual simulado:

Período	ROC-AUC	Features con Drift	Nivel de Alerta
Feb-May 2025	0.60-0.63	0-1 / 7	WARNING
Jun-Sep 2025	0.56-0.62	0-3 / 7	WARNING-CRITICAL
Oct 2025-Ene 2026	0.57-0.65	5-7 / 7	CRITICAL

Hallazgos Clave

• El drift se intensifica a partir del mes 6 de producción
• Las features más afectadas: num_support_tickets, monthly_charges, total_data_gb
• El ROC-AUC cae de 0.946 (baseline) a 0.570-0.652 en los últimos meses
• Se generaron 21 alertas en total (12 CRITICAL, 9 WARNING)
• Se recomienda reentrenamiento cuando PSI > 0.2 en más del 50% de features

Estructura del Proyecto

ml-model-monitoring/
├── data/
│   ├── baseline_data.csv              # Datos de entrenamiento (5,000 registros)
│   └── production_data.csv            # Datos de producción (6,178 registros)
├── notebooks/
│   └── 01_model_monitoring_framework.py # Framework completo
├── src/
│   └── monitor_config.json            # Configuración del monitor
├── figures/
│   ├── 01_performance_dashboard.png   # Dashboard de métricas
│   ├── 02_drift_heatmap.png          # Heatmap PSI por feature/mes
│   ├── 03_distribution_comparison.png # Baseline vs producción
│   ├── 04_calibration_metrics.png     # Log Loss y Brier Score
│   ├── 05_alert_timeline.png         # Timeline de alertas
│   └── 06_monthly_summary.png        # Resumen mensual
├── reports/
│   ├── monitoring_summary.csv         # Resumen tabular
│   └── monitoring_report.txt          # Reporte detallado
├── requirements.txt
├── LICENSE
└── README.md

Visualizaciones

Dashboard de Performance

Heatmap de Data Drift (PSI)

Distribuciones: Baseline vs Producción

Timeline de Alertas

Resumen Mensual

Metodología

Componentes del Framework

1. ProductionDataSimulator: Genera datos de producción con drift gradual controlado para testing del framework.

2. ModelMonitor: Clase principal que implementa:

   • Data Drift Detection: Test de Kolmogorov-Smirnov, Population Stability Index (PSI), Jensen-Shannon Divergence
   • Prediction Drift Detection: Monitoreo de distribución de predicciones y probabilidades
   • Performance Monitoring: Tracking de ROC-AUC, F1-Score, Log Loss, Brier Score
   • Alert System: Alertas multinivel (OK, WARNING, CRITICAL) basadas en umbrales configurables

Métricas de Drift

Métrica	Descripción	Umbral Warning	Umbral Critical
KS Test	Test de Kolmogorov-Smirnov	p < 0.05	p < 0.01
PSI	Population Stability Index	> 0.10	> 0.25
JS Divergence	Jensen-Shannon Divergence	> 0.05	> 0.15
AUC Drop	Caída respecto al baseline	> 0.02	> 0.05

Pipeline de Monitoreo

Datos de Producción → Preprocesamiento → Data Drift Detection
                                        → Model Prediction
                                        → Performance Metrics
                                        → Alert Generation
                                        → Report Generation

Tecnologías Utilizadas

• Python 3.11 — Lenguaje principal
• scikit-learn — Modelo base y métricas
• SciPy — Tests estadísticos (KS test, Jensen-Shannon)
• pandas / NumPy — Manipulación de datos
• matplotlib / seaborn — Visualización y dashboards

Instalación y Uso

# Clonar repositorio
git clone https://github.com/<tu-usuario>/ml-model-monitoring.git
cd ml-model-monitoring

# Instalar dependencias
pip install -r requirements.txt

# Ejecutar framework completo
python notebooks/01_model_monitoring_framework.py

Uso como Librería

from model_monitor import ModelMonitor

# Inicializar monitor
monitor = ModelMonitor(
    model=trained_model,
    scaler=fitted_scaler,
    features=feature_list,
    baseline_data=training_data,
    baseline_metrics=baseline_metrics
)

# Monitorear un batch de producción
result = monitor.monitor_batch(
    batch_data=new_data,
    batch_labels=true_labels,  # opcional
    date=datetime.now()
)

# Obtener resumen
summary = monitor.get_monitoring_summary()

Recomendaciones de Implementación

1. Frecuencia de monitoreo: Diaria para métricas de predicción, semanal para drift estadístico
2. Reentrenamiento: Automático cuando PSI > 0.2 en más del 50% de features
3. Alertas: Integrar con Slack/Teams/Email para notificaciones en tiempo real
4. Logging: Almacenar logs de monitoreo en base de datos para análisis histórico
5. A/B Testing: Comparar modelo actual vs reentrenado antes de reemplazar

Licencia

Este proyecto está bajo la Licencia MIT. Ver LICENSE para más detalles.