Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Prompt-Versionierung und Katalogverwaltung

Lektion 14 von 16 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Prompt-Versionierung und Katalogverwaltung
  2. Warum Prompts versionieren
  3. Katalogstruktur
  4. Nutzung des Katalogs in Ihrer Anwendung
  5. Versionierung mit Git
  6. Best Practices
  7. Testen des Katalogs mit einem Rollback
  8. Kernaussagen

Lektion aktualisiert am 3. November 2026 basierend auf der OpenAI-Dokumentation: temperature und top_p werden nur mit einem Reasoning-Effort von none akzeptiert, während GPT-5.6-Modelle standardmäßig mit medium rechnerisch arbeiten. Aufrufe, die diese Parameter festlegen, müssen daher reasoning={"effort": "none"} (Responses API) oder reasoning_effort="none" (Chat Completions) angeben. Quellen: Using GPT-6 · GPT-5.6 Terra.

Prompt-Versionierung und Katalogverwaltung

In der Produktion entwickeln sich Ihre Prompts genauso stark wie Ihr Code. Ohne Versionierung verlieren Sie den Überblick über Änderungen, können nicht auf vorherige Versionen zurückgreifen und wissen nicht, welche Version in der Produktion läuft. In dieser Lektion erfahren Sie, wie Sie Prompts als Software-Artefakte verwalten.

Warum Prompts versionieren

Eine Änderung am Prompt kann das Verhalten Ihrer Anwendung radikal verändern. Im Gegensatz zum Code sind diese Änderungen oft subtil und schwer ohne automatisierte Tests zu erkennen: Ein umformulierter Satz, ein verschobenes Wort, und das Modell beginnt, in einem von zehn Grenzfällen falsch zu klassifizieren. Kein Standard-Einheitstest wird diese Lücke aufdecken, aber der Support wird es drei Wochen später als vage Beschwerde über falsch geroutete Tickets melden.

Die Versionierung adressiert vier unterschiedliche Bedürfnisse. Erstens Nachverfolgbarkeit: Zu wissen, wer was und wann geändert hat, verwandelt eine sterile Teamdebatte in eine einfache Überprüfung der Historie. Zweitens Rollback: Wenn eine Regression auftritt, ist das unmittelbare Ziel nicht das Verständnis des Warum, sondern die Wiederherstellung eines bekannten Verhaltens. Drittens Leistungsvergleich: Dies erfordert, dass ältere Versionen genau so ausführbar bleiben wie zuvor, mit ihrem ursprünglichen Modell und seinen Einstellungen. Schließlich Auditierung: Für Systeme, die der DSGVO (General Data Protection Regulation) oder anderen Compliance-Rahmenwerken unterliegen, müssen Sie nachweisen, welche Anweisungen an einem bestimmten Datum galten – ein Screenshot reicht nicht aus.

Katalogstruktur

Die PromptCatalog-Klasse erfüllt diese Bedürfnisse mit minimaler Infrastruktur: Ein Ordner pro Prompt, eine JSON-Datei pro Version, nummeriert sequentiell. Jede Datei bündelt den System-Prompt-Text zusammen mit dem zugehörigen Modell und der Temperatur – ein Prompt, der auf 0,1 abgestimmt ist, und derselbe Prompt bei 0,7 sind nicht dasselbe, und das Festlegen beider zusammen verhindert, dass Text wiederhergestellt wird, während die Einstellungen vergessen werden.

Das Feld status verfolgt den Lebenszyklus. Eine Version beginnt als draft, was Vorbereitung und Tests ohne Beeinflussung des Live-Traffics ermöglicht. Der Aufruf von activate schaltet sie auf active um und demotiert automatisch die vorherige Version auf deprecated, sodass zu jedem Zeitpunkt nur eine Version den Traffic bedient. Diese Methode macht Rollbacks trivial: Die Wiederaktivierung einer früheren Version ist ein einziger Aufruf, keine Bereitstellung. Ihre Anwendung ruft get_active in der Produktion auf, während list_versions Reviews und Audits unterstützt.

import json
from datetime import datetime
from pathlib import Path

