Promptide versioonihaldus ja kataloogihaldus
Sellel lehel
Tund uuendatud 3. novembril 2026 OpenAI dokumentatsiooni põhjal: parameetreid
temperaturejatop_paktsepteeritakse ainult siis, kui arutluse jõupingutus (reasoning effort) onnone, samas kui GPT-5.6 mudelid kasutavad vaikimisi arutlust (medium). Seetõttu peavad need parameetrid määravad päringud sisaldamareasoning={"effort": "none"}(Responses API) võireasoning_effort="none"(Chat Completions). Allikad: GPT-6 kasutamine · GPT-5.6 Terra.
Promptide versioonihaldus ja kataloogihaldus
Tootmiskeskkonnas arenevad su promptid sama palju kui su kood. Ilma versioonihalduseta kaotad muudatustel silma peal hoidmise võime, ei saa taastada eelmisi seisundeid ja ei tea, milline versioon parasjagu tootmises jookseb. See tund õpetab, kuidas hallata prompte tarkvara artefaktidena.
Miks prompte versioneerida
Prompti muutus võib radikaalselt muuta su rakenduse käitumist. Erinevalt koodist on need muutused sageli peened ja ilma automatiseeritud testideta raskesti tuvastatavad: ümber sõnastatud lause, nihutatud sõna ja mudel hakkab ühel juhul kümnest ääreolukorras valesti klassifitseerima. Ükski standardne ühiktest seda lõhet ei püüa, kuid tugiteenistus märgib seda kolm nädalat hiljem ebamäärase kaebusena valesti suunatud piletite kohta.
Versioonihaldus lahendab nelja erinevat vajadust. Esiteks jälgitavus: teadmine, kes, mida ja millal muutis, muudab viljatu meeskonna väitluse lihtsaks ajaloo kontrolliks. Teiseks taastamine (rollback): kui ilmneb regressioon, ei ole esmane eesmärk mõista, miks see juhtus, vaid taastada teadaolev käitumine. Kolmandaks jõudluse võrdlus: see nõuab, et vanemad versioonid jääksid täpselt sellisena käivitatavaks, nagu nad olid, koos oma algse mudeli ja seadetega. Lõpuks auditeerimine: süsteemide puhul, mis alluvad GDPR-ile (üldine andmekaitsemäärus) või muudele vastavusraamistikele, pead suutma tõendada, millised juhised olid antud kuupäeval jõus – ekraanitõmmis selleks ei piisa.
Kataloogi struktuur
Klass PromptCatalog rahuldab need vajadused minimaalse taristuga: üks kaust prompti kohta, üks JSON-fail versiooni kohta, nummerdatud järjestikku. Iga fail koondab süsteemi prompti teksti koos seotud mudeli ja temperatuuriga – prompt, mis on häälestatud temperatuurile 0.1, ja sama prompt temperatuuril 0.7 ei ole sama asi ning nende koos lukustamine hoiab ära olukorra, kus taastad teksti, unustades aga selle seaded.
Väli status jälgib elutsüklit. Versioon algab olekuga draft (mustand), võimaldades ettevalmistust ja testimist ilma live-liiklust mõjutamata. Meetodi activate kutsumine lülitab oleku väärtuseks active (aktiivne) ja viib eelmise versiooni automaatselt olekusse deprecated (iganenud), tagades, et igal ajal teenindab liiklust ainult üks versioon. See meetod teeb taastamise triviaalseks: eelmise versiooni uuesti aktiveerimine on üksainus väljakutse, mitte terviklik juurutamine. Su rakendus kutsub tootmises get_active, samas kui list_versions toetab ülevaateid ja auditeid.
import json
from datetime import datetime
from pathlib import Path
class PromptCatalog:
"""Promptide kataloogi haldur versioonihaldusega."""
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:
"""Salvestab prompti uue versiooni."""
prompt_dir = self.catalog_dir / name
prompt_dir.mkdir(exist_ok=True)
# Määra versiooni number
versions = sorted(prompt_dir.glob("v*.json"))
version = len(versions) + 1
version_str = f"v{version:03d}"
# Salvesta
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:
"""Toob prompti nime ja versiooni põhjal."""
prompt_dir = self.catalog_dir / name
if version == "latest":
versions = sorted(prompt_dir.glob("v*.json"))
if not versions:
raise FileNotFoundError(f"Prompti '{name}' ei leitud")
filepath = versions[-1]
else:
filepath = prompt_dir / f"{version}.json"
return json.loads(filepath.read_text())
def get_active(self, name: str) -> dict:
"""Toob prompti aktiivse versiooni."""
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"Aktiivset versiooni '{name}' jaoks ei leitud"
)
def activate(self, name: str, version: str):
"""Aktiveerib versiooni ja deaktiveerib teised."""
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]:
"""Loetleb kõik prompti versioonid."""
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
Kataloogi kasutamine rakenduses
Kutsuja poolel on reegel lihtne: su kood ei sisalda prompti teksti; see küsib kataloogist aktiivset versiooni. See hoiab promptid muudetavana ilma rakenduse koodi puutumata ja takistab kolmekümne-realiste stringide mattumist funktsiooni keskele. Salvestamise käigus salvestatud metaandmed – autor, kirjeldus, muudatuste logi – ei mõjuta täitmist, kuid muudavad ajaloo loetavaks kuus kuud hiljem, kui keegi enam ei mäleta, miks sõnastust muudeti.
Kriitiline detail peitub funktsiooni classifier_ticket lõpus: tagastatud vastus sisaldab välja prompt_version. Logi seda välja iga tulemusega ja intsidentide analüüs muutub võimalikuks – tead, et teisipäeva pärastlõunal valesti klassifitseeritud piletid tulid kõik versioonist v004, ilma et peaksid ristviitama juurutamise ajatemplitele.
from openai import OpenAI
client = OpenAI()
catalog = PromptCatalog("prompts/")
# Salvesta prompt
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'i piletite automaatne klassifitseerimine",
"changelog": "Esmaversioon"
}
)
# Tootmises: kasuta aktiivset versiooni
def classifier_ticket(ticket_text: str) -> dict:
"""Klassifitseerib pileti, kasutades aktiivset prompti."""
prompt_config = catalog.get_active("ticket-classifier")
response = client.responses.create(
model=prompt_config["model"],
reasoning={"effort": "none"}, # temperatuur nõuab jõupingutust 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"]
}
Versioonihaldus Gitiga
Meeskondade jaoks salvesta oma promptid spetsiaalsesse Giti hoidlasse. Allpool olev puu järgib lihtsat kokkulepet: üks kaust prompti kohta, sisaldades selle definitsiooni, testjuhtumeid ja muudatuste logi. Testide hoidmine koos promptiga, mida need kontrollivad, ei ole kosmeetika – tõmbetaotlus (pull request) muudab mõlemat koos ja ülevaataja hindab muutust tõendite, mitte deklareeritud kavatsuse põhjal.
prompts/
ticket-classifier/
prompt.yaml
tests/
test_cases.json
CHANGELOG.md
invoice-extractor/
prompt.yaml
tests/
test_cases.json
CHANGELOG.md
YAML asendab siin JSON-i kindlal põhjusel: promptid on mitmerealised tekstid ja süntaks | kuvab need täpselt nii, nagu need saadetakse, ilma escape-märkideta või ekslevate \n tähemärkideta. Giti diff sellel failil loeb nagu proosa diff – ülevaataja näeb, et lause lisati. Väljundi skeem reisib samas failis, nii et väljakutse täielik konfiguratsioon mahub ühte artefakti.
# 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
Parimad tavad
Mis eraldab elavat kataloogi arhiivikaustast, taandub mõnele majapidamisreeglile. Hoia ühes failis ainult üks prompt: mitme prompti segamine ühte dokumenti teeb diffid loetamatuks ja taastamise võimatuks sihtida. Jõusta muudatuste logi, mis dokumenteerib mitte seda, mis muutus – diff näitab seda –, vaid miks: „lisatud juhend mitmekeelsete piletite kohta tugiteenistuse tagasiside põhjal“ on väärtuslikum kui kümme rida tehnilist kirjeldust.
Seosta iga promptiga süstemaatiliselt testikomplekt; vastasel juhul on kasutajad esimesed, kes sulle ütlevad, kui muudatus rikub kehtestatud käitumist. Suuna promptide muutused läbi sama koodi ülevaatuse protsessi nagu kood ise: prompt, mis läheb tootmisse ilma ülevaatuseta, tekitab sama palju üllatusi kui läbi vaatamata kood. Veendu, et taastamine võtab vähem kui minuti, ja testi seda vaiksel päeval, mitte intsidenti ajal. Lõpuks märgista juurutatud versioonid siltidega (tags), et seostada vaadeldav käitumine üheselt konkreetse hoidla olekuga.
Kataloogi testimine taastamisega
Seadista PromptCatalog kolmele oma rakenduse reaalsele promptile ja seejärel salvesta igaühele kaks või kolm versiooni, arendades juhiseid väikeste sammudega – tooni juhend, lisatud kategooria. Versioonihaldus tõestab oma väärtust just nende peenete muutuste peal, sest need on need, mida sa ei mäleta tegemast. Seadista aktiveerimine ja deaktiveerimine ning lisa igale promptile testikomplekt.
Lõpeta kõige õpetlikuma harjutusega: aktiveeri tahtlikult halvenenud versioon, jälgi regressiooni testide kaudu ja vii läbi taastamine, mõõtes aega. Kui operatsioon ületab ühe minuti, paranda protseduuri enne, kui lisad kataloogi ühegi prompti – aeglane taastamine ei ole taastamine, see on pikaajaline intsident.
Peamised punktid
- Promptid on tarkvara artefaktid, mis vajavad versioonihaldust
- Iga versioon on JSON- või YAML-fail metaandmetega
- Olek (mustand, aktiivne, iganenud) võimaldab järkjärgulist juurutamist
- Salvesta promptid Gitti koos testide ja muudatuste logiga
- Taastamine peab regressiooni korral olema kohene