Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Verzování promptů a správa katalogu

Lekce 14 z 16 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Verzování promptů a správa katalogu
  2. Proč verzovat prompty
  3. Struktura katalogu
  4. Použití katalogu v aplikaci
  5. Verzování s Gitem
  6. Osvědčené postupy
  7. Testování katalogu s rollbackem
  8. Klíčové poznatky

Lekce aktualizována 3. listopadu 2026 na základě dokumentace OpenAI: parametry temperature a top_p jsou akceptovány pouze při úsilí o uvažování (reasoning effort) nastaveném na none, zatímco modely GPT-5.6 ve výchozím nastavení uvažují (medium). Volání, která tyto parametry nastavují, musí proto specifikovat reasoning={"effort": "none"} (Responses API) nebo reasoning_effort="none" (Chat Completions). Zdroje: Using GPT-6 · GPT-5.6 Terra.

Verzování promptů a správa katalogu

V produkčním prostředí se tvé prompty vyvíjejí stejně jako tvůj kód. Bez verzování ztrácíš přehled o změnách, nemůžeš se vrátit k předchozí verzi a netušíš, která verze právě běží v produkci. Tato lekce ti ukáže, jak zacházet s prompty jako se softwarovými artefakty.

Proč verzovat prompty

Změna promptu může radikálně změnit chování tvé aplikace. Na rozdíl od kódu jsou tyto změny často nenápadné a bez automatizovaných testů těžko odhalitelné: přeformulovaná věta, přesunuté slovo a model začne u jednoho z deseti hraničních případů chybovat klasifikaci. Žádný standardní unit test tuto mezeru neodhalí, ale zákaznická podpora to nahlásí o tři týdny později jako vágní stížnost na špatně směrované tickety.

Verzování řeší čtyři odlišné potřeby. Zaprvé sledovatelnost: vědět, kdo, co a kdy změnil, promění sterilní týmovou debatu v jednoduchou kontrolu historie. Zadruhé návrat k předchozí verzi (rollback): když se objeví regrese, okamžitým cílem není pochopit proč, ale obnovit známé chování. Zatřetí porovnávání výkonu: to vyžaduje, aby starší verze zůstaly spustitelné přesně tak, jak byly, s původním modelem a nastavením. Nakonec audit: u systémů podléhajících GDPR (Obecné nařízení o ochraně osobních údajů) nebo jiným compliance rámcům musíš prokázat, které instrukce platily k danému datu – screenshot nestačí.

Struktura katalogu

Třída PromptCatalog splňuje tyto potřeby s minimální infrastrukturou: jedna složka pro každý prompt, jeden JSON soubor pro každou verzi, číslované sekvenčně. Každý soubor sdružuje text systémového promptu spolu s přidruženým modelem a teplotou – prompt vyladěný na 0,1 a tentýž prompt na 0,7 nejsou totéž a jejich uzamčení dohromady zabraňuje obnově textu při zapomenutí jeho nastavení.

Pole status sleduje životní cyklus. Verze začíná jako draft (koncept), což umožňuje přípravu a testování bez ovlivnění živého provozu. Volání activate ji přepne na active (aktivní) a automaticky degraduje předchozí verzi na deprecated (zastaralá), čímž zajistí, že v daný okamžik obsluhuje provoz pouze jedna verze. Tato metoda činí rollback triviálním: reaktivace předchozí verze je jediným voláním, nikoliv nasazením. Tvá aplikace volá v produkci get_active, zatímco list_versions podporuje revize a audity.

import json
from datetime import datetime
from pathlib import Path

class PromptCatalog:
    """Správce katalogu promptů s verzováním."""

    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:
        """Uloží novou verzi promptu."""
        prompt_dir = self.catalog_dir / name
        prompt_dir.mkdir(exist_ok=True)

        # Určení čísla verze
        versions = sorted(prompt_dir.glob("v*.json"))
        version = len(versions) + 1
        version_str = f"v{version:03d}"

        # Uložení
        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:
        """Načte prompt podle jména a verze."""
        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:
        """Načte aktivní verzi promptu."""
        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):
        """Aktivuje verzi a deaktivuje ostatní."""
        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]:
        """Vypíše všechny verze promptu."""
        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

Použití katalogu v aplikaci

