Hogar

Skill

Ciencia de datos y aprendizaje automático

mle-workflow

affaan-m/ECC

Convierte el trabajo con modelos en un sistema de aprendizaje automático en producción mediante contratos de datos, entrenamiento repetible, controles de calidad cuantificables, artefactos implementables y supervisión operativa.

...Expandir todo

Tiempo actualizado 1 de octubre de 2026

# monitoring # deployment # evaluation # model training # data contracts # machine learning engineering # mlops

Flujo de trabajo de ingeniería de aprendizaje automático

Utiliza esta competencia para convertir el trabajo con modelos en un sistema de aprendizaje automático en producción con contratos de datos claros, entrenamiento repetible, controles de calidad medibles, artefactos implementables y supervisión operativa.

Cuándo activarla

Al planificar o revisar una función de aprendizaje automático en producción, una actualización de modelo, un sistema de clasificación, un sistema de recomendación, un clasificador, un flujo de trabajo de incrustación o un proceso de predicción
Al convertir el código de un cuaderno en un proceso reutilizable de entrenamiento, evaluación, inferencia por lotes o inferencia en línea
Diseño de criterios de promoción de modelos, evaluaciones offline/online, seguimiento de experimentos o rutas de reversión
Depuración de fallos causados por la deriva de datos, la fuga de etiquetas, características obsoletas, la incompatibilidad de artefactos o la lógica inconsistente de entrenamiento y servicio
Añadir supervisión de modelos, implementaciones «canario», tráfico de prueba o comprobaciones de calidad tras la implementación

Calibración del alcance

Utiliza únicamente las vías que se adapten al sistema que tengas delante. Esta habilidad resulta útil para la clasificación, la búsqueda, las recomendaciones, los clasificadores, las previsiones, las incrustaciones, los flujos de trabajo de LLM, la detección de anomalías y el análisis por lotes, pero no debe imponer una única arquitectura para todos ellos.

No des por sentado que todos los modelos cuentan con etiquetas supervisadas, servicio en línea, un almacén de características, PyTorch, GPU, revisión humana, pruebas A/B o retroalimentación en tiempo real.
No añadas maquinaria MLOps pesada cuando un contrato de datos, una línea de base, un script de evaluación y una nota de reversión permitan revisar el cambio.
Haz explícitas las suposiciones cuando el proyecto carezca de etiquetas, resultados retrasados, definiciones de segmentos, tráfico de producción o responsabilidad en la supervisión.
Trata los ejemplos como andamios intercambiables. Sustituye las métricas, el modo de servicio, los almacenes de datos y los mecanismos de implementación por los equivalentes propios del proyecto.

Habilidades relacionadas

python-patterns y python-testing para la implementación en Python y la cobertura con pytest
pytorch-patterns para modelos de aprendizaje profundo, cargadores de datos, gestión de dispositivos y bucles de entrenamiento
eval-harness y ai-regression-testing para puertas de promoción y comprobaciones de regresión asistidas por agentes
database-migrations, postgres-patterns, y clickhouse-io para el almacenamiento de datos y las interfaces de análisis
deployment-patterns, docker-patterns, y security-review para servicios, secretos, contenedores y refuerzo de la seguridad en producción

Reutiliza la superficie de ingeniería de software (SWE)

No trates el aprendizaje automático (MLE) como algo separado de la ingeniería de software. La mayoría de los flujos de trabajo de ingeniería de software (SWE) del ECC se aplican directamente a los sistemas de aprendizaje automático, a menudo con modos de fallo más estrictos:

La instalación recomendada minimal --with capability:machine-learning mantiene disponible la superficie del agente principal junto con esta habilidad. Para entornos de prueba que solo incluyen la habilidad o con acceso limitado al agente, combina skill:mle-workflow con agent:mle-reviewer allí donde el destino admita agentes.

Superficie de SWE	Uso de MLE
`product-capability` / `architecture-decision-records`	Convierte el trabajo de modelado en contratos de producto explícitos y registra decisiones irreversibles sobre datos, modelos y despliegues
`repo-scan` / `codebase-onboarding` / `code-tour`	Identifica las rutas existentes de entrenamiento, características, puesta en producción, evaluación y supervisión antes de introducir una pila de aprendizaje automático paralela
`plan` / `feature-dev`	Definir el alcance de los cambios en los modelos como capacidades del producto, con fases de datos, evaluación, puesta en servicio y reversión
`tdd-workflow` / `python-testing`	Prueba las transformaciones de características, la lógica de segmentación, los cálculos de métricas, la carga de artefactos y los esquemas de inferencia antes de la implementación
`code-reviewer` / `mle-reviewer`	Revisa la calidad del código, así como los riesgos específicos del aprendizaje automático relacionados con fugas, reproducibilidad, promoción y supervisión
`build-fix` / `pr-test-analyzer`	Diagnosticar fallos en la integración continua (CI), evaluaciones inestables, elementos de prueba que faltan y fallos de modelos o dependencias específicos del entorno
`quality-gate` / `test-coverage`	Exige pruebas automatizadas para las transformaciones, las métricas, los contratos de inferencia, los controles de promoción y el comportamiento de reversión
`eval-harness` / `verification-loop`	Convertir las métricas fuera de línea, las comprobaciones de segmentos, los presupuestos de latencia y los simulacros de reversión en puertas de control repetibles
`ai-regression-testing`	Conserva cada error de producción como una regresión: característica ausente, etiqueta obsoleta, artefacto defectuoso, desviación del esquema o discrepancia en el servicio
`api-design` / `backend-patterns`	Diseña API de predicción, trabajos por lotes, puntos finales de reentrenamiento idempotentes y envolventes de respuesta
`database-migrations` / `postgres-patterns` / `clickhouse-io`	Etiquetas de versión, instantáneas de características, registros de predicción, métricas de experimentos y análisis de desviaciones
`deployment-patterns` / `docker-patterns`	Empaqueta imágenes reproducibles de entrenamiento y servicio con comprobaciones de estado, límites de recursos y reversión
`canary-watch` / `dashboard-builder`	Haz visible el estado de la implementación mediante paneles de control de versión del modelo, segmentos, desviaciones, latencia, costes y etiquetas retrasadas
`security-review` / `security-scan`	Comprueba los artefactos del modelo, los cuadernos, las indicaciones, los conjuntos de datos y los registros en busca de secretos, información de carácter personal (PII), deserialización insegura y riesgos en la cadena de suministro
`e2e-testing` / `browser-qa` / `accessibility`	Prueba los flujos críticos del producto que consumen predicciones, incluyendo la explicabilidad y los estados de la interfaz de usuario de reserva
`benchmark` / `performance-optimizer`	Mide el rendimiento, la latencia p95, la memoria, la utilización de la GPU y el coste por predicción o reentrenamiento
`cost-aware-llm-pipeline` / `token-budget-advisor`	Dirige las cargas de trabajo de LLM/incrustación en función de la calidad, la latencia y el presupuesto, en lugar de recurrir por defecto al modelo más grande
`documentation-lookup` / `search-first`	Verifica el comportamiento actual de las bibliotecas para el servicio de modelos, los almacenes de características, las bases de datos vectoriales y las herramientas de evaluación antes de programar
`git-workflow` / `github-ops` / `opensource-pipeline`	Empaquetar los cambios de MLE para su revisión con un alcance claro, excluyendo los artefactos generados y incluyendo pruebas reproducibles
`strategic-compact` / `dmux-workflows`	Dividir el trabajo prolongado de aprendizaje automático en vías paralelas: contrato de datos, entorno de evaluación, ruta de servicio, supervisión y documentación

