ml-adoption-playbook

Playbook de Adopción de ML

Esta habilidad proporciona una metodología adaptable para implementar modelos de aprendizaje automático en proyectos de ingeniería de software existentes. Cierra la brecha entre la ingeniería de software tradicional y MLOps, estructurando cómo investigar, separar, entrenar e integrar ML.

Cuándo activar

• Un usuario pide "añadir ML" o "añadir un algoritmo" a su base de código existente.
• Planificación de la integración de un nuevo modelo (por ejemplo, recomendación, clasificación, predicción) en una aplicación sin ML.
• Estructuración de un flujo de trabajo para que un agente construya, entrene e implemente un componente ML de forma adaptativa.

Fase 1: Planteamiento del problema y viabilidad

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

• Verificación heurística: Pregunte al usuario si una heurística simple (por ejemplo, regex, ordenación basada en reglas) podría resolver el problema más rápido. Si es así, comience ahí.
• Definición de métrica: Defina qué métrica de negocio intenta mejorar el modelo ML (por ejemplo, tasa de clics, latencia reducida).
• Presupuesto de error: Defina qué aspecto tiene una predicción "mala" y cómo debe manejarla el sistema.

Fase 2: Preparación de datos

ML es inútil sin datos limpios y accesibles.

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

Fase 3: Integración arquitectónica y desacoplamiento

No acople estrechamente la inferencia del modelo con la lógica central del negocio.

• Límite API: Sugiera colocar el modelo detrás de un endpoint API (por ejemplo, usando fastapi-patterns o django-patterns) o una clase de servicio dedicada.
• Mecanismos de retroceso: Diseñe un estado predeterminado. Si el modelo tarda demasiado en responder o lanza un error, el sistema debe retroceder de forma segura a una regla codificada.
• Feature Flags: Envuelva la nueva llamada de inferencia ML en un feature flag para que pueda implementarse (o revertirse) de forma segura.

Fase 4: Implementación y entrenamiento del modelo

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

• Comience de forma simple: Construya primero un modelo base (por ejemplo, una Regresión Logística simple de scikit-learn o una capa lineal básica de PyTorch).
• Reproducibilidad: Aplique pytorch-patterns o buenas prácticas similares: fije las semillas aleatorias, haga el código independiente del dispositivo y documente explícitamente las formas de los tensores/arrays.
• Evidencia automatizada: Exija tests para las transformaciones de datos y el esquema de inferencia. No acepte un modelo sin un script de evaluación que lo compare con la línea base.

Fase 5: Entrega a MLOps

Una vez que el modelo base está integrado, enfoque en las operaciones continuas.

• Consulte mle-workflow: Guíe al usuario hacia la configuración de seguimiento de experimentos, registros de modelos y detección de deriva.
• CI/CD: Agregue el paso de evaluación del modelo al pipeline de CI existente para garantizar que las futuras confirmaciones no degraden el rendimiento del modelo.

Flujo de trabajo iterativo del agente

Al asistir a un usuario a través de este playbook, 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.