Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Versionning de prompts et gestion de catalogue

Lektion 14 av 16 Uppdaterad 3 november 2026 Utvecklare
På denna sida
  1. Versionning de prompts et gestion de catalogue
  2. Pourquoi versionner les prompts
  3. Structure du catalogue
  4. Utiliser le catalogue dans ton application
  5. Versionning avec Git
  6. Bonnes pratiques
  7. Tester le catalogue avec un retour arrière
  8. Viktiga punkter

Leçon mise à jour le 3 novembre 2026 selon la documentation OpenAI : temperature et top_p ne sont acceptés qu’avec un effort de raisonnement de none, alors que les modèles GPT-5.6 raisonnent par défaut (medium). Les appels définissant ces paramètres doivent donc spécifier reasoning={"effort": "none"} (API Responses) ou reasoning_effort="none" (Chat Completions). Sources : Utilisation de GPT-6 · GPT-5.6 Terra.

Versionning de prompts et gestion de catalogue

En production, tes prompts évoluent tout autant que ton code. Sans versionning, tu perds le fil des modifications, tu ne peux pas revenir en arrière et tu ignores quelle version tourne en production. Cette leçon t’apprend à gérer tes prompts comme des artefacts logiciels.

Pourquoi versionner les prompts

Une modification de prompt peut radicalement changer le comportement de ton application. Contrairement au code, ces changements sont souvent subtils et difficiles à détecter sans tests automatisés : une phrase reformulée, un mot déplacé, et le modèle commence à mal classer un cas limite sur dix. Aucun test unitaire standard ne capturera cet écart, mais le support le signalera trois semaines plus tard sous forme d’une plainte vague concernant des tickets mal orientés.

Le versionning répond à quatre besoins distincts. Premièrement, la traçabilité : savoir qui a changé quoi et quand transforme un débat d’équipe stérile en une simple vérification d’historique. Deuxièmement, le retour arrière (rollback) : lorsqu’une régression apparaît, l’objectif immédiat n’est pas de comprendre pourquoi, mais de restaurer un comportement connu. Troisièmement, la comparaison de performances : cela exige que les anciennes versions restent exécutables exactement telles qu’elles étaient, avec leur modèle et leurs paramètres d’origine. Enfin, l’audit : pour les systèmes soumis au RGPD (Règlement général sur la protection des données) ou à d’autres cadres de conformité, tu dois démontrer quelles instructions étaient en vigueur à une date donnée ; une capture d’écran ne suffit pas.

Structure du catalogue

La classe PromptCatalog répond à ces besoins avec une infrastructure minimale : un dossier par prompt, un fichier JSON par version, numérotés séquentiellement. Chaque fichier regroupe le texte du prompt système ainsi que le modèle et la température associés : un prompt réglé à 0,1 et le même prompt à 0,7 ne sont pas la même chose, et les verrouiller ensemble empêche de restaurer le texte en oubliant ses paramètres.

Le champ status suit le cycle de vie. Une version commence par draft, permettant la préparation et les tests sans affecter le trafic en direct. L’appel à activate la fait passer à active et rétrograde automatiquement la version précédente en deprecated, garantissant qu’une seule version sert le trafic à tout moment. Cette méthode rend le retour arrière trivial : réactiver une version antérieure est un simple appel, pas un déploiement. Ton application appelle get_active en production, tandis que list_versions prend en charge les revues et les audits.

import json
from datetime import datetime
from pathlib import Path

