Maison

Skill

Science des données et ML

mle-workflow

affaan-m/ECC

Transformez vos modèles en un système d'apprentissage automatique de production grâce à des contrats de données, un apprentissage reproductible, des critères de qualité mesurables, des artefacts déployables et une surveillance opérationnelle.

...Développer tout

Heure mise à jour 1 octobre 2026

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

Flux de travail d'ingénierie en apprentissage automatique

Utilisez cette compétence pour transformer le travail sur les modèles en un système d'apprentissage automatique en production, doté de contrats de données clairs, d'un apprentissage reproductible, de critères de qualité mesurables, d'artefacts déployables et d'une surveillance opérationnelle.

Quand l'activer

Lors de la planification ou de la révision d’une fonctionnalité d’apprentissage automatique en production, d’une mise à jour de modèle, d’un système de classement, d’un système de recommandation, d’un classificateur, d’un workflow d’encodage vectoriel ou d’un pipeline de prévision
Conversion du code d’un notebook en pipeline réutilisable d’entraînement, d’évaluation, d’inférence par lots ou d’inférence en ligne
Conception de critères de promotion de modèles, d’évaluations hors ligne/en ligne, de suivi d’expériences ou de chemins de retour en arrière
Débogage des défaillances causées par une dérive des données, une fuite d’étiquettes, des caractéristiques obsolètes, une incompatibilité d’artefacts ou une logique incohérente d’entraînement et de mise en service
Ajout d’une surveillance des modèles, d’un déploiement « canary », d’un trafic « shadow » ou de contrôles qualité post-déploiement

Calibrage de la portée

N’utilisez que les voies adaptées au système dont vous disposez. Cette compétence est utile pour le classement, la recherche, les recommandations, les classificateurs, les prévisions, les représentations vectorielles, les workflows LLM, la détection d’anomalies et l’analyse par lots, mais elle ne doit pas imposer une architecture unique à tous ces cas de figure.

Ne partez pas du principe que chaque modèle dispose de labels supervisés, d’un service en ligne, d’un magasin de caractéristiques, de PyTorch, de GPU, d’une révision humaine, de tests A/B ou d’un retour d’information en temps réel.
N’ajoutez pas de mécanismes MLOps lourds lorsqu’un contrat de données, une base de référence, un script d’évaluation et une note de retour en arrière suffisent à rendre le changement vérifiable.
Exprimez clairement vos hypothèses lorsque le projet manque d’étiquettes, de résultats différés, de définitions de tranches, de trafic de production ou de responsabilité en matière de surveillance.
Considérez les exemples comme des structures interchangeables. Remplacez les métriques, le mode de déploiement, les magasins de données et les mécanismes de déploiement par leurs équivalents propres au projet.

Compétences associées

python-patterns et python-testing pour la mise en œuvre en Python et la couverture pytest
pytorch-patterns pour les modèles d’apprentissage profond, les chargeurs de données, la gestion des périphériques et les boucles d’entraînement
eval-harness et ai-regression-testing pour les portes de promotion et les contrôles de régression assistés par des agents
database-migrations, postgres-patterns, et clickhouse-io pour le stockage des données et les interfaces d’analyse
deployment-patterns, docker-patterns, et security-review pour les services, les secrets, les conteneurs et la sécurisation en production

Réutiliser l’environnement SWE

Ne considérez pas le MLE comme distinct de l’ingénierie logicielle. La plupart des workflows ECC SWE s’appliquent directement aux systèmes d’apprentissage automatique, souvent avec des modes de défaillance plus stricts :

L'installation recommandée minimal --with capability:machine-learning conserve l’interface de l’agent principal disponible parallèlement à cette compétence. Pour les harnais réservés aux compétences ou limités à l’agent, associez skill:mle-workflow avec agent:mle-reviewer lorsque la cible prend en charge les agents.