Diez simulaciones de tareas de MLE

Utiliza estas simulaciones como comprobaciones de cobertura al planificar o revisar el trabajo de MLE. Un flujo de trabajo de MLE sólido debe reducir cada tarea a contratos explícitos, interfaces de ingeniería de software (SWE) reutilizables, evidencia automatizada y un artefacto revisable.

ID	Tarea común de MLE	Ruta ECC optimizada	Resultado requerido	Vías del proceso cubiertas
MLE-01	Definir una capacidad ambigua de predicción, clasificación, recomendación, clasificación, incrustación o previsión	`product-capability`, `plan`, `architecture-decision-records`, `mle-workflow`	Iteración: definir de forma concisa a quién le importa, quién es el responsable de la decisión, la métrica de éxito, los errores inaceptables, los supuestos, las restricciones y el primer experimento	contrato de producto, pérdidas para las partes interesadas, riesgo, implementación
MLE-02	Definir los objetivos métricos, las etiquetas, las fuentes de datos y el margen de error	`repo-scan`, `database-reviewer`, `database-migrations`, `postgres-patterns`, `clickhouse-io`	Contrato de datos y métricas con nivel de detalle de las entidades, sincronización de las etiquetas, confianza de las etiquetas, sincronización de las características, uniones en un momento determinado, política de división e instantánea del conjunto de datos	Contrato de datos, diseño de métricas, fugas, reproducibilidad
MLE-03	Crear un modelo de referencia y una ruta de puntuación antes de añadir complejidad	`tdd-workflow`, `python-testing`, `python-patterns`, `code-reviewer`	Modelador de referencia con matriz de confusión, notas de calibración, estimación de latencia/coste, debilidades conocidas y pruebas de la forma de la puntuación y el determinismo	referencia, puntuación, pruebas, paridad de servicio
MLE-04	Generar características a partir de hipótesis sobre qué diferencia los resultados	`python-patterns`, `pytorch-patterns`, `docker-patterns`, `deployment-patterns`	Plan de características y módulo de transformación que abarca la fuente de la señal, los valores perdidos, los valores atípicos, las correlaciones, las comprobaciones de fugas y la equivalencia entre entrenamiento y servicio	flujo de trabajo de características, fugas, entrenamiento, artefactos
MLE-05	Ajustar umbrales, configuraciones y complejidad del modelo teniendo en cuenta las compensaciones	`eval-harness`, `ai-regression-testing`, `quality-gate`, `test-coverage`	Informe de umbrales y configuraciones que compara precisión, recuperación, F1, AUC, calibración, segmentos de grupo, latencia, coste, complejidad y clases de error aceptables	evaluación, umbral, promoción, regresión
MLE-06	Realizar análisis de errores y convertir los fallos en el siguiente experimento	`eval-harness`, `ai-regression-testing`, `mle-reviewer`, `silent-failure-hunter`	Informe de agrupaciones de errores para falsos positivos, falsos negativos, etiquetas ambiguas, características obsoletas, señales ausentes y rastros de errores, con las lecciones aprendidas	análisis de errores, rastreo de errores, iteración, regresión
MLE-07	Empaquetar un artefacto de modelo para la inferencia por lotes o en línea	`api-design`, `backend-patterns`, `security-review`, `security-scan`	Paquete de artefactos versionado con preprocesamiento, configuración, restricciones de dependencias, validación de esquemas, carga segura y registros que protegen la información de carácter personal	artefacto, seguridad, contrato de inferencia
MLE-08	Implementar el servicio en línea o la evaluación por lotes con captura de retroalimentación	`api-design`, `backend-patterns`, `e2e-testing`, `browser-qa`, `accessibility`	Punto final de predicción o trabajo por lotes con envolvente de respuesta, tiempo de espera, procesamiento por lotes, solución alternativa, versión del modelo, nivel de confianza, registro de comentarios y pruebas de flujo de producto	servicio, inferencia por lotes, plan de contingencia, flujo de trabajo del usuario
MLE-09	Implementación de un modelo con tráfico de prueba, canario, prueba A/B o reversión	`canary-watch`, `dashboard-builder`, `verification-loop`, `performance-optimizer`	Nombrar el plan de implementación: división del tráfico, paneles de control, latencia p95, coste, controles de calidad, artefacto de reversión y desencadenante de reversión	implementación, canario, reversión
MLE-10	Operar, depurar y actualizar un modelo en producción tras su lanzamiento	`silent-failure-hunter`, `dashboard-builder`, `mle-reviewer`, `doc-updater`, `github-ops`	Registro de observaciones y plan de actualización con comprobaciones de desviación, estado de etiquetas diferidas, responsables de alertas, actualizaciones del manual de procedimientos, criterios de reentrenamiento y pruebas de PR	supervisión, respuesta a incidentes, reentrenamiento