Na straně volajícího platí jednoduché pravidlo: tvůj kód neobsahuje žádný text promptu; žádá aktivní verzi z katalogu. To udržuje prompty upravitelné bez zásahu do kódu aplikace a zabraňuje tomu, aby se třicítkářské řetězce ztrácely uprostřed funkce. Metadata uložená při ukládání – autor, popis, changelog – nemají žádný vliv na执行, ale činí historii čitelnou o šest měsíců později, když si už nikdo nepamatuje, proč se znění změnilo.

Kritický detail se nachází na konci funkce classifier_ticket: vrácená odpověď zahrnuje prompt_version. Toto pole loguj s každým výsledkem a analýza incidentů se stane možnou – budeš vědět, že špatně klasifikované tickety z úterního odpoledne všechny pocházely z verze v004, aniž bys musel křížově odkazovat časová razítka nasazení.

from openai import OpenAI

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

# Uložení promptu
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": "Automatická klasifikace ticketů Zendesk",
        "changelog": "Počáteční verze"
    }
)

# V produkci: použití aktivní verze
def classifier_ticket(ticket_text: str) -> dict:
    """Klasifikuje ticket pomocí aktivního promptu."""
    prompt_config = catalog.get_active("ticket-classifier")

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

Verzování s Gitem

Pro týmy ukládej své prompty do vyhrazeného Git repozitáře. Níže uvedený strom dodržuje jednoduchou konvenci: jedna složka pro každý prompt, obsahující jeho definici, testovací případy a changelog. Uchovávání testů vedle promptu, který ověřují, není jen kosmetické – pull request upravuje obojí dohromady a recenzent posuzuje změnu na základě důkazů, nikoliv deklarovaného záměru.

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

YAML zde nahrazuje JSON z konkrétního důvodu: prompty jsou víceřádkové texty a syntaxe | je zobrazuje přesně tak, jak jsou odesílány, bez escapování nebo zbloudilých znaků \n. Git diff na tomto souboru vypadá jako diff prózy – recenzent vidí, že byla přidána věta. Schéma výstupu cestuje ve stejném souboru, takže kompletní konfigurace pro volání se vejde do jediného artefaktu.

# 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

Osvědčené postupy

To, co odděluje živý katalog od archivační složky, se redukuje na několik pravidel údržby. Udržuj jeden prompt na soubor: míchání více promptů v jediném dokumentu činí diffy nečitelnými a rollbacky nemožnými cílit. Vynucuj changelog dokumentující nejen co se změnilo – to ukáže diff – ale proč: „přidána instrukce ohledně vícejazyčných ticketů na základě zpětné vazby podpory“ má větší hodnotu než deset řádků technického popisu.

Systematicky přidružuj ke každému promptu sadu testů; jinak ti uživatelé jako první řeknou, když modifikace rozbije zavedené chování. Směruj změny promptů stejným procesem code review jako samotný kód: prompt, který jde do produkce bez revize, produkuje stejná překvapení jako nerevidovaný kód. Ověř, že rollback trvá méně než minutu, a otestuj ho v klidný den, nikoliv během incidentu. Nakonec označ nasazené verze tagy, abys jednoznačně propojil pozorované chování s konkrétním stavem repozitáře.

Testování katalogu s rollbackem

Nastav PromptCatalog pro tři skutečné prompty z tvé aplikace a poté zaznamenej dvě nebo tři verze každého z nich postupným vylepšováním instrukcí v malých krocích – instrukce tónu, přidaná kategorie. Verzování prokazuje svou hodnotu právě u těchto jemných změn, protože právě ty si nebudeš pamatovat, že jsi je provedl. Nastav aktivaci a deaktivaci a ke každému promptu připoj sadu testů.

Dokonči to nejpoučnějším cvičením: záměrně aktivuj degradovanou verzi, pozoruj regresi prostřednictvím testů a proveď rollback s měřením času. Pokud operace přesáhne jednu minutu, oprav proceduru dříve, než do katalogu přidáš jediný prompt – pomalý rollback není rollback, je to zdlouhavý incident.

Klíčové poznatky

  • Prompty jsou softwarové artefakty, které vyžadují verzování
  • Každá verze je soubor JSON nebo YAML s metadaty
  • Status (draft, active, deprecated) umožňuje postupné nasazování
  • Ukládej prompty do Gitu s testy a changelogem
  • Rollback musí být v případě regrese okamžitý