Surface SWE	Utilisation de MLE
`product-capability` / `architecture-decision-records`	Transformez le travail sur les modèles en contrats produit explicites et consignez de manière irréversible les choix relatifs aux données, aux modèles et aux déploiements
`repo-scan` / `codebase-onboarding` / `code-tour`	Identifier les processus existants de formation, de création de fonctionnalités, de mise en production, d’évaluation et de surveillance avant d’introduire une pile d’apprentissage automatique parallèle
`plan` / `feature-dev`	Définir la portée des modifications de modèle en tant que fonctionnalités produit, avec des phases de données, d’évaluation, de mise en production et de retour en arrière
`tdd-workflow` / `python-testing`	Tester les transformations de caractéristiques, la logique de partitionnement, les calculs de métriques, le chargement des artefacts et les schémas d’inférence avant la mise en œuvre
`code-reviewer` / `mle-reviewer`	Vérifiez la qualité du code ainsi que les risques spécifiques au ML liés aux fuites, à la reproductibilité, à la mise en production et à la surveillance
`build-fix` / `pr-test-analyzer`	Diagnostiquer les problèmes de CI, les évaluations instables, les fixtures manquantes et les défaillances de modèles ou de dépendances spécifiques à un environnement
`quality-gate` / `test-coverage`	Exiger des preuves automatisées pour les transformations, les métriques, les contrats d’inférence, les barrières de promotion et le comportement de retour en arrière
`eval-harness` / `verification-loop`	Transformez les métriques hors ligne, les vérifications de tranches, les budgets de latence et les exercices de retour en arrière en portes de contrôle reproductibles
`ai-regression-testing`	Conservez chaque bug de production comme un cas de régression : fonctionnalité manquante, étiquette obsolète, artefact défectueux, dérive de schéma ou incompatibilité de service
`api-design` / `backend-patterns`	Concevoir des API de prédiction, des tâches par lots, des points de terminaison de réentraînement idempotents et des enveloppes de réponse
`database-migrations` / `postgres-patterns` / `clickhouse-io`	Étiquettes de version, instantanés de fonctionnalités, journaux de prédiction, métriques d’expérimentation et analyses de dérive
`deployment-patterns` / `docker-patterns`	Regroupez des images d’entraînement et de service reproductibles avec des contrôles d’intégrité, des limites de ressources et des mécanismes de retour en arrière
`canary-watch` / `dashboard-builder`	Rendez l’état de santé du déploiement visible grâce à des tableaux de bord sur la version du modèle, les tranches, la dérive, la latence, le coût et les étiquettes différées
`security-review` / `security-scan`	Vérifiez les artefacts de modèle, les notebooks, les prompts, les ensembles de données et les journaux à la recherche de secrets, d’informations personnelles identifiables (PII), de désérialisation non sécurisée et de risques liés à la chaîne d’approvisionnement
`e2e-testing` / `browser-qa` / `accessibility`	Tester les flux critiques du produit qui utilisent des prédictions, y compris l’explicabilité et les états de repli de l’interface utilisateur
`benchmark` / `performance-optimizer`	Mesurez le débit, la latence p95, la mémoire, l’utilisation du GPU et le coût par prédiction ou réentraînement
`cost-aware-llm-pipeline` / `token-budget-advisor`	Acheminez les charges de travail LLM/d’embedding en fonction de la qualité, de la latence et du budget, plutôt que d’opter par défaut pour le plus grand modèle
`documentation-lookup` / `search-first`	Vérifier le comportement actuel des bibliothèques pour la mise en service des modèles, les magasins de caractéristiques, les bases de données vectorielles et les outils d’évaluation avant le codage
`git-workflow` / `github-ops` / `opensource-pipeline`	Regroupez les modifications MLE en vue de leur révision avec un périmètre clairement défini, en excluant les artefacts générés et en fournissant des preuves de test reproductibles
`strategic-compact` / `dmux-workflows`	Diviser les travaux de ML de longue haleine en pistes parallèles : contrat de données, harnais d’évaluation, chemin de mise en service, surveillance et documentation

Dix simulations de tâches MLE

Utilisez ces simulations pour vérifier la couverture lors de la planification ou de la révision des travaux MLE. Un workflow MLE solide doit réduire chaque tâche à des contrats explicites, des interfaces SWE réutilisables, des preuves automatisées et un artefact révisable.

