Versionering en catalogusbeheer van prompts
Op deze pagina
Les bijgewerkt op 3 november 2026 op basis van OpenAI-documentatie:
temperatureentop_pworden alleen geaccepteerd met een redeneerinspanning vannone, terwijl GPT-5.6-modellen standaard redeneren (medium). Aanroepen die deze parameters instellen, moeten daaromreasoning={"effort": "none"}(Responses API) ofreasoning_effort="none"(Chat Completions) specificeren. Bronnen: Using GPT-6 · GPT-5.6 Terra.
Versionering en catalogusbeheer van prompts
In productie evolueren uw prompts net zo sterk als uw code. Zonder versionering raakt u het overzicht over wijzigingen kwijt, kunt u niet terugrollen en weet u niet welke versie er in productie draait. Deze les laat u zien hoe u prompts als software-artefacten beheert.
Waarom prompts versioneren
Een wijziging in een prompt kan het gedrag van uw applicatie radicaal veranderen. In tegenstelling tot code zijn deze wijzigingen vaak subtiel en moeilijk op te sporen zonder geautomatiseerde tests: een herformuleerde zin, een verplaatst woord, en het model classificeert één op de tien randgevallen verkeerd. Geen enkele standaard unittest vangt dit gat op, maar de supportafdeling meldt het drie weken later als een vage klacht over verkeerd gerouteerde tickets.
Versionering beantwoordt aan vier verschillende behoeften. Ten eerste traceerbaarheid: weten wie wat en wanneer heeft gewijzigd, maakt van een steriel teamdebat een simpele geschiedeniscontrole. Ten tweede rollback: wanneer een regressie optreedt, is het directe doel niet begrijpen waarom, maar bekend gedrag herstellen. Ten derde prestatievergelijking: dit vereist dat oudere versies exact zoals ze waren uitvoerbaar blijven, met hun oorspronkelijke model en instellingen. Tot slot auditing: voor systemen die onder de AVG (Algemene Verordening Gegevensbescherming) of andere compliance-kaders vallen, moet u kunnen aantonen welke instructies op een bepaalde datum van kracht waren—een screenshot volstaat niet.
Catalogusstructuur
De klasse PromptCatalog voorziet in deze behoeften met minimale infrastructuur: één map per prompt, één JSON-bestand per versie, sequentieel genummerd. Elk bestand bundelt de systeem-prompttekst samen met het bijbehorende model en de temperatuur—een prompt afgestemd op 0,1 en dezelfde prompt op 0,7 zijn niet hetzelfde, en ze samen vergrendelen voorkomt dat u tekst herstelt terwijl u de instellingen vergeet.
Het veld status volgt de levenscyclus. Een versie begint als draft, waardoor voorbereiding en testing mogelijk zijn zonder live verkeer te beïnvloeden. Het aanroepen van activate schakelt deze om naar active en degradeert automatisch de vorige versie naar deprecated, zodat er op elk moment slechts één versie verkeer bedient. Deze methode maakt rollback triviaal: het heractiveren van een eerdere versie is één aanroep, geen deployment. Uw applicatie roept in productie get_active aan, terwijl list_versions ondersteuning biedt voor reviews en audits.
import json
from datetime import datetime
from pathlib import Path
class PromptCatalog:
"""Beheerder van promptcatalogus met versionering."""
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:
"""Slaat een nieuwe versie van een prompt op."""
prompt_dir = self.catalog_dir / name
prompt_dir.mkdir(exist_ok=True)
# Bepaal versienummer
versions = sorted(prompt_dir.glob("v*.json"))
version = len(versions) + 1
version_str = f"v{version:03d}"
# Opslaan
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:
"""Haalt een prompt op op naam en versie."""
prompt_dir = self.catalog_dir / name
if version == "latest":
versions = sorted(prompt_dir.glob("v*.json"))
if not versions:
raise FileNotFoundError(f"Prompt '{name}' niet gevonden")
filepath = versions[-1]
else:
filepath = prompt_dir / f"{version}.json"
return json.loads(filepath.read_text())
def get_active(self, name: str) -> dict:
"""Haalt de actieve versie van een prompt op."""
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"Geen actieve versie voor '{name}'"
)
def activate(self, name: str, version: str):
"""Activeert een versie en deactiveert andere."""
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]:
"""Somt alle versies van een prompt op."""
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
De catalogus gebruiken in uw applicatie
Aan de kant van de aanroeper is de regel simpel: uw code bevat geen prompttekst; deze vraagt de actieve versie op uit de catalogus. Hierdoor blijven prompts wijzigbaar zonder dat u de applicatiecode hoeft aan te raken, en voorkomt u dat strings van dertig regels begraven raken midden in een functie. Metadata die tijdens het opslaan wordt bewaard—auteur, beschrijving, changelog—heeft geen effect op de uitvoering, maar maakt de geschiedenis leesbaar zes maanden later, wanneer niemand meer weet waarom de formulering is gewijzigd.
Het cruciale detail bevindt zich aan het einde van classifier_ticket: het geretourneerde antwoord bevat prompt_version. Log dit veld bij elk resultaat, en incidentanalyse wordt mogelijk—u weet dan dat de verkeerd geclassificeerde tickets van dinsdagmiddag allemaal afkomstig waren van v004, zonder dat u deployment-tijdstippen hoeft te kruisverwijzen.
from openai import OpenAI
client = OpenAI()
catalog = PromptCatalog("prompts/")
# Sla een prompt op
catalog.save_prompt(
name="ticket-classifier",
system_prompt="""Je bent een classifier voor supporttickets.
Categoriseer elk ticket als: bug, feature, vraag, facturatie.
Antwoord in JSON met categorie, prioriteit (1-5), samenvatting.""",
model="gpt-5.6-terra",
temperature=0.1,
metadata={
"author": "marie.dupont",
"description": "Automatische classificatie van Zendesk-tickets",
"changelog": "Eerste versie"
}
)
# In productie: gebruik de actieve versie
def classifier_ticket(ticket_text: str) -> dict:
"""Classificeert een ticket met de actieve prompt."""
prompt_config = catalog.get_active("ticket-classifier")
response = client.responses.create(
model=prompt_config["model"],
reasoning={"effort": "none"}, # temperatuur vereist 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"]
}
Versionering met Git
Voor teams is het raadzaam uw prompts in een toegewijde Git-repository op te slaan. De onderstaande boomstructuur volgt een eenvoudige conventie: één map per prompt, bevat de definitie, testcases en changelog. Tests naast de prompt houden die ze verifiëren is geen cosmetische keuze—een pull request wijzigt beide samen, en de reviewer beoordeelt de wijziging op bewijs in plaats van verklaarde intentie.
prompts/
ticket-classifier/
prompt.yaml
tests/
test_cases.json
CHANGELOG.md
invoice-extractor/
prompt.yaml
tests/
test_cases.json
CHANGELOG.md
YAML vervangt hier JSON om een specifieke reden: prompts zijn meerregelige teksten, en de |-syntax geeft ze exact weer zoals verzonden, zonder escaping of verdwaalde \n-tekens. Een Git-diff op dit bestand leest als een proza-diff—de reviewer ziet dat er een zin is toegevoegd. Het uitvoerschema reist mee in hetzelfde bestand, zodat de volledige configuratie voor een aanroep in één artefact past.
# prompts/ticket-classifier/prompt.yaml
name: ticket-classifier
model: gpt-5.6-terra
temperature: 0.1
max_output_tokens: 500
system_prompt: |
Je bent een classifier voor supporttickets.
Categoriseer elk ticket als: bug, feature, vraag, facturatie.
Antwoord in JSON met categorie, prioriteit (1-5), samenvatting.
schema:
type: object
properties:
category:
type: string
enum: [bug, feature, vraag, facturatie]
priority:
type: integer
summary:
type: string
required: [category, priority, summary]
additionalProperties: false
Best practices
Wat een levende catalogus onderscheidt van een archiefmap, komt neer op een paar huishoudelijke regels. Houd één prompt per bestand aan: het mengen van meerdere prompts in één document maakt diffs onleesbaar en rollbacks onmogelijk gericht af te dwingen. Forceer een changelog dat niet documenteert wat er is gewijzigd—de diff toont dat—maar waarom: “instructie over meertalige tickets toegevoegd naar aanleiding van feedback van support” is tien regels technische beschrijving waard.
Koppel systematisch een testsuite aan elke prompt; anders zijn gebruikers de eersten die u vertellen wanneer een wijziging gevestigd gedrag breekt. Leid promptwijzigingen via hetzelfde code review-proces als de code zelf: een prompt die zonder review naar productie gaat, produceert dezelfde verrassingen als ongecontroleerde code. Verifieer dat rollback minder dan een minuut duurt, en test dit op een rustige dag in plaats van tijdens een incident. Markeer tot slot gedeployde versies met tags om waargenomen gedrag eenduidig te koppelen aan een specifieke repository-status.
De catalogus testen met een rollback
Stel een PromptCatalog in voor drie echte prompts uit uw applicatie, en leg vervolgens twee of drie versies van elk vast door de instructies in kleine stappen te evolueren—een toon-instructie, een toegevoegde categorie. Versionering bewijst zijn waarde bij deze fijnkorrelige wijzigingen, omdat dit de wijzigingen zijn die u niet meer zult herinneren. Stel activatie en deactivatie in, en koppel een testsuite aan elke prompt.
Sluit af met de meest instructieve oefening: activeer bewust een gedegradeerde versie, observeer de regressie via tests, en voer de rollback uit terwijl u de tijd neemt. Als de bewerking langer dan één minuut duurt, repareer dan de procedure voordat u ook maar één prompt aan de catalogus toevoegt—een trage rollback is geen rollback, het is een langdurig incident.
Belangrijkste punten
- Prompts zijn software-artefacten die versionering vereisen
- Elke versie is een JSON- of YAML-bestand met metadata
- Status (draft, active, deprecated) maakt gefaseerde deployment mogelijk
- Sla prompts op in Git met tests en een changelog
- Rollback moet bij regressie direct mogelijk zijn