class PromptCatalog:
    """Gestionnaire de catalogue de prompts avec versionning."""

    def __init__(self, catalog_dir: str = "prompts/"):
        self.catalog_dir = Path(catalog_dir)
        self.catalog_dir.mkdir(parents=True, exist_ok=True)

    def save_prompt(self, name: str, system_prompt: str,
                    model: str, temperature: float,
                    metadata: dict = None) -> str:
        """Enregistre une nouvelle version d'un prompt."""
        prompt_dir = self.catalog_dir / name
        prompt_dir.mkdir(exist_ok=True)

        # Déterminer le numéro de version
        versions = sorted(prompt_dir.glob("v*.json"))
        version = len(versions) + 1
        version_str = f"v{version:03d}"

        # Sauvegarder
        prompt_data = {
            "name": name,
            "version": version_str,
            "created_at": datetime.now().isoformat(),
            "model": model,
            "temperature": temperature,
            "system_prompt": system_prompt,
            "metadata": metadata or {},
            "status": "draft"  # draft | active | deprecated
        }

        filepath = prompt_dir / f"{version_str}.json"
        filepath.write_text(json.dumps(prompt_data, indent=2,
                                        ensure_ascii=False))

        return version_str

    def get_prompt(self, name: str,
                   version: str = "latest") -> dict:
        """Récupère un prompt par nom et version."""
        prompt_dir = self.catalog_dir / name

        if version == "latest":
            versions = sorted(prompt_dir.glob("v*.json"))
            if not versions:
                raise FileNotFoundError(f"Prompt '{name}' introuvable")
            filepath = versions[-1]
        else:
            filepath = prompt_dir / f"{version}.json"

        return json.loads(filepath.read_text())

    def get_active(self, name: str) -> dict:
        """Récupère la version active d'un prompt."""
        prompt_dir = self.catalog_dir / name
        for filepath in sorted(prompt_dir.glob("v*.json"),
                               reverse=True):
            data = json.loads(filepath.read_text())
            if data["status"] == "active":
                return data
        raise FileNotFoundError(
            f"Aucune version active pour '{name}'"
        )

    def activate(self, name: str, version: str):
        """Active une version et désactive les autres."""
        prompt_dir = self.catalog_dir / name

        for filepath in prompt_dir.glob("v*.json"):
            data = json.loads(filepath.read_text())
            if data["version"] == version:
                data["status"] = "active"
            elif data["status"] == "active":
                data["status"] = "deprecated"
            filepath.write_text(json.dumps(data, indent=2,
                                            ensure_ascii=False))

    def list_versions(self, name: str) -> list[dict]:
        """Liste toutes les versions d'un prompt."""
        prompt_dir = self.catalog_dir / name
        versions = []
        for filepath in sorted(prompt_dir.glob("v*.json")):
            data = json.loads(filepath.read_text())
            versions.append({
                "version": data["version"],
                "status": data["status"],
                "created_at": data["created_at"],
                "model": data["model"]
            })
        return versions

Utiliser le catalogue dans ton application

Côté appelant, la règle est simple : ton code ne contient aucun texte de prompt ; il demande la version active au catalogue. Cela garde les prompts modifiables sans toucher au code de l’application et empêche les chaînes de trente lignes de s’enterrer au milieu d’une fonction. Les métadonnées enregistrées lors du stockage (auteur, description, journal des modifications) n’ont aucun effet sur l’exécution, mais rendent l’historique lisible six mois plus tard, quand personne ne se souvient pourquoi la formulation a changé.

Le détail critique se trouve à la fin de classifier_ticket : la réponse retournée inclut prompt_version. Journalise ce champ avec chaque résultat, et l’analyse des incidents devient possible : tu sauras que les tickets mal classés de mardi après-midi provenaient tous de la v004, sans avoir à recouper les horodatages de déploiement.

from openai import OpenAI

client = OpenAI()
catalog = PromptCatalog("prompts/")

# Enregistrer un prompt
catalog.save_prompt(
    name="ticket-classifier",
    system_prompt="""You are a support ticket classifier.
Categorize each ticket as: bug, feature, question, billing.
Respond in JSON with category, priority (1-5), summary.""",
    model="gpt-5.6-terra",
    temperature=0.1,
    metadata={
        "author": "marie.dupont",
        "description": "Classification automatique des tickets Zendesk",
        "changelog": "Version initiale"
    }
)

# En production : utiliser la version active
def classifier_ticket(ticket_text: str) -> dict:
    """Classe un ticket en utilisant le prompt actif."""
    prompt_config = catalog.get_active("ticket-classifier")

    response = client.responses.create(
        model=prompt_config["model"],
        reasoning={"effort": "none"},  # temperature nécessite effort none
        instructions=prompt_config["system_prompt"],
        input=ticket_text,
        temperature=prompt_config["temperature"]
    )

    return {
        "result": json.loads(response.output_text),
        "prompt_version": prompt_config["version"]
    }