ID	Tâche MLE courante	Parcours ECC rationalisé	Résultat requis	Étapes du pipeline couvertes
MLE-01	Définir une capacité ambiguë de prédiction, de classement, de recommandation, de classification, d'encodage ou de prévision	`product-capability`, `plan`, `architecture-decision-records`, `mle-workflow`	Itération Définir de manière concise les parties prenantes, le responsable de la décision, les indicateurs de réussite, les erreurs inacceptables, les hypothèses, les contraintes et le contrat du produit de la première expérience	contrat produit, perte pour les parties prenantes, risque, déploiement
MLE-02	Définir les objectifs en termes de métriques, les étiquettes, les sources de données et le budget d’erreur	`repo-scan`, `database-reviewer`, `database-migrations`, `postgres-patterns`, `clickhouse-io`	Contrat de données et de métriques avec granularité des entités, timing des étiquettes, confiance des étiquettes, timing des caractéristiques, jointures à un instant donné, politique de partitionnement et instantané de l’ensemble de données	Contrat de données, conception des indicateurs, fuites, reproductibilité
MLE-03	Construire un modèle de référence et un chemin de notation avant d’ajouter de la complexité	`tdd-workflow`, `python-testing`, `python-patterns`, `code-reviewer`	Système de notation de référence avec matrice de confusion, notes d’étalonnage, estimation de la latence et des coûts, faiblesses connues et tests portant sur la forme des scores et le déterminisme	référence, notation, tests, parité de mise en production
MLE-04	Générer des caractéristiques à partir d’hypothèses sur ce qui différencie les résultats	`python-patterns`, `pytorch-patterns`, `docker-patterns`, `deployment-patterns`	Plan de caractéristiques et module de transformation couvrant la source du signal, les valeurs manquantes, les valeurs aberrantes, les corrélations, les contrôles de fuite et l’équivalence entre l’entraînement et la mise en production	pipeline de caractéristiques, fuites, entraînement, artefacts
MLE-05	Ajuster les seuils, les configurations et la complexité du modèle en tenant compte des compromis	`eval-harness`, `ai-regression-testing`, `quality-gate`, `test-coverage`	Rapport sur les seuils et les configurations comparant la précision, le rappel, le F1, l’AUC, l’étalonnage, les tranches de groupes, la latence, le coût, la complexité et les classes d’erreurs acceptables	évaluation, seuil, promotion, régression
MLE-06	Effectuer une analyse des erreurs et transformer les erreurs en piste pour la prochaine expérience	`eval-harness`, `ai-regression-testing`, `mle-reviewer`, `silent-failure-hunter`	Rapport de regroupement des erreurs pour les faux positifs, les faux négatifs, les étiquettes ambiguës, les caractéristiques obsolètes, les signaux manquants et les traces de bogues, avec les enseignements tirés	analyse des erreurs, trace de bogue, itération, régression
MLE-07	Empaqueter un artefact de modèle pour l’inférence par lots ou en ligne	`api-design`, `backend-patterns`, `security-review`, `security-scan`	Ensemble d’artefacts versionné comprenant le prétraitement, la configuration, les contraintes de dépendance, la validation du schéma, le chargement sécurisé et des journaux respectant la protection des données personnelles	artefact, sécurité, contrat d’inférence
MLE-08	Déploiement d’un service en ligne ou d’une évaluation par lots avec capture des retours d’expérience	`api-design`, `backend-patterns`, `e2e-testing`, `browser-qa`, `accessibility`	Point de terminaison de prédiction ou tâche par lots avec enveloppe de réponse, délai d’expiration, traitement par lots, solution de secours, version du modèle, niveau de confiance, journalisation des retours d’expérience et tests du flux produit	mise en production, inférence par lots, solution de secours, workflow utilisateur
MLE-09	Déploiement d’un modèle avec trafic fantôme, canary, test A/B ou retour en arrière	`canary-watch`, `dashboard-builder`, `verification-loop`, `performance-optimizer`	Nommage du plan de déploiement : répartition du trafic, tableaux de bord, latence p95, coût, garde-fous de qualité, artefact de retour en arrière et déclencheur de retour en arrière	déploiement, canari, retour en arrière
MLE-10	Exploiter, déboguer et actualiser un modèle en production après son lancement	`silent-failure-hunter`, `dashboard-builder`, `mle-reviewer`, `doc-updater`, `github-ops`	Registre d’observation et plan de rafraîchissement comprenant des contrôles de dérive, l’état de santé des étiquettes différées, les responsables des alertes, les mises à jour du guide d’intervention, les critères de réentraînement et les preuves PR	surveillance, réponse aux incidents, réentraînement

Itération compacte

Avant de modifier le code du modèle, regroupez le travail en un seul artefact pouvant faire l’objet d’une révision. Celui-ci doit être suffisamment court pour tenir dans la description d’une pull request et suffisamment précis pour qu’un autre ingénieur puisse remettre en question les compromis.

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:

Ce « compact » est l’équivalent, en MLE, d’une note de conception solide rédigée par un ingénieur logiciel (SWE). Il empêche l’équipe d’optimiser une métrique à laquelle personne ne fait confiance, d’ajouter des fonctionnalités qui ne traitent pas le véritable mode d’erreur, ou de déployer de la complexité sans possibilité de retour en arrière.

