Suivre l'apprentissage de l'IA

Ce manuel s'adresse aux SUPER_ADMIN, aux ROLE_GOVERNANCE et aux comptes ROLE_ANALYST qui mesurent l'efficacité de la boucle d'apprentissage active. Le dashboard visualise le taux de détections ambiguës, les formats problématiques et le flux d'événements vers PIGES.

Pourquoi cette feature

La boucle d'apprentissage (voir manuel Triage IA) publie chaque correction humaine vers PIGES, qui enrichit ses embeddings CLIP. Sans métriques, il est impossible de répondre à une question simple : « Est-ce que l'IA s'améliore vraiment ? ».

Ce dashboard répond à quatre questions opérationnelles :

1. Combien d'ads détectées sur la période, et combien en format_unknown ?
2. Le taux d'unknown baisse-t-il dans le temps ?
3. Quels formats canoniques sont systématiquement mal classés ?
4. Combien d'événements d'apprentissage sont publiés vers PIGES chaque jour ?

À savoir

La permission requise est backstage.audit.read, accordée aux SUPER_ADMIN, ROLE_GOVERNANCE et ROLE_ANALYST. Le dashboard est read-only : aucune action ne modifie l'état du système.

Workflow détaillé

1. Accéder au dashboard

Depuis le menu Backstage, section Observabilité, cliquez sur Apprentissage IA. L'URL directe est /backstage/ai-learning.

2. Appliquer les filtres

Deux filtres au-dessus des widgets :

• Magazine : dropdown listant tous les magazines actifs. Valeur par défaut Tous pour une vue agrégée. Sélectionnez Le Quotidien Médical pour isoler un magazine et diagnostiquer un catalogue spécifique.
• Période : boutons rapides 7 jours, 30 jours (défaut), 90 jours. Période maximale 365 jours.

Les quatre widgets se rafraîchissent automatiquement à chaque changement de filtre.

3. Lire les KPI cards

La première rangée affiche cinq KPI principaux :

KPI	Signification	Lecture idéale
Total ads	Nombre total d'ads ingérées sur la période	Tendance haussière = activité pipeline normale
Unknown	Ads flaggées format_unknown (confidence < 0.60)	Baisse dans le temps = apprentissage effectif
Taux unknown	Unknown / Total	Cible < 10 % sur un catalogue mature
Needs review	Ads flaggées format_needs_review (0.60–0.85)	Volume stable, devrait baisser avec les reclassifs
Reclassifs	Nombre de réaffectations manuelles via Triage ou F06	Plus haut = boucle active, PIGES enrichi

4. Analyser la courbe du taux unknown

Le widget Taux unknown dans le temps affiche une courbe (line chart) du taux d'unknown jour par jour sur la période sélectionnée. L'axe Y est en pourcentage, l'axe X en dates.

Interprétation :

• Pente descendante régulière : l'apprentissage fonctionne, Claude gagne en précision.
• Pic ponctuel : souvent lié à l'ajout d'un nouveau magazine dont le catalogue n'est pas encore seed. Utilisez Uploader une grille tarifaire pour combler.
• Plateau durable > 15 % : le catalogue du magazine est probablement incomplet. Enquêtez sur les formats problématiques (widget suivant).

5. Top 5 formats problématiques

Le tableau classe les AdFormat ayant généré le plus de reclassifs (autrement dit, où Claude s'est le plus trompé). Chaque ligne affiche :

• Libellé et code du format.
• Canonique associé.
• Nombre de reclassifs sur la période.
• Lien rapide vers la queue Triage filtrée sur ce format.

Si un format reste en tête pendant plusieurs semaines, cela indique soit un prompt à affiner (voir Prompt Studio), soit un canonique mal choisi à repenser.

6. Events PIGES par jour

Le dernier widget (bar chart) compte les événements ad-reassigned publiés vers PIGES jour par jour. Chaque barre représente le nombre d'embeddings CLIP ajoutés à ChromaDB.

Lecture :

• Corrélation forte avec la courbe reclassifs : le circuit fire-and-forget fonctionne.
• Écart important (reclassifs >> events PIGES) : soit PIGES est indisponible, soit le circuit breaker est ouvert. Vérifiez les logs ai.learning.event_failed dans l'audit.

Interprétation globale

Apprentissage actif

• Taux unknown en baisse régulière.
• Volume d'events PIGES stable ou en hausse (proportionnel à l'activité).
• Les formats en tête du top 5 changent de semaine en semaine.

