Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Verzionovanie promptov a správa katalógu

Lekcia 14 z 16 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Verzionovanie promptov a správa katalógu
  2. Prečo verzionovať prompty
  3. Štruktúra katalógu
  4. Používanie katalógu v tvojej aplikácii
  5. Verzionovanie s Gitom
  6. Najlepšie postupy
  7. Testovanie katalógu s rollbackom
  8. Kľúčové poznatky

Lekcia aktualizovaná 3. novembra 2026 na základe dokumentácie OpenAI: parametre temperature a top_p sú akceptované len pri úsilí o logické uvažovanie (reasoning effort) nastavenom na none, zatiaľ čo modely GPT-5.6 štandardne uvažujú (medium). Volania, ktoré nastavujú tieto parametre, preto musia špecifikovať reasoning={"effort": "none"} (Responses API) alebo reasoning_effort="none" (Chat Completions). Zdroje: Using GPT-6 · GPT-5.6 Terra.

Verzionovanie promptov a správa katalógu

V produkcii sa tvoje prompty vyvíjajú rovnako ako tvoj kód. Bez verzionovania stratíš prehľad o zmenách, nemôžeš sa vrátiť k predchádzajúcemu stavu a nemáš tušenie, ktorá verzia beží v produkcii. Táto lekcia ti ukáže, ako spravovať prompty ako softvérové artefakty.

Prečo verzionovať prompty

Zmena promptu môže radikálne zmeniť správanie tvojej aplikácie. Na rozdiel od kódu sú tieto zmeny často jemné a ťažko odhaliteľné bez automatizovaných testov: preformulovaná veta, presunuté slovo a model začne nesprávne klasifikovať jeden z desiatich hraničných prípadov. Žiadny štandardný unit test túto medzeru neodhalí, ale podporu to nahlási o tri týždne neskôr ako vágna sťažnosť na zle smerované ticketty.

Verzionovanie rieši štyri odlišné potreby. Po prvé, sledovateľnosť: vedieť, kto čo a kedy zmenil, mení sterilnú tímovú debatu na jednoduchú kontrolu histórie. Po druhé, návrat k predchádzajúcemu stavu (rollback): keď sa objaví regresia, okamžitým cieľom nie je pochopiť prečo, ale obnoviť známe správanie. Po tretie, porovnanie výkonu: to si vyžaduje, aby staršie verzie zostali spustiteľné presne tak, ako boli, s ich pôvodným modelom a nastaveniami. Nakoniec, audit: pre systémy podliehajúce GDPR (Všeobecné nariadenie o ochrane údajov) alebo iným rámcom compliance musíš preukázať, ktoré inštrukcie boli platné k danému dátumu – screenshot nestačí.

Štruktúra katalógu

Trieda PromptCatalog spĺňa tieto potreby s minimálnou infraštruktúrou: jeden priečinok pre každý prompt, jeden JSON súbor pre každú verziu, číslovaný sekvenčne. Každý súbor zhlukuje text systémového promptu spolu s priradeným modelom a teplotou – prompt vyladený na 0,1 a ten istý prompt na 0,7 nie je to isté a ich uzamknutie spolu zabraňuje obnoveniu textu pri zabudnutí na jeho nastavenia.

Pole status sleduje životný cyklus. Verzia začína ako draft (koncept), čo umožňuje prípravu a testovanie bez ovplyvnenia živej prevádzky. Volanie activate ju prepne na active a automaticky degraduje predchádzajúcu verziu na deprecated, čím sa zabezpečí, že v danom čase obsluhuje prevádzku iba jedna verzia. Táto metóda robí rollback triviálnym: reaktivácia predchádzajúcej verzie je jediným volaním, nie nasadením. Tvoja aplikácia volá get_active v produkcii, zatiaľ čo list_versions podporuje revízie a audity.

import json
from datetime import datetime
from pathlib import Path