Cercle de décision

Utilisez cette boucle chaque fois que la tâche est ambiguë, a un impact important ou implique de nombreuses métriques :

Commencez par la décision, pas par le modèle. Identifiez l’action qui modifie le comportement en aval.
Identifiez les parties prenantes concernées et expliquez pourquoi. Les différentes parties prenantes supportent des coûts différents liés aux faux positifs, aux faux négatifs, à la latence, aux dépenses informatiques, au manque de transparence ou aux opportunités manquées.
Transformez l’ambiguïté en hypothèses. Demandez-vous quel signal permettrait de distinguer les résultats, quelles preuves pourraient le réfuter et quelle base de référence simple serait difficile à dépasser.
Recherchez l'état de la technique ou un problème similaire déjà connu avant de concevoir un système sur mesure.
Évaluez les choix en tenant compte (probability, confidence) x (cost, severity, importance, impact).
Tenez compte des comportements hostiles, des incitations, de la divulgation sélective, des changements de répartition et des boucles de rétroaction.
Privilégiez le changement le plus simple qui réduit l’erreur la plus importante. La simplicité n’est pas de la paresse ; c’est un moyen de minimiser les erreurs grossières tout en préservant la vitesse d’itération.
Consignez la décision, les preuves, les contre-arguments et la prochaine étape réversible.

Métrique et économie de l’erreur

Choisissez les indicateurs en fonction des coûts des échecs, et non par habitude :

Utilisez une matrice de confusion dès le début afin que l'équipe puisse discuter de faux positifs et de faux négatifs concrets plutôt que de précision abstraite.
Privilégiez la précision lorsque le coût d’une décision positive erronée est prépondérant.
Privilégiez le rappel lorsque le coût d’un positif manqué est prépondérant.
N’utilisez l’indice F1 que lorsque le compromis entre précision et rappel est véritablement équilibré et explicable.
Utilisez l’AUC ou des indicateurs de classement lorsque l’ordre de qualité importe davantage qu’un seuil unique.
Suivez la latence, le débit, la mémoire et le coût comme des indicateurs de premier ordre, car ils déterminent la complexité réalisable du modèle.
Comparez les résultats à une référence et au modèle de production actuel avant de vous réjouir d’un gain hors ligne.
Considérez les signaux de rétroaction du monde réel comme des étiquettes retardées présentant des biais, des décalages et des lacunes de couverture ; ne les traitez pas comme des vérités absolues sans analyse préalable.

Chaque choix de métrique doit préciser quelle erreur il rend moins coûteuse, quelle erreur il rend plus probable, et qui supporte ce coût.

Hypothèses sur les données et les caractéristiques

Les caractéristiques doivent découler d’une théorie de la séparation :

Le texte, les champs catégoriels, les historiques numériques, les relations graphiques, la récence, la fréquence et les agrégats sont des familles de signaux candidates, et non des caractéristiques automatiques.
Pour chaque famille de caractéristiques, précisez pourquoi elle devrait permettre de distinguer les résultats et comment elle pourrait révéler des informations futures.
En cas d’étiquettes bruitées, envisagez l’arbitrage, la confiance des étiquettes, les cibles souples ou la pondération par la confiance.
En cas de déséquilibre entre les classes, comparez la perte pondérée, le rééchantillonnage, le déplacement du seuil et les règles de décision calibrées.
Pour les valeurs manquantes, déterminez si leur absence est informative, si elles sont imputables ou si elles constituent une raison de s’abstenir.
Pour les valeurs aberrantes, déterminez s’il faut les écrêter, les regrouper, les examiner ou les conserver en tant que signal rare mais important.
Pour les caractéristiques corrélées, vérifiez si elles sont redondantes, instables ou si elles servent d’indicateurs d’un état futur indisponible.

N’ajoutez pas de complexité au modèle tant que l’analyse des erreurs n’a pas démontré que le modèle de base échoue pour une raison qu’un signal ou une capacité supplémentaire pourrait raisonnablement corriger.

Boucle d’analyse des erreurs

Après chaque modèle de référence, cycle d’entraînement, modification de seuil ou changement de configuration :

