LogoIngeniería de Software Estadístico
Buscar

Getting Started

Flujo completo: desde cero hasta API y dashboard en ~30 minutos

Esta guía recorre el ciclo completo de ingeniería de software estadístico con un ejemplo práctico y ejecutable.

¿Qué valor tiene este ejemplo?

Este ejemplo mínimo sienta las bases para proyectos reales: desde la validación de datos hasta el despliegue. Una vez interiorizado, podrás escalarlo a modelos más complejos (bayesianos, deep learning) y añadir monitoreo, reentrenamiento automático o feature stores.

Producto Final

Un sistema completo de ingeniería de software estadístico que resuelve un problema real: predecir una variable continua (y) a partir de dos características (x1, x2) usando un modelo de regresión lineal. Aunque el problema es simple, el valor real está en la infraestructura que lo rodea:

  • Reproducibilidad: todo el entorno, dependencias y datos se versionan (Poetry, DVC opcional).

  • Validación de datos: se verifica calidad y esquema antes de entrenar (sin datos “sucios”).

  • Experiment tracking: cada ejecución queda registrada en MLflow (parámetros, métricas, modelo).

  • Model registry: se promueve automáticamente la mejor versión con el alias champion.

  • API productiva: se expone el modelo como servicio REST con FastAPI, listo para integrarse a cualquier aplicación.

  • Dashboard interactivo: un frontend en Next.js consume la API y permite visualizar predicciones y la curva del modelo.

  • Despliegue listo para producción: con Docker Compose se empaquetan todos los servicios (API, frontend, MLflow).

Utilidad para tu aprendizaje

Al completar esta guía, habrás adquirido competencias directamente transferibles a entornos profesionales:

  • Estructurar un proyecto estadístico siguiendo una arquitectura en capas (core, servicios, interfaces).

  • Automatizar la validación de datos con scripts simples (pandas) evitando bibliotecas pesadas al inicio.

  • Gestionar experimentos y modelos con MLflow (tracking, registry, aliases).

  • Crear una API documentada y robusta con FastAPI, cargando el modelo champion desde MLflow.

  • Construir un dashboard interactivo en Next.js/TypeScript que consuma la API y muestre predicciones en tiempo real.

  • Orquestar múltiples servicios con Docker para un despliegue consistente en cualquier entorno.

Utilidad específica de cada paso

Paso 0 – Estructura del proyecto

Utilidad: Aprender a organizar el código por capas, separando la lógica de negocio (services), la presentación (interfaces/api) y los contratos (contracts). Esta estructura facilita el mantenimiento y el testing.

Paso 1 – Dataset y validación

Utilidad: Comprender la necesidad de datos deterministas (semilla fija) y la validación temprana. El script train_contract.py evita que datos corruptos lleguen al entrenamiento, un hábito esencial en MLOps.

Paso 2 – Versionado con DVC (opcional)

Utilidad: Ver cómo se vincula el código con los datos. Si más adelante cambias el dataset, DVC permite volver a cualquier versión anterior y reproducir el modelo exacto.

Paso 3 – Entrenamiento y MLflow

Utilidad: Registrar cada ejecución (parámetros, métricas, artefactos) y asignar un alias (champion) para saber qué modelo está en producción. En un equipo, esto elimina la confusión de “¿cuál es el último modelo bueno?”.

Paso 4 – API FastAPI

Utilidad: Pasar del modelo local a un servicio accesible por HTTP. Se aprende a cargar el modelo champion desde el registry y exponer endpoints con documentación automática (Swagger).

Paso 5 – Dashboard con Next.js

Utilidad: Conectar una interfaz de usuario real al modelo. Además, el botón “Generar curva desde API” demuestra cómo se puede explorar el comportamiento del modelo de forma interactiva, consultando la API en tiempo real.

Paso 6 – Docker Compose

Utilidad: Preparar el sistema para producción. Levantar todos los servicios (API, frontend, MLflow) con un solo comando garantiza que el entorno de desarrollo refleje el de producción.

Prerrequisitos

  • Python 3.11 o superior
  • Poetry (gestor de dependencias)
  • Git (opcional, pero recomendado)
  • Docker y Docker Compose (opcional, para el despliegue completo)
  • Node.js 18+ y npm (para el dashboard)

Paso 0: Estructura del proyecto

Crea el directorio del proyecto y la estructura de carpetas:

bash

Añade las dependencias principales y de desarrollo:

bash

La estructura resultante será:

text

Paso 1: Dataset sintético y contrato de datos

1.1 Generar datos sintéticos

Crea el archivo data/generate_data.py:

python

Ejecuta:

bash

1.2 Validación de datos con pandas

Crea contracts/train_contract.py con validaciones simples pero efectivas:

python

Ejecuta:

bash

Paso 2: Versionado de datos con DVC (opcional)

Si deseas versionar los datos junto con el código, instala DVC y configúralo:

bash

Paso 3: Entrenamiento y registro en MLflow

3.1 Iniciar el servidor de MLflow

Abre una terminal (o una pestaña nueva) y ejecuta:

bash

3.2 Script de entrenamiento

Crea services/train_model.py:

python

Ejecuta el entrenamiento (en la terminal original, sin cerrar el servidor de MLflow):

bash

Paso 4: API REST con FastAPI

Crea el archivo interfaces/api/main.py:

python

Levanta la API:

bash

Prueba el endpoint desde otra terminal:

bash

Ejemplo de respuesta:

json

Paso 5: Dashboard con Next.js y Recharts

5.1 Crear el proyecto Next.js

Abre una nueva terminal (sin cerrar las anteriores) y ejecuta:

bash

5.2 Código del dashboard

Reemplaza el contenido de dashboard/app/page.tsx con:

tsx

5.3 Ejecutar el dashboard

bash

Abre http://localhost:3000 en tu navegador. Deberías ver:

  • Un formulario para ingresar x1 y x2 y obtener la predicción real desde la API.
  • La curva de sensibilidad generada automáticamente al cargar la página consultando el endpoint /predict para un rango de valores.
  • Un botón "Regenerar curva desde API" para actualizar el gráfico manualmente.

Paso 6: Despliegue con Docker Compose (opcional)

Para ejecutar todo el sistema con un solo comando, añade los siguientes archivos.

6.1 Dockerfile para la API

Crea Dockerfile en la raíz del proyecto:

dockerfile

6.2 Dockerfile para el dashboard

Crea dashboard/Dockerfile:

dockerfile

6.3 Archivo docker-compose.yml

En la raíz del proyecto (junto al Dockerfile de la API), crea docker-compose.yml:

yaml

Levanta todos los servicios:

bash

Accede a:

Resumen de Comandos (sin Docker)

bash

Próximos Pasos

Notas Finales

Si encuentras errores de conexión entre el dashboard y la API, verifica que el puerto 8000 esté accesible (en Docker, usa http://api:8000). En desarrollo local, http://127.0.0.1:8000 funciona.

El dataset sintético garantiza resultados deterministas con la semilla fija.

Para reproducir el mismo entrenamiento desde cero, el alias champion siempre apunta a la última versión registrada.

¡Has completado el ciclo completo!