class PromptCatalog:
    """Prompt catalog manager with versioning."""

    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:
        """Saves a new version of a prompt."""
        prompt_dir = self.catalog_dir / name
        prompt_dir.mkdir(exist_ok=True)

        # Determine version number
        versions = sorted(prompt_dir.glob("v*.json"))
        version = len(versions) + 1
        version_str = f"v{version:03d}"

        # Save
        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:
        """Retrieves a prompt by name and 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}' not found")
            filepath = versions[-1]
        else:
            filepath = prompt_dir / f"{version}.json"

        return json.loads(filepath.read_text())

    def get_active(self, name: str) -> dict:
        """Retrieves the active version of a 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"No active version for '{name}'"
        )

    def activate(self, name: str, version: str):
        """Activates a version and deactivates others."""
        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]:
        """Lists all versions of a 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

Nutzung des Katalogs in Ihrer Anwendung

Auf der Seite des Aufrufers lautet die Regel einfach: Ihr Code enthält keinen Prompt-Text; er fordert die aktive Version vom Katalog an. Dies hält Prompts modifizierbar, ohne den Anwendungscode zu berühren, und verhindert, dass dreißig-Zeilen-Strings mitten in einer Funktion begraben werden. Metadaten, die während der Speicherung gespeichert werden – Autor, Beschreibung, Änderungsprotokoll – haben keinen Einfluss auf die Ausführung, machen die Historie aber sechs Monate später lesbar, wenn niemand mehr weiß, warum die Formulierung geändert wurde.

Das kritische Detail liegt am Ende von classifier_ticket: Die zurückgegebene Antwort enthält prompt_version. Protokollieren Sie dieses Feld mit jedem Ergebnis, und die Analyse von Vorfällen wird möglich – Sie werden wissen, dass die falsch klassifizierten Tickets am Dienstag nachmittag alle von v004 stammten, ohne Bereitstellungszeitstempel abzugleichen.

from openai import OpenAI

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

# Save a 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": "Automatic classification of Zendesk tickets",
        "changelog": "Initial version"
    }
)

# In production: use the active version
def classifier_ticket(ticket_text: str) -> dict:
    """Classifies a ticket using the active prompt."""
    prompt_config = catalog.get_active("ticket-classifier")

    response = client.responses.create(
        model=prompt_config["model"],
        reasoning={"effort": "none"},  # temperature requires 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"]
    }

Versionierung mit Git

Für Teams speichern Sie Ihre Prompts in einem dedizierten Git-Repository. Der folgende Baum folgt einer einfachen Konvention: Ein Ordner pro Prompt, der seine Definition, Testfälle und Änderungsprotokoll enthält. Tests beiseite zu halten, die sie verifizieren, ist nicht kosmetisch – eine Pull-Request-Änderung modifiziert beides zusammen, und der Prüfer urteilt über die Änderung anhand von Beweisen, nicht anhand der erklärten Absicht.

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

YAML ersetzt hier JSON aus einem spezifischen Grund: Prompts sind mehrzeilige Texte, und die |-Syntax zeigt sie genau so an, wie sie gesendet werden, ohne Escaping oder fremde \n-Zeichen. Ein Git-Diff in dieser Datei liest sich wie ein Prosa-Diff – der Prüfer sieht, dass ein Satz hinzugefügt wurde. Das Ausgabe-Schema reist in derselben Datei mit, sodass die vollständige Konfiguration für einen Aufruf in einem einzigen Artefakt passt.

# 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

Best Practices

Was einen lebendigen Katalog von einem Archiv-Ordner unterscheidet, hängt von ein paar Hausordnungsvorschriften ab. Halten Sie einen Prompt pro Datei: Das Mischen mehrerer Prompts in einem einzigen Dokument macht Diffs unlesbar und Rollbacks unmöglich gezielt auszuführen. Erzwingen Sie ein Änderungsprotokoll, das nicht dokumentiert, was geändert wurde – das zeigt das Diff – sondern warum: “Hinzugefügte Anweisung zu mehrsprachigen Tickets nach Support-Feedback” ist zehn Zeilen technischer Beschreibung wert.

Koppeln Sie systematisch eine Testsuite mit jedem Prompt; sonst werden die Benutzer die ersten sein, die Ihnen sagen, wann eine Änderung etabliertes Verhalten bricht. Leiten Sie Prompt-Änderungen durch denselben Code-Review-Prozess wie den Code selbst: Ein Prompt, der ohne Review in die Produktion geht, erzeugt dieselben Überraschungen wie unüberprüfter Code. Stellen Sie sicher, dass Rollback weniger als eine Minute dauert, und testen Sie es an einem ruhigen Tag, nicht während eines Vorfalls. Markieren Sie schließlich bereitgestellte Versionen mit Tags, um beobachtetes Verhalten eindeutig mit einem bestimmten Repository-Zustand zu verknüpfen.

Testen des Katalogs mit einem Rollback

Richten Sie ein PromptCatalog für drei echte Prompts Ihrer Anwendung ein, und notieren Sie zwei oder drei Versionen jedes Prompts, indem Sie die Anweisungen in kleinen Schritten weiterentwickeln – eine Ton-Anweisung, eine hinzugefügte Kategorie. Die Versionierung beweist ihren Wert bei diesen feingranularen Änderungen, da es genau diese sind, die Sie nicht mehr merken werden, dass Sie sie vorgenommen haben. Richten Sie Aktivierung und Deaktivierung ein, und hängen Sie eine Testsuite an jeden Prompt an.

Beenden Sie mit der lehrreichsten Übung: Aktivieren Sie absichtlich eine degradierte Version, beobachten Sie die Regression über die Tests und führen Sie das Rollback aus, während Sie die Zeit messen. Wenn die Operation mehr als eine Minute dauert, beheben Sie das Verfahren, bevor Sie einen einzigen Prompt zum Katalog hinzufügen – ein langsames Rollback ist kein Rollback, es ist ein prolongierter Vorfall.

Kernaussagen

  • Prompts sind Software-Artefakte, die eine Versionierung erfordern
  • Jede Version ist eine JSON- oder YAML-Datei mit Metadaten
  • Status (draft, active, deprecated) ermöglicht schrittweise Bereitstellung
  • Speichern Sie Prompts in Git mit Tests und einem Änderungsprotokoll
  • Rollback muss im Falle einer Regression sofort erfolgen