Classez les erreurs en faux positifs, faux négatifs, abstentions, cas à faible confiance et défaillances du système.
Regroupez les erreurs par caractéristiques communes : langue, type d’entité, source, heure, géographie, appareil, rareté, actualité, fraîcheur de la caractéristique, source de l’étiquette ou version du modèle.
Distinguez les erreurs du modèle des bogues dans les données, de l’ambiguïté des étiquettes, de l’ambiguïté du produit, des lacunes d’instrumentation et des incohérences de mise en service.
Associer chaque groupe majeur à l’une des quatre mesures suivantes : de meilleurs étiquettes, de meilleures caractéristiques, de meilleurs seuils/paramètres de configuration ou une meilleure solution de repli du produit.
Conservez chaque erreur importante sous forme de test de régression, de tranche d’évaluation, de panneau de tableau de bord ou d’entrée dans le guide d’exploitation.
Concevez la prochaine itération comme une expérience falsifiable, et non comme une vague tâche consistant à « améliorer le modèle ».

La boucle MLE la plus solide n’est pas « entraînement → métrique → déploiement ». C’est « erreur → cluster → hypothèse → expérience → preuve → système plus simple ».

Registre d’observations

Conservez une trace concise des décisions et des preuves à côté du code, des PR, des rapports d’expérimentation ou du runbook :

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:

Utilisez ce registre pour rendre le travail sur le modèle cumulatif. L’objectif est que chaque itération facilite la décision suivante, et non pas simplement de produire un nouvel artefact.

Workflow principal

1. Définir le contrat de prédiction

Définissez le contrat au niveau du produit avant d'écrire le code du modèle :

Cible de prédiction et responsable de la décision
Entité d'entrée, schéma de sortie, champs de confiance/calibrage et latence autorisée
Mode de service par lots, en ligne, en streaming ou hybride
Comportement de secours lorsque le modèle, le magasin de caractéristiques ou une dépendance n’est pas disponible
Vérification humaine ou procédure de contournement pour les décisions à fort impact
Exigences en matière de confidentialité, de conservation et d’audit pour les entrées, les prédictions et les étiquettes

N’acceptez pas « améliorer le modèle » comme exigence. Liez le modèle à un comportement observable du produit et à un critère d’acceptation mesurable.

2. Fixez le contrat de données

Chaque tâche d’apprentissage automatique nécessite un contrat de données explicite :

Niveau de granularité des entités et clé primaire
Définition des étiquettes, horodatage des étiquettes et délai de disponibilité des étiquettes
Horodatage des caractéristiques, SLA de fraîcheur et règles de jointure ponctuelles
Politique de répartition entre les ensembles d'entraînement, de validation, de test et de backtest
Colonnes obligatoires, valeurs nulles autorisées, plages, catégories et unités
Données à caractère personnel (PII) ou champs sensibles ne devant pas figurer dans les artefacts d’entraînement ni dans les journaux
Version du jeu de données ou identifiant de l’instantané pour la reproductibilité

Privilégiez la prévention des fuites. Si une caractéristique n’est pas disponible au moment de la prédiction, ou si elle est jointe à l’aide d’informations futures, supprimez-la ou transférez-la vers un parcours réservé à l’analyse.

3. Construire un pipeline reproductible

Le code d’entraînement doit pouvoir être exécuté par un autre ingénieur sans état caché du notebook :

Utilisez des fichiers de configuration typés ou des classes de données pour tous les hyperparamètres et toutes les branches
Fixez les dépendances des paquets et des modèles
Définissez des graines aléatoires et documentez tout comportement non déterministe du GPU
Enregistrez la version du jeu de données, le SHA du code, le hachage de la configuration, les métriques et l’URI de l’artefact
Enregistrez la logique de prétraitement avec l'artefact du modèle, et non séparément dans un notebook
Veillez à ce que les transformations d’entraînement, d’évaluation et d’inférence soient partagées ou générées à partir d’une seule source
Rendre chaque étape idempotente afin que les nouvelles tentatives n’altèrent pas les artefacts ou les métriques

Privilégier les valeurs immuables et les fonctions de transformation pures. Éviter de modifier les tableaux de données partagés ou la configuration globale lors de la génération de caractéristiques.

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. Évaluer avant la promotion

Les critères de mise en production doivent être définis avant la fin de l’entraînement :

Comparaison entre le modèle de référence et le modèle de production actuel
Métrique principale alignée sur le comportement du produit
Métriques de sécurité pour la latence, l’étalonnage, les tranches d’équité, le coût et la concentration des erreurs
Indicateurs par tranche pour les cohortes, zones géographiques, appareils, langues ou sources de données importantes
Intervalles de confiance ou variance des exécutions répétées lorsque les indicateurs présentent du bruit
Exemples d’échecs examinés par un humain pour les modèles à fort impact
Seuils explicites de « ne pas déployer »

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}")

