Prompt verziókezelés és katalógusmenedzsment
Ezen az oldalon
Lecke frissítve: 2026. november 3. az OpenAI dokumentációja alapján: a
temperatureés atop_pparaméterek csaknonegondolkodási erőfeszítés (reasoning effort) mellett fogadhatók el, míg a GPT-5.6 modellek alapértelmezetten (medium) gondolkodnak. Az ezeket a paramétereket beállító hívásoknak ezért expliciten meg kell adniuk areasoning={"effort": "none"}(Responses API) vagyreasoning_effort="none"(Chat Completions) beállítást. Források: GPT-6 használata · GPT-5.6 Terra.
Prompt verziókezelés és katalógusmenedzsment
Éles környezetben a promptjaid ugyanannyit fejlődnek, mint a kódod. Verziókezelés nélkül elveszíted a változások nyomon követésének lehetőségét, nem tudsz visszagörgetni (rollback), és fogalmad sincs, melyik verzió fut éppen élesben. Ez a lecke bemutatja, hogyan kezeld a promptokat szoftveres artifactként.
Miért szükséges a promptok verziókezelése?
Egy prompt módosítása drasztikusan megváltoztathatja az alkalmazásod viselkedését. A kóddal ellentétben ezek a változások gyakran finomak, és automatizált tesztek nélkül nehezen észlelhetők: egy átfogalmazott mondat, egy elmozdított szó, és a modell már minden tizedik határesetet rosszul osztályozza. Ezt a rést egyetlen szabványos unit teszt sem fogja elkapni, de az ügyfélszolgálat három hét múlva jelezni fogja homályos panaszok formájában a rosszul irányított jegyek miatt.
A verziókezelés négy különböző igényt elégít ki. Először is a nyomon követhetőséget: annak ismerete, hogy ki, mit és mikor változtatott, egy meddő csapatvitát egyszerű történeti ellenőrzéssé alakít. Másodszor a visszagörgetést (rollback): amikor regresszió lép fel, az azonnali cél nem annak megértése, hogy miért történt, hanem az ismert működés helyreállítása. Harmadszor a teljesítmény összehasonlítását: ehhez szükséges, hogy a régebbi verziók pontosan úgy maradjanak végrehajthatók, ahogy eredetileg voltak, a saját modelljükkel és beállításaikkal. Végül az auditálást: az GDPR (Általános Adatvédelmi Rendelet) vagy egyéb megfelelőségi keretrendszerek hatálya alá eső rendszereknél igazolnod kell, hogy egy adott dátumon mely utasítások voltak érvényben – egy képernyőfotó erre nem elegendő.
Katalógus szerkezete
A PromptCatalog osztály minimális infrastruktúrával elégíti ki ezeket az igényeket: promptonként egy mappa, verziónként egy JSON fájl, szekvenciálisan számozva. Minden fájl csomagolja a rendszerprompt szövegét a hozzá tartozó modellel és hőmérséklettel (temperature) együtt – egy 0,1-re hangolt prompt és ugyanaz a prompt 0,7-en nem ugyanaz, és ezek együttes rögzítése megakadályozza, hogy a szöveget visszaállítsd, miközben elfelejted a beállításait.
A status mező követi nyomon az életciklust. Egy verzió draft (tervezet) állapotban indul, lehetővé téve az előkészítést és tesztelést az élő forgalom befolyásolása nélkül. Az activate hívása active (aktív) állapotra váltja, és automatikusan deprecated (elavult) állapotba helyezi az előző verziót, biztosítva, hogy bármely időpillanatban csak egy verzió szolgálja ki a forgalmat. Ez a módszer triviálissá teszi a visszagörgetést: egy korábbi verzió újraaktiválása egyetlen hívás, nem pedig egy teljes telepítés. Az alkalmazásod éles környezetben a get_active metódust hívja, míg a list_versions támogatja az átvizsgálást és az auditálást.
import json
from datetime import datetime
from pathlib import Path
class PromptCatalog:
"""Prompt katalógus kezelő verziókezeléssel."""
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:
"""Elmenti a prompt egy új verzióját."""
prompt_dir = self.catalog_dir / name
prompt_dir.mkdir(exist_ok=True)
# Verziószám meghatározása
versions = sorted(prompt_dir.glob("v*.json"))
version = len(versions) + 1
version_str = f"v{version:03d}"
# Mentés
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:
"""Lekéri a promptot név és verzió alapján."""
prompt_dir = self.catalog_dir / name
if version == "latest":
versions = sorted(prompt_dir.glob("v*.json"))
if not versions:
raise FileNotFoundError(f"Prompt '{name}' nem található")
filepath = versions[-1]
else:
filepath = prompt_dir / f"{version}.json"
return json.loads(filepath.read_text())
def get_active(self, name: str) -> dict:
"""Lekéri a prompt aktív verzióját."""
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"Nincs aktív verzió ehhez: '{name}'"
)
def activate(self, name: str, version: str):
"""Aktivál egy verziót és deaktiválja a többit."""
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]:
"""Felsorolja a prompt összes verzióját."""
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
A katalógus használata az alkalmazásban
A hívó oldalán a szabály egyszerű: a kódod nem tartalmaz prompt szöveget; lekéri az aktív verziót a katalógusból. Ez lehetővé teszi a promptok módosítását az alkalmazáskód érintése nélkül, és megakadályozza, hogy harmincsoros stringek temetkezzenek el egy függvény közepén. A tárolás során elmentett metaadatok – szerző, leírás, változásnapló – nincs hatással a végrehajtásra, de olvashatóvá teszik a történetet hat hónap múlva, amikor már senki nem emlékszik, miért változott a megfogalmazás.
A kritikus részlet a classifier_ticket végén található: a visszatérő válasz tartalmazza a prompt_version mezőt. Naplózd ezt a mezőt minden eredménnyel együtt, és lehetővé válik az incidenselemzés – tudni fogod, hogy a keddi délután rosszul osztályozott jegyek mind a v004-es verzióból származtak, anélkül, hogy össze kellene vetned a telepítési időbélyegeket.
from openai import OpenAI
client = OpenAI()
catalog = PromptCatalog("prompts/")
# Prompt mentése
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": "Zendesk jegyek automatikus osztályozása",
"changelog": "Kezdeti verzió"
}
)
# Éles környezetben: az aktív verzió használata
def classifier_ticket(ticket_text: str) -> dict:
"""Osztályoz egy jegyet az aktív prompt segítségével."""
prompt_config = catalog.get_active("ticket-classifier")
response = client.responses.create(
model=prompt_config["model"],
reasoning={"effort": "none"}, # a temperature megköveteli a 'none' erőfeszítést
instructions=prompt_config["system_prompt"],
input=ticket_text,
temperature=prompt_config["temperature"]
)
return {
"result": json.loads(response.output_text),
"prompt_version": prompt_config["version"]
}
Verziókezelés Gittel
Csapatok számára tárold a promptjaidat egy dedikált Git tárolóban. Az alábbi fastruktúra egy egyszerű konvenciót követ: promptonként egy mappa, amely tartalmazza a definíciót, a teszt eseteket és a változásnaplót. A teszteknek a hozzájuk tartozó prompt mellett tartása nem csupán kozmetikai kérdés – egy pull request mindkettőt egyszerre módosítja, és a recenzens bizonyítékok alapján ítéli meg a változást, nem pedig a deklarált szándék alapján.
prompts/
ticket-classifier/
prompt.yaml
tests/
test_cases.json
CHANGELOG.md
invoice-extractor/
prompt.yaml
tests/
test_cases.json
CHANGELOG.md
A YAML itt egy speciális okból váltja fel a JSON-t: a promptok több soros szövegek, és a | szintaxis pontosan úgy jeleníti meg őket, ahogy elküldésre kerülnek, escape karakterek vagy téves \n karakterek nélkül. Egy Git diff ezen a fájlon úgy olvasható, mint egy prózai diff – a recenzens látja, hogy egy mondat hozzáadásra került. A kimeneti séma ugyanabban a fájlban utazik, így egy hívás teljes konfigurációja egyetlen artifactben elfér.
# 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
Legjobb gyakorlatok
Amit egy élő katalógust megkülönböztet egy archivált mappától, az néhány karbantartási szabályon múlik. Tarts egy promptot egy fájlban: több prompt keverése egyetlen dokumentumban olvashatatlanná teszi a diffeket és lehetetlenné a célzott visszagörgetést. Érvényesíts egy változásnaplót, amely nem azt dokumentálja, hogy mi változott – ezt mutatja a diff –, hanem azt, hogy miért: „utasítás hozzáadása a többnyelvű jegyekhez az ügyfélszolgálati visszajelzések alapján“ többet ér tíz sor technikai leírásnál.
Rendszeresen társíts tesztsorozatot minden promptához; ellenkező esetben a felhasználók lesznek az elsők, akik szólnak, ha egy módosítás megtöri a bevált működést. Vezesd át a prompt változásokat ugyanazon a kódreview folyamaton, mint magát a kódot: egy review nélkül élesbe kerülő prompt ugyanolyan meglepetéseket okoz, mint a nem review-özött kód. Ellenőrizd, hogy a visszagörgetés kevesebb mint egy percet vesz igénybe, és teszteld ezt egy csendes napon, nem pedig incidens közben. Végül jelöld meg a telepített verziókat tagekkel, hogy egyértelműen összekapcsold a megfigyelt viselkedést a tároló egy adott állapotával.
A katalógus tesztelése visszagörgetéssel
Állíts be egy PromptCatalog-ot három valódi prompttal az alkalmazásodból, majd rögzíts mindegyikből két-három verziót az utasítások apró lépésekben történő fejlesztésével – egy hangnemi utasítás, egy hozzáadott kategória. A verziókezelés ezeken a finomhangolt változásokon bizonyítja az értékét, mert ezekre azok, amelyeket nem fogsz emlékezni, hogy megtettél. Állítsd be az aktiválást és deaktiválást, és csatolj egy tesztsorozatot minden promptához.
Fejezd be a legtanulságosabb gyakorlattal: szándékosan aktiválj egy degradált verziót, figyeld meg a regressziót a tesztek segítségével, és hajtsd végre a visszagörgetést időméréssel. Ha a művelet meghaladja az egy percet, javítsd az eljárást, mielőtt egyetlen promptot is hozzáadnál a katalógushoz – egy lassú visszagörgetés nem visszagörgetés, hanem elhúzódó incidens.
Főbb megállapítások
- A promptok szoftveres artifactek, amelyek verziókezelést igényelnek
- Minden verzió egy JSON vagy YAML fájl metaadatokkal
- Az állapot (draft, active, deprecated) lehetővé teszi a fokozatos telepítést
- Tárold a promptokat Gitben tesztekkel és változásnaplóval
- Regresszió esetén a visszagörgetésnek azonnalinak kell lennie