Éditer et versionner les prompts IA

Ce manuel s'adresse aux SUPER_ADMIN qui maintiennent la qualité de détection IA en itérant sur les prompts Claude Vision. Le Prompt Studio remplace la boucle git commit → PR → CI → deploy par un éditeur en DB avec activation à chaud.

Pourquoi cette feature

Historiquement, le prompt système Claude Vision vivait dans un fichier statique du worker Node.js (ingestion-service/prompts/extract.v5.txt). Changer un mot imposait :

1. Commit local + push.
2. Pull Request + revue.
3. Passage CI (~6 min).
4. Deploy worker (~3 min).
5. Redémarrage du pool de workers.

Soit 15 à 20 minutes pour une itération triviale, ce qui bride la capacité à tester des variantes de prompt. Le Prompt Studio stocke les prompts en base (ai_prompts), expose un endpoint interne que le worker interroge avec un cache TTL de 5 minutes, et permet d'éditer + activer une nouvelle version sans toucher au déploiement.

À savoir

La permission requise est ai.prompt.manage, exclusivement accordée à ROLE_SUPER_ADMIN. Le Prompt Studio n'est pas accessible à la gouvernance : un prompt mal écrit impacte tout le pipeline IA, la décision reste super-admin.

Workflow détaillé

1. Accéder au Studio

Depuis le menu Backstage, section IA, cliquez sur Prompt Studio. L'URL directe est /backstage/prompts.

La liste affiche chaque prompt par name (ex. extract, classify) avec la version active, la date d'activation et l'auteur.

2. Consulter l'historique d'un prompt

Cliquez sur extract pour voir toutes les versions. Chaque ligne affiche :

• Version (entier auto-incrémenté par name).
• Statut : active (badge vert), draft, archived.
• Auteur de création et auteur d'activation.
• Notes libres, ex. tuning sur magazines pharma.

3. Cloner pour éditer

Cliquez sur Cloner en draft depuis la version active. Une nouvelle version v6 s'ouvre en mode édition dans Monaco Editor (coloration syntaxique, pliage, recherche).

Le mode Diff compare côte à côte la version courante et l'active pour visualiser vos changements.

4. Tester en dry-run

Avant d'activer, cliquez sur Tester sur échantillon. Vous pouvez :

• Uploader un PDF test (max 10 Mo).
• Ou sélectionner un import existant dans un magazine de votre choix.

Le backend appelle Claude avec le nouveau prompt et les images de l'échantillon, sans rien persister. La réponse JSON brute s'affiche dans un panneau latéral pour comparaison manuelle avec la version active.

5. Activer la nouvelle version

Cliquez sur Activer. Une double confirmation s'affiche :

1. Modale « Vous êtes sur le point de remplacer la version active v5 par v6. Continuer ? ».
2. Champ de texte à remplir avec le nom du prompt (extract) pour confirmer.

L'activation est transactionnelle :

BEGIN;
UPDATE ai_prompts SET is_active = FALSE WHERE name = 'extract';
UPDATE ai_prompts SET is_active = TRUE, activated_at = NOW(), activated_by_id = ?
  WHERE id = ?;
COMMIT;

L'index unique partiel idx_ai_prompts_active_per_name garantit qu'un seul is_active = true coexiste par name. Un événement d'audit ai.prompt.activated est écrit.

6. Propagation vers les workers

Les workers Node.js interrogent GET /api/internal/prompts/extract/active avec un cache TTL de 5 minutes. Après activation, attendez au plus 5 minutes pour que tous les workers récupèrent la nouvelle version. Un bouton Forcer le refresh global envoie un signal Cache-Control: max-age=0 et ramène le délai à moins de 10 secondes.

Fallback fichier

Si l'endpoint interne est indisponible (API down, timeout), le worker retombe automatiquement sur le fichier statique versionné dans l'image Docker (extract.v5.txt). Le pipeline ne s'arrête jamais : fail-open strict.