Versionning avec Git

Pour les équipes, stocke tes prompts dans un dépôt Git dédié. L’arborescence ci-dessous suit une convention simple : un dossier par prompt, contenant sa définition, ses cas de test et son journal des modifications. Garder les tests aux côtés du prompt qu’ils vérifient n’est pas cosmétique : une pull request modifie les deux ensemble, et le réviseur juge le changement sur des preuves plutôt que sur l’intention déclarée.

prompts/
  ticket-classifier/
    prompt.yaml
    tests/
      test_cases.json
    CHANGELOG.md
  invoice-extractor/
    prompt.yaml
    tests/
      test_cases.json
    CHANGELOG.md

YAML remplace ici JSON pour une raison précise : les prompts sont des textes multilignes, et la syntaxe | les affiche exactement tels qu’envoyés, sans échappement ni caractères \n parasites. Un diff Git sur ce fichier se lit comme un diff de prose : le réviseur voit qu’une phrase a été ajoutée. Le schéma de sortie voyage dans le même fichier, afin que la configuration complète d’un appel tienne dans un seul artefact.

# prompts/ticket-classifier/prompt.yaml
name: ticket-classifier
model: gpt-5.6-terra
temperature: 0.1
max_output_tokens: 500
system_prompt: |
  You are a support ticket classifier.
  Categorize each ticket as: bug, feature, question, billing.
  Respond in JSON with category, priority (1-5), summary.
schema:
  type: object
  properties:
    category:
      type: string
      enum: [bug, feature, question, billing]
    priority:
      type: integer
    summary:
      type: string
  required: [category, priority, summary]
  additionalProperties: false

Bonnes pratiques

Ce qui sépare un catalogue vivant d’un dossier d’archive tient à quelques règles d’entretien. Garde un prompt par fichier : mélanger plusieurs prompts dans un seul document rend les diffs illisibles et les retours en arrière impossibles à cibler. Impose un journal des modifications documentant non pas ce qui a changé (le diff le montre), mais pourquoi : « ajout d’une instruction sur les tickets multilingues suite aux retours du support » vaut dix lignes de description technique.

Associe systématiquement une suite de tests à chaque prompt ; sinon, ce sont les utilisateurs qui te diront les premiers quand une modification casse un comportement établi. Fais passer les changements de prompts par le même processus de revue de code que le code lui-même : un prompt qui va en production sans revue produit les mêmes surprises qu’un code non revu. Vérifie que le retour arrière prend moins d’une minute et teste-le un jour calme plutôt que pendant un incident. Enfin, marque les versions déployées avec des tags pour lier sans ambiguïté le comportement observé à un état spécifique du dépôt.

Tester le catalogue avec un retour arrière

Configure un PromptCatalog pour trois vrais prompts de ton application, puis enregistre deux ou trois versions de chacun en faisant évoluer les instructions par petites étapes : une instruction de ton, une catégorie ajoutée. Le versionning prouve sa valeur sur ces changements fins, car ce sont ceux dont tu ne te souviendras pas. Mets en place l’activation et la désactivation, et attache une suite de tests à chaque prompt.

Termine par l’exercice le plus instructif : active délibérément une version dégradée, observe la régression via les tests, et exécute le retour arrière en le chronométrant. Si l’opération dépasse une minute, corrige la procédure avant d’ajouter un seul prompt au catalogue : un retour arrière lent n’est pas un retour arrière, c’est un incident prolongé.

Viktiga punkter

  • Les prompts sont des artefacts logiciels qui nécessitent un versionning
  • Chaque version est un fichier JSON ou YAML avec des métadonnées
  • Le statut (draft, active, deprecated) permet un déploiement progressif
  • Stocke les prompts dans Git avec des tests et un journal des modifications
  • Le retour arrière doit être instantané en cas de régression