Iteración compacta

Antes de modificar el código del modelo, condensa el trabajo en un único artefacto revisable. Este debe ser lo suficientemente breve como para caber en la descripción de una solicitud de incorporación de cambios (PR) y lo suficientemente preciso como para que otro ingeniero pueda cuestionar las decisiones tomadas.

Goal:
Who cares:
Decision owner:
User or system action changed by the model:
Success metric:
Guardrail metrics:
Mistake budget:
Unacceptable mistakes:
Acceptable mistakes:
Assumptions:
Constraints:
Labels and data snapshot:
Baseline:
Candidate signals:
Threshold or config plan:
Eval slices:
Known risks:
Next experiment:
Rollback or fallback:

Este resumen es el equivalente en MLE a una nota de diseño sólida de un ingeniero de software (SWE). Evita que el equipo optimice una métrica en la que nadie confía, añada funcionalidades que no aborden el modo de error real o implemente complejidad sin posibilidad de revertirla.

Cerebro de decisión

Utiliza este ciclo siempre que la tarea sea ambigua, de gran impacto o con muchas métricas:

Empieza por la decisión, no por el modelo. Identifica la acción que modifica el comportamiento posterior.
Identifica a quién le afecta y por qué. Las distintas partes interesadas asumen costes diferentes por los falsos positivos, los falsos negativos, la latencia, el gasto en computación, la opacidad o las oportunidades perdidas.
Convierte la ambigüedad en hipótesis. Pregúntate qué señal diferenciaría los resultados, qué evidencia la refutaría y qué referencia sencilla debería ser difícil de superar.
Investiga el estado de la técnica o un problema conocido similar antes de inventar un sistema a medida.
Evalúa las opciones teniendo en cuenta (probability, confidence) x (cost, severity, importance, impact).
Ten en cuenta el comportamiento adverso, los incentivos, la divulgación selectiva, el cambio de distribución y los bucles de retroalimentación.
Opta por el cambio más sencillo que reduzca el error más importante. La simplicidad no es pereza; es una forma de minimizar los errores graves sin perder velocidad de iteración.
Registra la decisión, las pruebas, los contraargumentos y el siguiente paso reversible.

Métricas y economía de los errores

Elige las métricas en función de los costes de los fallos, no por costumbre:

Utiliza una matriz de confusión desde el principio para que el equipo pueda debatir sobre falsos positivos y falsos negativos concretos, en lugar de sobre la precisión abstracta.
Da prioridad a la precisión cuando el coste de una decisión positiva incorrecta sea predominante.
Prioriza la recuperación cuando el coste de un positivo omitido sea predominante.
Utiliza el F1 solo cuando la relación entre precisión y recuperación esté realmente equilibrada y sea explicable.
Utiliza el AUC o métricas de clasificación cuando el orden de calidad sea más importante que un único umbral.
Realiza un seguimiento de la latencia, el rendimiento, la memoria y el coste como métricas de primer orden, ya que determinan la complejidad viable del modelo.
Compara con una referencia y con el modelo de producción actual antes de celebrar una mejora fuera de línea.
Trata las señales de retroalimentación del mundo real como etiquetas retrasadas con sesgos, retrasos y lagunas de cobertura; no las trates como verdad de referencia sin analizarlas.

Cada elección de métrica debe indicar qué error abarata, qué error hace más probable y quién absorbe ese coste.

Hipótesis sobre datos y características

Las características deben derivarse de una teoría de la separación:

El texto, los campos categóricos, los historiales numéricos, las relaciones gráficas, la recencia, la frecuencia y los agregados son familias de señales candidatas, no características automáticas.
Para cada familia de características, indica por qué debería separar los resultados y cómo podría filtrar información futura.
En el caso de las etiquetas ruidosas, se debe considerar la adjudicación, la confianza en las etiquetas, los objetivos flexibles o la ponderación por confianza.
En caso de desequilibrio de clases, compara la pérdida ponderada, el remuestreo, el movimiento de umbrales y las reglas de decisión calibradas.
En el caso de los valores perdidos, decide si la ausencia es informativa, si se puede imputar o si es motivo para abstenerse.
En el caso de los valores atípicos, decide si recortarlos, agruparlos, investigarlos o conservarlos como una señal poco frecuente pero importante.
En el caso de las características correlacionadas, comprueba si son redundantes, inestables o indicadores de un estado futuro no disponible.

No aumentes la complejidad del modelo hasta que el análisis de errores demuestre que el modelo de referencia falla por una razón que una señal o capacidad adicional pueda solucionar de forma plausible.

Ciclo de análisis de errores

Tras cada línea de base, sesión de entrenamiento, cambio de umbral o cambio de configuración:

Divide los errores en falsos positivos, falsos negativos, abstenciones, casos de baja confianza y fallos del sistema.
Agrupa los errores por rasgos comunes: idioma, tipo de entidad, fuente, hora, ubicación geográfica, dispositivo, dispersión, actualidad, frescura de las características, fuente de la etiqueta o versión del modelo.
Separa los errores del modelo de los fallos en los datos, la ambigüedad de las etiquetas, la ambigüedad del producto, las lagunas en la instrumentación y las discrepancias en el servicio.
Rastrear cada grupo principal hasta una de estas cuatro medidas: mejores etiquetas, mejores características, mejores umbrales o configuración, o mejor alternativa de producto.
Conserva cada error importante como prueba de regresión, segmento de evaluación, panel del dashboard o entrada en el manual de procedimientos.
Redacta la siguiente iteración como un experimento falsable, no como una vaga tarea de «mejorar el modelo».