Bonnes pratiques de prompt

Structure contractuelle JSON

Le prompt extract doit imposer une sortie JSON stricte avec les clés attendues (ads: [{ bbox, formatCode, confidence }]). Formulez explicitement : Réponds uniquement en JSON, sans texte avant ni après, respecte le schéma suivant….

Instructions en français

Claude Sonnet 4.5 performe très bien en français et la cohérence linguistique avec les libellés de magazines améliore la reconnaissance. Évitez le mélange FR/EN dans le même prompt.

Few-shot ciblé

Incluez 2 à 3 exemples réels de bonne détection en fin de prompt (section <exemples>). Privilégiez des exemples couvrant les cas limites (spread, gatefold, faux positifs éditoriaux) plutôt que des cas triviaux.

Ne pas injecter le catalogue dans le prompt en dur

Le worker injecte dynamiquement la liste des AdFormat actifs du magazine dans une section <catalog> au moment de l'appel (voir F-AD-CATALOG addendum A1). Votre prompt doit contenir un placeholder du type Voici le catalogue des formats disponibles pour ce magazine : <catalog/>.

Cas limites

Rollback vers une version antérieure

Ouvrez l'historique, sélectionnez v4, cliquez sur Réactiver cette version. La double confirmation s'applique. La v5 et v6 basculent en archived, la v4 redevient active.

Deux super-admins éditent simultanément

Le Prompt Studio n'implémente pas de lock optimiste en v1. Si deux admins créent en parallèle v6 et v7 en clonant v5, les deux drafts coexistent. Le premier qui clique sur Activer gagne ; le second voit sa version passer en draft et doit la cloner à nouveau depuis la version active.

Prompt cassé après activation

Si Claude commence à renvoyer du JSON invalide après une activation, le worker log l'erreur et tombe sur le fallback fichier statique pour les prochains batchs. Réactivez la version précédente via l'historique pour revenir à un état sain en moins de 10 secondes (avec Forcer le refresh global).

Suppression d'une version

Impossible. Toutes les versions sont conservées pour la traçabilité. Seul le statut (active, draft, archived) change. Utilisez Archiver pour masquer une version obsolète de la liste principale (filtrable via la case Afficher les archivées).

FAQ

A/B testing supporté ?

Non en v1. Un seul prompt actif par name à un instant T. Un vrai A/B nécessiterait un splitter côté worker et des métriques de comparaison qui sont reportés en v2.

L'activation impacte-t-elle les détections passées ?

Non. Les détections historiques restent telles qu'elles ont été stockées. Seuls les batchs ingérés après activation utilisent la nouvelle version. Pour re-détecter un import avec la nouvelle version, utilisez le bouton Relancer la détection dans Catalogue > Imports.

Puis-je comparer deux versions arbitraires ?

Oui. Dans l'historique, cochez deux versions puis cliquez sur Comparer. Le diff side-by-side s'affiche dans une modale, avec les changements ligne par ligne.

Combien de versions peut-on garder par prompt ?

Pas de limite technique. L'index unique partiel reste léger (une ligne par name). Au-delà de 50 versions, filtrez via Afficher les archivées pour nettoyer l'affichage.

Quel modèle Claude est utilisé ?

Le worker utilise claude-sonnet-4-5 (identifiant côté SDK). Le Prompt Studio ne change pas le modèle, seulement le prompt système. Pour changer de modèle, une modification du worker reste nécessaire (config env).

Les notes sont-elles visibles par toute la gouvernance ?

Les notes sont libres mais ne sont pas exposées hors du Prompt Studio. Utilisez-les pour documenter les intentions (fix détection gatefold COVER_4 sur Pharma magazines) à destination des autres super-admins.

Liens utiles

• Dashboard apprentissage IA — mesurer l'effet d'un changement de prompt
• Triage IA — traiter les détections ambiguës générées par un prompt en cours de tuning
• Uploader une grille tarifaire — alimenter le catalogue que le prompt va exploiter