Verzionovanie promptov a správa katalógu
Na tejto strane
Lekcia aktualizovaná 3. novembra 2026 na základe dokumentácie OpenAI: parametre
temperatureatop_psú akceptované len pri úsilí o logické uvažovanie (reasoning effort) nastavenom nanone, zatiaľ čo modely GPT-5.6 štandardne uvažujú (medium). Volania, ktoré nastavujú tieto parametre, preto musia špecifikovaťreasoning={"effort": "none"}(Responses API) aleboreasoning_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