Utilisez les indicateurs hors ligne comme filtres, et non comme garanties. Lorsque le modèle modifie le comportement du produit, prévoyez une évaluation en parallèle, un déploiement « canari » ou des tests A/B avant le déploiement complet.

5. Préparation pour la mise en production

Un artefact ML n'est prêt pour la production que lorsque le contrat de mise en service est testable :

L’artefact de modèle comprend la version, la référence aux données d’entraînement, la configuration et le prétraitement
Le schéma d’entrée rejette les caractéristiques invalides, obsolètes ou hors limites
Le schéma de sortie inclut la version du modèle et des champs de confiance ou d'explication lorsque cela est utile
Le chemin de mise en service comporte un délai d’expiration, un traitement par lots, des limites de ressources et un comportement de repli
Les exigences en matière de CPU/GPU sont explicites et testées
Les journaux de prédiction évitent les données à caractère personnel (PII) et incluent suffisamment d’identifiants pour le débogage et les jointures d’étiquettes
Les tests d’intégration couvrent les caractéristiques manquantes, obsolètes, de type incorrect, les lots vides et le chemin de secours

Ne laissez jamais le code des caractéristiques destiné uniquement à l’entraînement diverger du code des caractéristiques de mise en service sans un test prouvant leur équivalence.

6. Exploiter le modèle

La surveillance du modèle nécessite à la fois des signaux système et des signaux de qualité :

disponibilité, taux d’erreur, taux de délai d’expiration, profondeur de la file d’attente et latence p50/p95/p99
Taux de valeurs nulles des caractéristiques, dérive de plage, dérive catégorielle et dérive de fraîcheur
Dérive de la distribution des prédictions et dérive de la distribution de confiance
Santé de l’arrivée des étiquettes et indicateurs de qualité liés aux retards
Seuils de sécurité pour les indicateurs clés de performance (KPI) métier et déclencheurs de retour en arrière
Tableaux de bord par version pour les déploiements canari et les retours en arrière

Chaque déploiement doit s’accompagner d’un plan de retour en arrière précisant l’artefact précédent, la configuration, les dépendances de données et le mécanisme de basculement du trafic.

Liste de contrôle

Le contrat de prédiction est explicite et vérifiable
Le contrat de données définit le niveau de granularité des entités, le calendrier des étiquettes, le calendrier des fonctionnalités et les instantanés/versions
Les risques de fuite ont été vérifiés par rapport à la disponibilité au moment de la prédiction
L'entraînement est reproductible à partir du code, de la configuration, de la version des données et de la graine
Les métriques sont comparées au modèle de référence et au modèle de production actuel
Des métriques par tranche et des garde-fous sont inclus pour les cohortes à haut risque
Les barrières de promotion sont automatisées et fonctionnent selon le principe « fail closed »
Les transformations d’entraînement et de mise en production sont partagées ou soumises à des tests d’équivalence
L’artefact du modèle contient la version, la configuration, la référence de l’ensemble de données et le prétraitement
Le chemin de mise en production valide les entrées et intègre des mécanismes de délai d’expiration, de repli et de restauration
La surveillance couvre l’état du système, la dérive des caractéristiques, la dérive des prédictions et les étiquettes retardées
Les données sensibles sont exclues des artefacts, des journaux, des invites et des exemples

Anti-modèles

L’état du notebook est nécessaire pour reproduire le modèle
Le découpage aléatoire entraîne la fuite de données futures dans les ensembles de validation ou de test
Les jointures de caractéristiques ignorent l’heure de l’événement et la disponibilité des étiquettes
Les métriques hors ligne s’améliorent tandis que des tranches importantes régressent
Les seuils sont ajustés à plusieurs reprises sur l’ensemble de test
Le prétraitement de l'entraînement est copié manuellement dans le code de déploiement
La version du modèle est absente des journaux de prédiction
La surveillance vérifie uniquement la disponibilité du service, et non la qualité des données ou des prédictions
La restauration nécessite un réentraînement au lieu de basculer vers un artefact dont la bon fonctionnement est avéré

Résultats attendus

Lors de l’utilisation de cette compétence, fournissez des artefacts concrets : contrat de données, étapes de promotion, étapes du pipeline, plan de test, plan de déploiement ou conclusions de l’examen. Signalez les inconnues qui empêchent la mise en production au lieu de les combler par des hypothèses.

Voir sur 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.