El ciclo de MLE más sólido no es «entrenamiento → métrica → implementación». Es «error → clúster → hipótesis → experimento → evidencia → sistema más sencillo».

Registro de observaciones

Mantén un registro compacto de decisiones y pruebas junto al código, la solicitud de incorporación de cambios (PR), el informe del experimento o el manual de procedimientos:

Iteration:
Change:
Why this mattered:
Metric movement:
Slice movement:
False positives:
False negatives:
Unexpected errors:
Decision:
Tradeoff accepted:
Lesson captured:
Regression added:
Debt created:
Next iteration:

Utiliza el registro para que el trabajo del modelo sea acumulativo. El objetivo es que cada iteración facilite la siguiente decisión, no solo producir otro artefacto.

Flujo de trabajo principal

1. Define el contrato de predicción

Recopila el contrato a nivel de producto antes de escribir el código del modelo:

Objetivo de predicción y responsable de la decisión
Entidad de entrada, esquema de salida, campos de confianza/calibración y latencia permitida
Modo de servicio por lotes, en línea, en streaming o híbrido
Comportamiento de reserva cuando el modelo, el almacén de características o una dependencia no estén disponibles
Revisión humana o vía de anulación para decisiones de alto impacto
Requisitos de privacidad, retención y auditoría para entradas, predicciones y etiquetas

No aceptes «mejorar el modelo» como requisito. Vincula el modelo a un comportamiento observable del producto y a un criterio de aceptación medible.

2. Fijar el contrato de datos

Toda tarea de aprendizaje automático necesita un contrato de datos explícito:

Nivel de detalle de la entidad y clave primaria
Definición de la etiqueta, marca de tiempo de la etiqueta y retraso en la disponibilidad de la etiqueta
Marca de tiempo de la característica, SLA de actualidad y reglas de unión en un momento determinado
Política de división en entrenamiento, validación, prueba y backtest
Columnas obligatorias, valores nulos permitidos, rangos, categorías y unidades
Datos de carácter personal (PII) o campos sensibles que no deben incluirse en los artefactos de entrenamiento ni en los registros
Versión del conjunto de datos o ID de instantánea para garantizar la reproducibilidad

Prioriza la protección contra fugas de datos. Si una característica no está disponible en el momento de la predicción, o se une utilizando información futura, elimínala o trasládala a una ruta destinada exclusivamente al análisis.

3. Crear un proceso reproducible

El código de entrenamiento debe poder ser ejecutado por otro ingeniero sin que haya un estado oculto del cuaderno:

Utiliza archivos de configuración tipados o clases de datos para todos los hiperparámetros y rutas
Fija las dependencias de paquetes y modelos
Establece semillas aleatorias y documenta cualquier comportamiento no determinista de la GPU
Registra la versión del conjunto de datos, el SHA del código, el hash de la configuración, las métricas y el URI del artefacto
Guarda la lógica de preprocesamiento junto con el artefacto del modelo, no por separado en un cuaderno
Mantén las transformaciones de entrenamiento, evaluación e inferencia compartidas o generadas a partir de una misma fuente
Haz que cada paso sea idempotente para que los reintentos no corrompan los artefactos ni las métricas

Da preferencia a los valores inmutables y a las funciones de transformación puras. Evita modificar marcos de datos compartidos o la configuración global durante la generación de características.

import hashlib
from dataclasses import dataclass
from pathlib import Path


@dataclass(frozen=True)
class TrainingConfig:
    dataset_uri: str
    model_dir: Path
    seed: int
    learning_rate: float
    batch_size: int


def artifact_name(config: TrainingConfig, code_sha: str) -> str:
    config_key = f"{config.dataset_uri}:{config.seed}:{config.learning_rate}:{config.batch_size}"
    config_hash = hashlib.sha256(config_key.encode("utf-8")).hexdigest()[:12]
    return f"{code_sha[:12]}-{config_hash}"

4. Evaluar antes de la promoción

Los criterios de promoción deben declararse antes de que finalice el entrenamiento:

Comparación entre el modelo de referencia y el modelo de producción actual
Métrica principal alineada con el comportamiento del producto
Métricas de control para la latencia, la calibración, los segmentos de equidad, el coste y la concentración de errores
Métricas de segmentación para cohortes, zonas geográficas, dispositivos, idiomas o fuentes de datos importantes
Intervalos de confianza o varianza de ejecuciones repetidas cuando las métricas presentan ruido
Ejemplos de fallos revisados por una persona en el caso de modelos de alto impacto
Umbrales explícitos de «no lanzar»

PROMOTION_GATES = {
    "auc": ("min", 0.82),
    "calibration_error": ("max", 0.04),
    "p95_latency_ms": ("max", 80),
}


def assert_promotion_ready(metrics: dict[str, float]) -> None:
    missing = sorted(name for name in PROMOTION_GATES if name not in metrics)
    if missing:
        raise ValueError(f"Model promotion metrics missing required gates: {missing}")

    failures = {
        name: value
        for name, (direction, threshold) in PROMOTION_GATES.items()
        for value in [metrics[name]]
        if (direction == "min" and value < threshold)
        or (direction == "max" and value > threshold)
    }
    if failures:
        raise ValueError(f"Model failed promotion gates: {failures}")

Utiliza las métricas fuera de línea como filtros, no como garantías. Cuando el modelo modifique el comportamiento del producto, planifica una evaluación en paralelo, un lanzamiento piloto o pruebas A/B antes del lanzamiento completo.

5. Preparación para la puesta en producción

Un artefacto de aprendizaje automático solo está listo para producción cuando el contrato de servicio es comprobable:

El artefacto del modelo incluye la versión, la referencia a los datos de entrenamiento, la configuración y el preprocesamiento
El esquema de entrada rechaza características inválidas, obsoletas o fuera de rango
El esquema de salida incluye la versión del modelo y campos de confianza o explicación cuando resulten útiles
La ruta de servicio cuenta con tiempo de espera, procesamiento por lotes, límites de recursos y comportamiento de reserva
Los requisitos de CPU/GPU son explícitos y se han probado
Los registros de predicción evitan la información de carácter personal (PII) e incluyen suficientes identificadores para la depuración y las uniones de etiquetas
Las pruebas de integración abarcan características ausentes, características obsoletas, tipos incorrectos, lotes vacíos y la ruta de reserva

Nunca permitas que el código de características exclusivo del entrenamiento difiera del código de características de la puesta en producción sin una prueba que demuestre su equivalencia.

6. Poner en funcionamiento el modelo

La supervisión del modelo requiere señales tanto del sistema como de calidad:

Disponibilidad, tasa de error, tasa de tiempos de espera, profundidad de la cola y latencia p50/p95/p99
Tasa de valores nulos de las características, deriva del rango, deriva categórica y deriva de frescura
Desviación de la distribución de predicciones y desviación de la distribución de confianza
Estado de llegada de las etiquetas y métricas de calidad de los retrasos
Límites de control de los KPI empresariales y desencadenantes de reversión
Cuadros de mando por versión para implementaciones de prueba y reversiones

Cada implementación debe contar con un plan de reversión que especifique el artefacto anterior, la configuración, las dependencias de datos y el mecanismo de conmutación del tráfico.

Lista de comprobación

El contrato de predicción es explícito y comprobable
El contrato de datos define el nivel de detalle de las entidades, el momento de la etiquetado, el momento de la activación de la función y la instantánea o versión
Se han comprobado los riesgos de fuga en relación con la disponibilidad en el momento de la predicción
El entrenamiento es reproducible a partir del código, la configuración, la versión de los datos y la semilla
Las métricas se comparan con el modelo de referencia y el modelo de producción actual
Se incluyen métricas por segmentos y medidas de protección para cohortes de alto riesgo
Las puertas de promoción están automatizadas y funcionan en modo «fail closed»
Las transformaciones de entrenamiento y de servicio se comparten o se someten a pruebas de equivalencia
El artefacto del modelo incluye la versión, la configuración, la referencia al conjunto de datos y el preprocesamiento
La ruta de puesta en producción valida las entradas y cuenta con comportamiento de tiempo de espera, plan de contingencia y reversión
La supervisión abarca el estado del sistema, la deriva de las características, la deriva de las predicciones y las etiquetas retrasadas
Los datos sensibles se excluyen de los artefactos, los registros, las indicaciones y los ejemplos

Antipatrones

Se requiere el estado del cuaderno para reproducir el modelo
La división aleatoria filtra datos futuros hacia los conjuntos de validación o de prueba
Las uniones de características ignoran la hora del evento y la disponibilidad de las etiquetas
La métrica fuera de línea mejora, mientras que algunos segmentos importantes empeoran
Los umbrales se ajustan repetidamente en el conjunto de prueba
El preprocesamiento del entrenamiento se copia manualmente en el código de servicio
Falta la versión del modelo en los registros de predicción
La supervisión solo comprueba el tiempo de actividad del servicio, no la calidad de los datos ni de las predicciones
La reversión requiere un nuevo entrenamiento en lugar de cambiar a un artefacto que se sabe que funciona correctamente

Resultados esperados

Al utilizar esta habilidad, se deben proporcionar artefactos concretos: contrato de datos, controles de promoción, pasos del proceso, plan de pruebas, plan de implementación o conclusiones de la revisión. Se deben señalar las incógnitas que impiden la preparación para la producción, en lugar de suplirlas con suposiciones.

Ver en GitHub

---
name: mle-workflow
description: Turn model work into a production ML system with data contracts, repeatable training, measurable quality gates, deployable artifacts, and operational monitoring.
---

# Machine Learning Engineering Workflow

Use this skill to turn model work into a production ML system with clear data contracts, repeatable training, measurable quality gates, deployable artifacts, and operational monitoring.

## When to Activate

- Planning or reviewing a production ML feature, model refresh, ranking system, recommender, classifier, embedding workflow, or forecasting pipeline
- Converting notebook code into a reusable training, evaluation, batch inference, or online inference pipeline
- Designing model promotion criteria, offline/online evals, experiment tracking, or rollback paths
- Debugging failures caused by data drift, label leakage, stale features, artifact mismatch, or inconsistent training and serving logic
- Adding model monitoring, canary rollout, shadow traffic, or post-deploy quality checks

## Scope Calibration

Use only the lanes that fit the system in front of you. This skill is useful for ranking, search, recommendations, classifiers, forecasting, embeddings, LLM workflows, anomaly detection, and batch analytics, but it should not force one architecture onto all of them.

- Do not assume every model has supervised labels, online serving, a feature store, PyTorch, GPUs, human review, A/B tests, or real-time feedback.
- Do not add heavyweight MLOps machinery when a data contract, baseline, eval script, and rollback note would make the change reviewable.
- Do make assumptions explicit when the project lacks labels, delayed outcomes, slice definitions, production traffic, or monitoring ownership.
- Treat examples as interchangeable scaffolds. Replace metrics, serving mode, data stores, and rollout mechanics with the project-native equivalents.

## Related Skills

- `python-patterns` and `python-testing` for Python implementation and pytest coverage
- `pytorch-patterns` for deep learning models, data loaders, device handling, and training loops
- `eval-harness` and `ai-regression-testing` for promotion gates and agent-assisted regression checks
- `database-migrations`, `postgres-patterns`, and `clickhouse-io` for data storage and analytics surfaces
- `deployment-patterns`, `docker-patterns`, and `security-review` for serving, secrets, containers, and production hardening

