Tests canari pour modèles IA : guide CI pratique

Introduction

Les APIs de modèles changent souvent — parfois subtilement. Un prompt qui renvoyait du JSON valide hier peut renvoyer du texte incongru aujourd’hui. Les tests canari (prompts canaris) te permettent de détecter ces changements silencieux avant qu’ils n’affectent tes utilisateurs. Ce guide pratique te donne un playbook réplicable : prompts exemples, stockage de référence (hash), intégration CI, seuils d’alerte et méthodes tolérantes.

Pourquoi implémenter des tests canari

Une seule rupture silencieuse peut casser des workflows producteurs de valeur : extraction de factures, génération de JSON, ou parsers automatisés. Les tests canari sont une méthode économique pour :

• détecter rapidement une dégradation (pas besoin d’un humain 24/7),
• automatiser la surveillance sur ton pipeline CI/cron,
• décider automatiquement d’une stratégie de mitigation (fallback, mirror, alerte).

Recommandation pratique : commence avec 20–50 prompts canaris couvrant tes cas critiques (format, structure, résumé, conversion). Ce range (20–50) est celui utilisé dans notre plan de canary (references/canary-test-plan.md) et équilibre bruit vs couverture.

Choisir et écrire tes prompts canaris

Objectif : créer des prompts stables mais sensibles aux régressions qui t’intéressent. Varie le format :

• Extraction structurée (ex: “Donne-moi un JSON contenant {date, montant}”)
• Transformation (ex: “Convertis ce texte Markdown en HTML minimal”)
• Synthèse avec contraintes (ex: “Résume en 3 bullet points sans générer d’opinion”)
• Parsing rigide (ex: “Renvoie exactement 3 champs séparés par des tabulations”)

Bonnes pratiques :

• Écris les prompts en anglais ou français selon l’usage en production (cohérence),
• Ajoute une instruction qui fixe la forme de sortie (“Réponds strictement en JSON”).
• Inclue des cas limites réels (extrait mal formé, date ambigüe),
• Numérote les prompts pour faciliter le mapping vers les sorties de référence.

Exemple rapide (prompt canari type) :

{
  "id": "canary-17",
  "prompt": "Extrait la date et le montant du texte suivant et renvoie un JSON {\"date\":..., \"amount\":...} : 'Facture du 2026-05-20 - Total: 1 234,56 €'",
  "expectation": "JSON with keys date and amount"
}

Référence initiale : stocker les sorties et leurs hashes

Procédure :

1. Pour chaque prompt canari, exécute-le et stocke la réponse brute dans un emplacement sécurisé (ex: S3 privé, artefacts CI).
2. Calcule le SHA256 de la sortie brute et enregistre-le dans un fichier de référence (ex: canary_reference.sha256).
3. Stocke aussi les headers pertinents : X-Model, X-Model-Version, Date, Request-ID.

Pourquoi le hash ? Un hash te dit si la sortie a changé, sans stocker de gros blobs. Pour la reproductibilité, conserve aussi la sortie brute (au moins X jours). Dans notre plan (references/canary-test-plan.md) on recommande de garder prompts + sorties + hashes pendant 30–90 jours selon criticité.

Snippet : calculer un hash (bash)

sha256sum response_canary-17.txt >> canary_reference.sha256

Intégration CI / cron : comment automatiser les runs

Options d’exécution : daily cron (basse criticité) ou per-deploy / per-push (haute criticité). Intègre le job dans ta CI existante : GitHub Actions, GitLab CI, Jenkins, etc.

Étapes typiques du job :

1. Récupérer la liste de prompts canaris (canary_prompts.json)
2. Appeler l’API modèle pour chaque prompt (en parallèle raisonnable)
3. Enregistrer la sortie brute + headers
4. Calculer le hash et comparer au fichier de référence
5. Si seuil franchi → déclencher mitigation/alerte

Exemple minimal : scripts/canary-check.sh (voir le repo) fait exactement ça : exécute les prompts, calcule les hashes et renvoie un code de sortie non nul si le nombre d’écarts dépasse le seuil.

Seuils et actions recommandés :

• Si >= 2 prompts changent sur 20 en 24h → ouvrir un incident automatique.
• Si 1 prompt change → enregistrer et attendre la confirmation (retentir au prochain run) pour éviter les faux positifs.

Mitigations automatiques possibles :

• Bascule vers un mirror modèle (si disponible),
• Activer un fallback heuristique (parser local) pour les tâches critiques,
• Poster une alerte Slack/Email et créer un ticket backlog.

Détection sémantique (tolérance aux paraphrases)

Un hash binaire est sensible aux paraphrases légères qui peuvent être acceptables. Pour une détection plus tolérante :

• Utilise des embeddings (sim. cosine) entre la sortie actuelle et la sortie de référence ;
• Définis un seuil sémantique (ex: similarité > 0.92) pour considérer la sortie inchangée ;
• Combine les deux méthodes : d’abord hash (détection stricte), puis embedding pour confirmer si le changement est fonctionnel ou juste phrastique.

Cette approche réduit les faux positifs quand le modèle reformule sans casser la structure attendue.

Limites et pièges à connaître

• Les changements de modèle officiels (maj, prompt-tuning) peuvent changer la sortie sans être des régressions — vérifie les headers X-Model et notes de release avant alerte.
• Les sorties non déterministes (temps, ids générés) doivent être normalisées avant hashing (strip timestamps, UUIDs).
• Les tests canari ne remplacent pas une suite QA complète : ils détectent des signaux, pas tous les bugs.

Checklist de normalisation :

• Supprimer dates/UIDs variables avant hash,
• Convertir les floats/formatages locaux à un canonical form,
• Forcer l’ordre des clés JSON avant hash,
• Échapper ou retirer métadonnées non déterministes (Request-ID).

Playbook d’urgence (si un run échoue)

1. Vérifier les headers X-Model et la release note du fournisseur.
2. Retester manuellement les prompts qui ont changé.
3. Si c’est une régression : basculer le traffic critique sur le mirror ou la version précédente (si possible).
4. Ouvrir un ticket avec logs + sorties brutes + hashes.
5. Rétablir la surveillance après correction.

Questions fréquentes

Q — Combien de prompts me faut-il ? R — Commence par 20. Ajoute des prompts jusqu’à couvrir tes chemins critiques.

Q — Doit-on stocker les sorties en clair ? R — Oui si elles ne contiennent pas de PII. Sinon chiffrement et règles de rétention strictes.

Q — Un changement sémantique léger est-il toujours un problème ? R — Non. Utilise la comparaison sémantique pour filtrer les paraphrases acceptables.

Ressources et références

• Plan et checklist canary : references/canary-test-plan.md
• Exemple de script : references/scripts/canary-check.sh (dans le skill)
• Bonnes pratiques git/PR : references/pr-workflow-tempfiles-cleanup.md

---

Ce guide te donne une marche à suivre actionnable pour surveiller silencieusement tes intégrations IA. Si tu veux, je crée la PR avec cet article + placeholder image maintenant.