class PromptCatalog:
    """Správca katalógu promptov s verzionovaní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ží novú verziu promptu."""
        prompt_dir = self.catalog_dir / name
        prompt_dir.mkdir(exist_ok=True)

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

        # Uloženie
        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:
        """Získa prompt podľa názvu a verzie."""
        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:
        """Získa aktívnu verziu 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 verziu 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šetky verzie 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žívanie katalógu v tvojej aplikácii

Na strane volajúceho platí jednoduché pravidlo: tvoj kód neobsahuje žiadny text promptu; vyžiada si aktívnu verziu z katalógu. To udržuje prompty upraviteľné bez dotyku s kódom aplikácie a zabraňuje tomu, aby sa tridsaťriadkové reťazce stratili uprostred funkcie. Metadáta uložené počas ukladania – autor, popis, changelog – nemajú vplyv na vykonávanie, ale robia históriu čitateľnou o šesť mesiacov neskôr, keď si už nikto nepamätá, prečo sa znenie zmenilo.

Kritický detail sa nachádza na konci funkcie classifier_ticket: vrátená odpoveď obsahuje prompt_version. Loguj toto pole pri každom výsledku a analýza incidentov sa stane možnou – budeš vedieť, že zle klasifikované ticketty z utorkového popoludnia všetky pochádzali z verzie v004, bez potreby krížového odkazovania na časové pečiatky nasadenia.

from openai import OpenAI

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

# Uloženie 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á klasifikácia ticketov Zendesk",
        "changelog": "Počiatočná verzia"
    }
)

# V produkcii: použitie aktívnej verzie
def classifier_ticket(ticket_text: str) -> dict:
    """Klasifikuje ticket pomocou aktívneho 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"]
    }

Verzionovanie s Gitom

Pre tímy ukladaj svoje prompty do vyhradeného Git repozitára. Strom nižšie dodržiava jednoduchú konvenciu: jeden priečinok pre každý prompt, obsahujúci jeho definíciu, testovacie prípady a changelog. Udržiavanie testov vedľa promptu, ktorý overujú, nie je kozmetické – pull request upravuje obe veci spoločne a recenzent posudzuje zmenu na základe dôkazov, nie deklarovaného zámeru.

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

YAML tu nahrádza JSON z konkrétneho dôvodu: prompty sú viacriadkové texty a syntax | ich zobrazuje presne tak, ako sú odoslané, bez escapovania alebo blúdnych znakov \n. Git diff na tomto súbore sa číta ako diff prózy – recenzent vidí, že bola pridaná veta. Schéma výstupu cestuje v tom istom súbore, takže kompletná konfigurácia pre volanie sa zmestí 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

Najlepšie postupy

To, čo oddeľuje živý katalóg od archívneho priečinka, sa scvrkáva na niekoľko pravidiel údržby. Udržuj jeden prompt na súbor: miešanie viacerých promptov v jednom dokumente robí diffy nečitateľnými a rollbacky nemožné cieliť. Vynucuj changelog dokumentujúci nie to, čo sa zmenilo – to ukáže diff – ale prečo: „pridaná inštrukcia o viacjazyčných ticketoch na základe spätnej väzby podpory“ má hodnotu desiatich riadkov technického popisu.

Systematicky priraďuj testovaciu sadu ku každému promptu; inak budú používatelia prví, ktorí ti povedia, keď úprava rozbije zabehnuté správanie. Smeruj zmeny promptov cez rovnaký proces kódovej revízie ako samotný kód: prompt, ktorý ide do produkcie bez revízie, produkuje rovnaké prekvapenia ako nerekvidovaný kód. Over, či rollback trvá menej ako minútu, a otestuj ho v pokojný deň, nie počas incidentu. Nakoniec, označ nasadené verzie tagmi, aby si jednoznačne prepojil pozorované správanie s konkrétnym stavom repozitára.

Testovanie katalógu s rollbackom

Nastav PromptCatalog pre tri skutočné prompty z tvojej aplikácie, potom zaznamenaj dve alebo tri verzie každého z nich postupným vylepšovaním inštrukcií v malých krokoch – inštrukcia tónu, pridaná kategória. Verzionovanie preukáže svoju hodnotu práve pri týchto jemných zmenách, pretože práve na ne si nespomenieš, že si ich urobil. Nastav aktiváciu a deaktiváciu a pripoj testovaciu sadu ku každému promptu.

Dokonči to najpoučnejším cvičením: zámerne aktivuj degradovanú verziu, pozoruj regresiu prostredníctvom testov a vykonaj rollback s meraním času. Ak operácia presiahne jednu minútu, oprav postup predtým, než pridáš jediný prompt do katalógu – pomalý rollback nie je rollback, je to zdĺhavý incident.

Kľúčové poznatky

  • Prompty sú softvérové artefakty, ktoré vyžadujú verzionovanie
  • Každá verzia je súbor JSON alebo YAML s metadátami
  • Stav (draft, active, deprecated) umožňuje postupné nasadzovanie
  • Ukladaj prompty do Gitu s testami a changelogom
  • Rollback musí byť okamžitý v prípade regresie