## Reuse the SWE Surface

Do not treat MLE as separate from software engineering. Most ECC SWE workflows apply directly to ML systems, often with stricter failure modes:

The recommended `minimal --with capability:machine-learning` install keeps the core agent surface available alongside this skill. For skill-only or agent-limited harnesses, pair `skill:mle-workflow` with `agent:mle-reviewer` where the target supports agents.

| SWE surface | MLE use |
|-------------|---------|
| `product-capability` / `architecture-decision-records` | Turn model work into explicit product contracts and record irreversible data, model, and rollout choices |
| `repo-scan` / `codebase-onboarding` / `code-tour` | Find existing training, feature, serving, eval, and monitoring paths before introducing a parallel ML stack |
| `plan` / `feature-dev` | Scope model changes as product capabilities with data, eval, serving, and rollback phases |
| `tdd-workflow` / `python-testing` | Test feature transforms, split logic, metric calculations, artifact loading, and inference schemas before implementation |
| `code-reviewer` / `mle-reviewer` | Review code quality plus ML-specific leakage, reproducibility, promotion, and monitoring risks |
| `build-fix` / `pr-test-analyzer` | Diagnose broken CI, flaky evals, missing fixtures, and environment-specific model or dependency failures |
| `quality-gate` / `test-coverage` | Require automated evidence for transforms, metrics, inference contracts, promotion gates, and rollback behavior |
| `eval-harness` / `verification-loop` | Turn offline metrics, slice checks, latency budgets, and rollback drills into repeatable gates |
| `ai-regression-testing` | Preserve every production bug as a regression: missing feature, stale label, bad artifact, schema drift, or serving mismatch |
| `api-design` / `backend-patterns` | Design prediction APIs, batch jobs, idempotent retraining endpoints, and response envelopes |
| `database-migrations` / `postgres-patterns` / `clickhouse-io` | Version labels, feature snapshots, prediction logs, experiment metrics, and drift analytics |
| `deployment-patterns` / `docker-patterns` | Package reproducible training and serving images with health checks, resource limits, and rollback |
| `canary-watch` / `dashboard-builder` | Make rollout health visible with model-version, slice, drift, latency, cost, and delayed-label dashboards |
| `security-review` / `security-scan` | Check model artifacts, notebooks, prompts, datasets, and logs for secrets, PII, unsafe deserialization, and supply-chain risk |
| `e2e-testing` / `browser-qa` / `accessibility` | Test critical product flows that consume predictions, including explainability and fallback UI states |
| `benchmark` / `performance-optimizer` | Measure throughput, p95 latency, memory, GPU utilization, and cost per prediction or retrain |
| `cost-aware-llm-pipeline` / `token-budget-advisor` | Route LLM/embedding workloads by quality, latency, and budget instead of defaulting to the largest model |
| `documentation-lookup` / `search-first` | Verify current library behavior for model serving, feature stores, vector DBs, and eval tooling before coding |
| `git-workflow` / `github-ops` / `opensource-pipeline` | Package MLE changes for review with crisp scope, generated artifacts excluded, and reproducible test evidence |
| `strategic-compact` / `dmux-workflows` | Split long ML work into parallel tracks: data contract, eval harness, serving path, monitoring, and docs |

## Ten MLE Task Simulations

Use these simulations as coverage checks when planning or reviewing MLE work. A strong MLE workflow should reduce each task to explicit contracts, reusable SWE surfaces, automated evidence, and a reviewable artifact.

| ID | Common MLE task | Streamlined ECC path | Required output | Pipeline lanes covered |
|----|-----------------|----------------------|-----------------|------------------------|
| MLE-01 | Frame an ambiguous prediction, ranking, recommender, classifier, embedding, or forecast capability | `product-capability`, `plan`, `architecture-decision-records`, `mle-workflow` | Iteration Compact naming who cares, decision owner, success metric, unacceptable mistakes, assumptions, constraints, and first experiment | product contract, stakeholder loss, risk, rollout |
| MLE-02 | Define metric goals, labels, data sources, and the mistake budget | `repo-scan`, `database-reviewer`, `database-migrations`, `postgres-patterns`, `clickhouse-io` | Data and metric contract with entity grain, label timing, label confidence, feature timing, point-in-time joins, split policy, and dataset snapshot | data contract, metric design, leakage, reproducibility |
| MLE-03 | Build a baseline model and scoring path before adding complexity | `tdd-workflow`, `python-testing`, `python-patterns`, `code-reviewer` | Baseline scorer with confusion matrix, calibration notes, latency/cost estimate, known weaknesses, and tests for score shape and determinism | baseline, scoring, testing, serving parity |
| MLE-04 | Generate features from hypotheses about what separates outcomes | `python-patterns`, `pytorch-patterns`, `docker-patterns`, `deployment-patterns` | Feature plan and transform module covering signal source, missing values, outliers, correlations, leakage checks, and train/serve equivalence | feature pipeline, leakage, training, artifacts |
| MLE-05 | Tune thresholds, configs, and model complexity under tradeoffs | `eval-harness`, `ai-regression-testing`, `quality-gate`, `test-coverage` | Threshold/config report comparing precision, recall, F1, AUC, calibration, group slices, latency, cost, complexity, and acceptable error classes | evaluation, threshold, promotion, regression |
| MLE-06 | Run error analysis and turn mistakes into the next experiment | `eval-harness`, `ai-regression-testing`, `mle-reviewer`, `silent-failure-hunter` | Error cluster report for false positives, false negatives, ambiguous labels, stale features, missing signals, and bug traces with lessons captured | error analysis, bug trace, iteration, regression |
| MLE-07 | Package a model artifact for batch or online inference | `api-design`, `backend-patterns`, `security-review`, `security-scan` | Versioned artifact bundle with preprocessing, config, dependency constraints, schema validation, safe loading, and PII-safe logs | artifact, security, inference contract |
| MLE-08 | Ship online serving or batch scoring with feedback capture | `api-design`, `backend-patterns`, `e2e-testing`, `browser-qa`, `accessibility` | Prediction endpoint or batch job with response envelope, timeout, batching, fallback, model version, confidence, feedback logging, and product-flow tests | serving, batch inference, fallback, user workflow |
| MLE-09 | Roll out a model with shadow traffic, canary, A/B test, or rollback | `canary-watch`, `dashboard-builder`, `verification-loop`, `performance-optimizer` | Rollout plan naming traffic split, dashboards, p95 latency, cost, quality guardrails, rollback artifact, and rollback trigger | deployment, canary, rollback |
| MLE-10 | Operate, debug, and refresh a production model after launch | `silent-failure-hunter`, `dashboard-builder`, `mle-reviewer`, `doc-updater`, `github-ops` | Observation ledger and refresh plan with drift checks, delayed-label health, alert owners, runbook updates, retrain criteria, and PR evidence | monitoring, incident response, retraining |