Stagnation

• Taux unknown stable autour d'une valeur > 10 %.
• Mêmes formats systématiquement en tête du top 5.

Action : cataloguer les formats manquants via la queue Triage (CTA Créer ce format), ou tuner le prompt via Prompt Studio.

Régression

• Taux unknown en hausse après avoir baissé.

Action : vérifier si un nouveau prompt a été activé récemment (audit ai.prompt.activated). Si oui, envisager un rollback vers la version précédente.

Cas limites

Magazine fraîchement onboarded

Les premiers jours, le taux unknown est mécaniquement élevé (catalogue vide ou partiel). Ce n'est pas un signal de dysfonctionnement mais un point de départ. Attendez 2 à 3 semaines de reclassifs avant de conclure sur la trajectoire.

Période trop courte

Sur 7 jours, les variations sont trop bruitées pour dégager une tendance fiable. Préférez 30 jours pour les revues hebdo, 90 jours pour les points trimestriels.

Magazine sans aucune ad

Si le magazine sélectionné n'a reçu aucun upload sur la période, tous les KPI affichent 0 et les courbes sont plates. Ce n'est pas un bug, c'est l'absence de données.

Discordance entre reclassifs et events PIGES

Si reclassifs = 100 et events PIGES = 40, cela signifie que 60 publications n'ont pas été transmises à PIGES. Causes probables :

• PIGES en maintenance (circuit breaker ouvert).
• Timeout HTTP (> 2 s).
• Payload malformé (ad sans bbox ou sans imageUrl).

Vérifiez les logs ai.learning.event_failed dans Observabilité > Audit log.

FAQ

À quelle fréquence les données sont-elles rafraîchies ?

Les KPI sont calculés à la volée à chaque requête (pas de cache applicatif). La réponse tient généralement en moins de 800 ms grâce aux index partiels sur ad.format_unknown et ad.format_needs_review.

Quelle est la rétention des données ?

Les ads sont conservées indéfiniment. Les événements PIGES sont stockés dans la table learning_events côté PIGES et conservés 2 ans, puis archivés en S3 Glacier.

Puis-je exporter les stats en CSV ?

Pas directement depuis l'UI en v1. Les données sont accessibles via l'endpoint GET /api/backstage/ai-learning/stats?magazineId=&days= qui renvoie le JSON complet, facilement convertible en CSV via un outil externe. Un bouton d'export natif est prévu pour v2.

Le dashboard est-il disponible hors SUPER_ADMIN ?

Oui : la permission backstage.audit.read est accordée à ROLE_GOVERNANCE et ROLE_ANALYST, qui ont donc l'accès read-only. Ils ne peuvent en revanche pas cliquer sur les liens vers Prompt Studio (permission ai.prompt.manage requise).

Les magazines inactifs apparaissent-ils dans le filtre ?

Non. Le dropdown ne liste que les magazines au statut active. Pour inspecter un magazine archivé, contactez un SUPER_ADMIN qui peut le réactiver temporairement.

Quelle différence entre Needs review et Unknown ?

Needs review : Claude a proposé un format avec une confiance intermédiaire (0.60 à 0.85). L'ad a déjà un ad_format_ref_id pré-rempli et passe dans F06 Verify pour confirmation éditoriale rapide. Unknown : Claude n'a rien proposé de fiable (confidence < 0.60), l'ad a ad_format_ref_id = null et remonte dans la queue Triage pour décision gouvernance.

Liens utiles

• Triage IA — agir sur les ads unknown et needs_review détectées
• Prompt Studio — tuner le prompt pour faire baisser le taux unknown
• Uploader une grille tarifaire — combler un catalogue incomplet identifié via le dashboard
• Queue tarifs à compléter — compléter la tarification après création de nouveaux formats