Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Promptide versioonihaldus ja kataloogihaldus

Õppetund 14 / 16 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Promptide versioonihaldus ja kataloogihaldus
  2. Miks prompte versioneerida
  3. Kataloogi struktuur
  4. Kataloogi kasutamine rakenduses
  5. Versioonihaldus Gitiga
  6. Parimad tavad
  7. Kataloogi testimine taastamisega
  8. Peamised punktid

Tund uuendatud 3. novembril 2026 OpenAI dokumentatsiooni põhjal: parameetreid temperature ja top_p aktsepteeritakse ainult siis, kui arutluse jõupingutus (reasoning effort) on none, samas kui GPT-5.6 mudelid kasutavad vaikimisi arutlust (medium). Seetõttu peavad need parameetrid määravad päringud sisaldama reasoning={"effort": "none"} (Responses API) või reasoning_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