## Iteration Compact

Before touching model code, compress the work into one reviewable artifact. This should be short enough to fit in a PR description and precise enough that another engineer can challenge the tradeoffs.

```text
Goal:
Who cares:
Decision owner:
User or system action changed by the model:
Success metric:
Guardrail metrics:
Mistake budget:
Unacceptable mistakes:
Acceptable mistakes:
Assumptions:
Constraints:
Labels and data snapshot:
Baseline:
Candidate signals:
Threshold or config plan:
Eval slices:
Known risks:
Next experiment:
Rollback or fallback:
```

This compact is the MLE equivalent of a strong SWE design note. It keeps the team from optimizing a metric no one trusts, adding features that do not address the real error mode, or shipping complexity without a rollback.

## Decision Brain

Use this loop whenever the task is ambiguous, high-impact, or metric-heavy:

1. Start from the decision, not the model. Name the action that changes downstream behavior.
2. Name who cares and why. Different stakeholders pay different costs for false positives, false negatives, latency, compute spend, opacity, or missed opportunities.
3. Convert ambiguity into hypotheses. Ask what signal would separate outcomes, what evidence would disprove it, and what simple baseline should be hard to beat.
4. Research prior art or a nearby known problem before inventing a bespoke system.
5. Score choices with `(probability, confidence) x (cost, severity, importance, impact)`.
6. Consider adversarial behavior, incentives, selective disclosure, distribution shift, and feedback loops.
7. Prefer the simplest change that reduces the most important mistake. Simplicity is not laziness; it is a way to minimize blunders while preserving iteration speed.
8. Capture the decision, evidence, counterargument, and next reversible step.

## Metric and Mistake Economics

Choose metrics from failure costs, not habit:

- Use a confusion matrix early so the team can discuss concrete false positives and false negatives instead of abstract accuracy.
- Favor precision when the cost of an incorrect positive decision dominates.
- Favor recall when the cost of a missed positive dominates.
- Use F1 only when the precision/recall tradeoff is genuinely balanced and explainable.
- Use AUC or ranking metrics when ordering quality matters more than a single threshold.
- Track latency, throughput, memory, and cost as first-class metrics because they shape feasible model complexity.
- Compare against a baseline and the current production model before celebrating an offline gain.
- Treat real-world feedback signals as delayed labels with bias, lag, and coverage gaps; do not treat them as ground truth without analysis.

Every metric choice should state which mistake it makes cheaper, which mistake it makes more likely, and who absorbs that cost.

## Data and Feature Hypotheses

Features should come from a theory of separation:

- Text, categorical fields, numeric histories, graph relationships, recency, frequency, and aggregates are candidate signal families, not automatic features.
- For every feature family, state why it should separate outcomes and how it could leak future information.
- For noisy labels, consider adjudication, label confidence, soft targets, or confidence weighting.
- For class imbalance, compare weighted loss, resampling, threshold movement, and calibrated decision rules.
- For missing values, decide whether absence is informative, imputable, or a reason to abstain.
- For outliers, decide whether to clip, bucket, investigate, or preserve them as rare but important signal.
- For correlated features, check whether they are redundant, unstable, or proxies for unavailable future state.

Do not add model complexity until error analysis shows that the baseline is failing for a reason additional signal or capacity can plausibly fix.

## Error Analysis Loop

After each baseline, training run, threshold change, or config change:

1. Split mistakes into false positives, false negatives, abstentions, low-confidence cases, and system failures.
2. Cluster errors by shared traits: language, entity type, source, time, geography, device, sparsity, recency, feature freshness, label source, or model version.
3. Separate model mistakes from data bugs, label ambiguity, product ambiguity, instrumentation gaps, and serving mismatches.
4. Trace each major cluster to one of four moves: better labels, better features, better threshold/config, or better product fallback.
5. Preserve every important mistake as a regression test, eval slice, dashboard panel, or runbook entry.
6. Write the next iteration as a falsifiable experiment, not a vague "improve model" task.

The strongest MLE loop is not train -> metric -> ship. It is mistake -> cluster -> hypothesis -> experiment -> evidence -> simpler system.

## Observation Ledger

Keep a compact decision and evidence trail beside the code, PR, experiment report, or runbook:

```text
Iteration:
Change:
Why this mattered:
Metric movement:
Slice movement:
False positives:
False negatives:
Unexpected errors:
Decision:
Tradeoff accepted:
Lesson captured:
Regression added:
Debt created:
Next iteration:
```

Use the ledger to make model work cumulative. The goal is for each iteration to make the next decision easier, not merely to produce another artifact.

## Core Workflow

### 1. Define the Prediction Contract

Capture the product-level contract before writing model code:

