Verzování promptů a správa katalogu
Na této stránce
Lekce aktualizována 3. listopadu 2026 na základě dokumentace OpenAI: parametry
temperatureatop_pjsou akceptovány pouze při úsilí o uvažování (reasoning effort) nastaveném nanone, zatímco modely GPT-5.6 ve výchozím nastavení uvažují (medium). Volání, která tyto parametry nastavují, musí proto specifikovatreasoning={"effort": "none"}(Responses API) neboreasoning_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ý