ml-adoption-playbook

Manual de adopción de ML

Esta habilidad proporciona una metodología adaptativa para implementar modelos de machine learning en proyectos de ingeniería de software existentes. Tiende un puente entre la ingeniería de software tradicional y MLOps, estructurando la forma en que el ML debe ser investigado, desacoplado, entrenado e integrado.

Cuándo activarlo

• Un usuario solicita "agregar ML" o "agregar un algoritmo" a su base de código existente.
• Se está planificando la integración de un nuevo modelo (p. ej., recomendación, clasificación, predicción) en una aplicación no basada en ML.
• Se necesita estructurar un flujo de trabajo para que un agente construya, entrene y despliegue un componente de ML de manera adaptativa.

Fase 1: Definición del problema y viabilidad

Antes de escribir código de modelo, establece el "por qué" y el "cómo".

• Comprobación heurística: Pregunta al usuario si una heurística simple (p. ej., expresiones regulares, ordenamiento basado en reglas) podría resolver el problema más rápido. De ser así, comienza por ahí.
• Definición de métrica: Define qué métrica de negocio se busca mejorar con el modelo de ML (p. ej., tasa de clics, reducción de latencia).
• Presupuesto de error: Define cómo se ve una predicción "mala" y cómo debe manejarla el sistema.

Fase 2: Preparación de datos

El ML es inútil sin datos limpios y accesibles.

• Auditar fuentes de datos: Identifica dónde residen los datos de entrenamiento. ¿Son una base de datos en vivo, un CSV estático o una API?
• Contrato de datos: Establece un esquema para los datos de entrada. ¿Qué características se requieren? ¿Qué sucede si falta alguna?
• Prevención de fugas: Asegúrate de que la división de datos propuesta no filtre accidentalmente información futura en el conjunto de entrenamiento (p. ej., división cronológica para datos de series temporales).

Fase 3: Integración arquitectónica y desacoplamiento

No acoples fuertemente la inferencia del modelo con la lógica central del negocio.

• Límite de API: Sugiere colocar el modelo detrás de un endpoint de API (p. ej., usando patrones de fastapi-patterns o django-patterns) o una clase de servicio dedicada.
• Mecanismos de fallback: Diseña un estado predeterminado. Si el modelo tarda demasiado en responder o arroja un error, el sistema debe recurrir de forma segura a una regla fija.
• Feature flags: Envuelve la nueva llamada de inferencia de ML en un feature flag para poder desplegarla (o revertirla) de manera segura.

Fase 4: Implementación y entrenamiento del modelo

Estructura el código para la reproducibilidad y la iteración.

• Empieza simple: Construye primero un modelo base (p. ej., una regresión logística simple con scikit-learn o una capa lineal básica con PyTorch).
• Reproducibilidad: Aplica patrones de pytorch-patterns o similares: fija las semillas aleatorias, haz el código independiente del dispositivo y documenta explícitamente las formas de tensores/arrays.
• Evidencia automatizada: Exige pruebas para las transformaciones de datos y el esquema de inferencia. No aceptes un modelo sin un script de evaluación que lo compare con la línea base.

Fase 5: Transición a MLOps

Una vez integrado el modelo base, enfócate en las operaciones continuas.

• Consultar mle-workflow: Guía al usuario hacia la configuración de seguimiento de experimentos, registros de modelos y detección de deriva.
• CI/CD: Agrega el paso de evaluación del modelo al pipeline de CI existente para garantizar que los commits futuros no degraden el rendimiento del modelo.

Flujo de trabajo iterativo del agente

Al asistir a un usuario mediante este manual, los agentes deben:

1. Hacer preguntas aclaratorias para completar la Fase 1 antes de proponer arquitecturas.
2. Redactar un contrato de datos en la Fase 2 para la aprobación del usuario.
3. Escribir la interfaz de desacoplamiento (API/Servicio) en la Fase 3 antes de escribir el bucle de entrenamiento.
4. Entregar un script reproducible en la Fase 4 que entrene el modelo y guarde el artefacto.