- Prediction target and decision owner
- Input entity, output schema, confidence/calibration fields, and allowed latency
- Batch, online, streaming, or hybrid serving mode
- Fallback behavior when the model, feature store, or dependency is unavailable
- Human review or override path for high-impact decisions
- Privacy, retention, and audit requirements for inputs, predictions, and labels

Do not accept "improve the model" as a requirement. Tie the model to an observable product behavior and a measurable acceptance gate.

### 2. Lock the Data Contract

Every ML task needs an explicit data contract:

- Entity grain and primary key
- Label definition, label timestamp, and label availability delay
- Feature timestamp, freshness SLA, and point-in-time join rules
- Train, validation, test, and backtest split policy
- Required columns, allowed nulls, ranges, categories, and units
- PII or sensitive fields that must not enter training artifacts or logs
- Dataset version or snapshot ID for reproducibility

Guard against leakage first. If a feature is not available at prediction time, or is joined using future information, remove it or move it to an analysis-only path.

### 3. Build a Reproducible Pipeline

Training code should be runnable by another engineer without hidden notebook state:

- Use typed config files or dataclasses for all hyperparameters and paths
- Pin package and model dependencies
- Set random seeds and document any nondeterministic GPU behavior
- Record dataset version, code SHA, config hash, metrics, and artifact URI
- Save preprocessing logic with the model artifact, not separately in a notebook
- Keep train, eval, and inference transformations shared or generated from one source
- Make every step idempotent so retries do not corrupt artifacts or metrics

Prefer immutable values and pure transformation functions. Avoid mutating shared data frames or global config during feature generation.

```python
import hashlib
from dataclasses import dataclass
from pathlib import Path


@dataclass(frozen=True)
class TrainingConfig:
    dataset_uri: str
    model_dir: Path
    seed: int
    learning_rate: float
    batch_size: int


def artifact_name(config: TrainingConfig, code_sha: str) -> str:
    config_key = f"{config.dataset_uri}:{config.seed}:{config.learning_rate}:{config.batch_size}"
    config_hash = hashlib.sha256(config_key.encode("utf-8")).hexdigest()[:12]
    return f"{code_sha[:12]}-{config_hash}"
```

### 4. Evaluate Before Promotion

Promotion criteria should be declared before training finishes:

- Baseline model and current production model comparison
- Primary metric aligned to product behavior
- Guardrail metrics for latency, calibration, fairness slices, cost, and error concentration
- Slice metrics for important cohorts, geographies, devices, languages, or data sources
- Confidence intervals or repeated-run variance when metrics are noisy
- Failure examples reviewed by a human for high-impact models
- Explicit "do not ship" thresholds

```python
PROMOTION_GATES = {
    "auc": ("min", 0.82),
    "calibration_error": ("max", 0.04),
    "p95_latency_ms": ("max", 80),
}


def assert_promotion_ready(metrics: dict[str, float]) -> None:
    missing = sorted(name for name in PROMOTION_GATES if name not in metrics)
    if missing:
        raise ValueError(f"Model promotion metrics missing required gates: {missing}")

    failures = {
        name: value
        for name, (direction, threshold) in PROMOTION_GATES.items()
        for value in [metrics[name]]
        if (direction == "min" and value < threshold)
        or (direction == "max" and value > threshold)
    }
    if failures:
        raise ValueError(f"Model failed promotion gates: {failures}")
```

Use offline metrics as gates, not guarantees. When the model changes product behavior, plan shadow evaluation, canary rollout, or A/B testing before full rollout.

### 5. Package for Serving

An ML artifact is production-ready only when the serving contract is testable:

- Model artifact includes version, training data reference, config, and preprocessing
- Input schema rejects invalid, stale, or out-of-range features
- Output schema includes model version and confidence or explanation fields when useful
- Serving path has timeout, batching, resource limits, and fallback behavior
- CPU/GPU requirements are explicit and tested
- Prediction logs avoid PII and include enough identifiers for debugging and label joins
- Integration tests cover missing features, stale features, bad types, empty batches, and fallback path

Never let training-only feature code diverge from serving feature code without a test that proves equivalence.

### 6. Operate the Model

Model monitoring needs both system and quality signals:

- Availability, error rate, timeout rate, queue depth, and p50/p95/p99 latency
- Feature null rate, range drift, categorical drift, and freshness drift
- Prediction distribution drift and confidence distribution drift
- Label arrival health and delayed quality metrics
- Business KPI guardrails and rollback triggers
- Per-version dashboards for canaries and rollbacks

Every deployment should have a rollback plan that names the previous artifact, config, data dependency, and traffic-switch mechanism.

## Review Checklist

- [ ] Prediction contract is explicit and testable
- [ ] Data contract defines entity grain, label timing, feature timing, and snapshot/version
- [ ] Leakage risks were checked against prediction-time availability
- [ ] Training is reproducible from code, config, data version, and seed
- [ ] Metrics compare against baseline and current production model
- [ ] Slice metrics and guardrails are included for high-risk cohorts
- [ ] Promotion gates are automated and fail closed
- [ ] Training and serving transformations are shared or equivalence-tested
- [ ] Model artifact carries version, config, dataset reference, and preprocessing
- [ ] Serving path validates inputs and has timeout, fallback, and rollback behavior
- [ ] Monitoring covers system health, feature drift, prediction drift, and delayed labels
- [ ] Sensitive data is excluded from artifacts, logs, prompts, and examples

## Anti-Patterns

- Notebook state is required to reproduce the model
- Random split leaks future data into validation or test sets
- Feature joins ignore event time and label availability
- Offline metric improves while important slices regress
- Thresholds are tuned on the test set repeatedly
- Training preprocessing is copied manually into serving code
- Model version is missing from prediction logs
- Monitoring only checks service uptime, not data or prediction quality
- Rollback requires retraining instead of switching to a known-good artifact

## Output Expectations

When using this skill, return concrete artifacts: data contract, promotion gates, pipeline steps, test plan, deployment plan, or review findings. Call out unknowns that block production readiness instead of filling them with assumptions.