Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Upravljanje z različicami pozivov in katalogom

Lekcija 14 od 16 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Upravljanje z različicami pozivov in katalogom
  2. Zakaj različičiti pozive
  3. Struktura kataloga
  4. Uporaba kataloga v tvoji aplikaciji
  5. Različičenje z Gitom
  6. Najboljše prakse
  7. Testiranje kataloga s povratnim korakom
  8. Ključne ugotovitve

Lekcija posodobljena 3. novembra 2026 na podlagi dokumentacije OpenAI: parametra temperature in top_p sta sprejeta le pri naporu razmišljanja (reasoning effort) vrednosti none, medtem ko modeli GPT-5.6 privzeto razmišljajo (medium). Klici, ki nastavljajo te parametre, morajo zato določiti reasoning={"effort": "none"} (Responses API) ali reasoning_effort="none" (Chat Completions). Viri: Uporaba GPT-6 · GPT-5.6 Terra.

Upravljanje z različicami pozivov in katalogom

V produkcijskem okolju se tvoji pozivi razvijajo enako hitro kot tvoja koda. Brez nadzora različic izgubiš pregled nad spremembami, ne moreš se vrniti na prejšnje stanje in nimaš pojma, katera različica trenutno teče v produkciji. Ta lekcija ti pokaže, kako upravljati s pozivi kot s programskimi artefakti.

Zakaj različičiti pozive

Sprememba poziva lahko drastično spremeni obnašanje tvoje aplikacije. Za razliko od kode so te spremembe pogosto subtilne in jih brez avtomatiziranih testov težko zaznaš: preoblikovan stavek, prestavljena beseda in model začne napačno razvrščati enega od desetih robnih primerov. Noben standardni enotski test ne bo zaznal te vrzeli, podpora pa bo to tri tedne kasneje označila kot nejasno pritožbo o napačno usmerjenih karticah.

Različičenje naslavlja štiri različne potrebe. Prvič, sledljivost: vedeti, kdo je kaj spremenil in kdaj, spremeni sterilno razpravo v ekipi v preprost pregled zgodovine. Drugič, povratni korak (rollback): ko se pojavi regresija, takojšnji cilj ni razumeti zakaj, temveč obnoviti znano obnašanje. Tretjič, primerjava zmogljivosti: to zahteva, da starejše različice ostanejo izvedljive točno tako, kot so bile, s svojim izvirnim modelom in nastavitvami. Nazadnje, revizija: za sisteme, ki spadajo pod GDPR (Splošna uredba o varstvu podatkov) ali druge okvire skladnosti, moraš dokazati, katera navodila so veljala na določen datum – posnetek zaslona tu ne zadošča.

Struktura kataloga

Razred PromptCatalog zadovolji te potrebe z minimalno infrastrukturo: ena mapa na poziv, ena datoteka JSON na različico, oštevilčene zaporedno. Vsaka datoteka združuje besedilo sistemskega poziva skupaj s povezanim modelom in temperaturo – poziv, uglašen na 0,1, in isti poziv na 0,7 nista ista stvar, njuno skupno zaklepanje pa preprečuje obnovitev besedila ob pozabi na nastavitve.

Polje status sledi življenjskemu ciklu. Različica se začne kot draft (osnutek), kar omogoča pripravo in testiranje brez vpliva na živi promet. Klic activate jo preklopi v active (aktivno) in samodejno degradira prejšnjo različico v deprecated (zastarelo), kar zagotavlja, da promet hkrati obravnava le ena različica. Ta metoda naredi povratni korak trivialnim: ponovna aktivacija prejšnje različice je en sam klic, ne pa celotna uvedba. Tvoja aplikacija v produkciji kliče get_active, medtem ko list_versions podpira preglede in revizije.

import json
from datetime import datetime
from pathlib import Path

class PromptCatalog:
    """Upravitelj kataloga pozivov z različičenjem."""

    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:
        """Shrani novo različico poziva."""
        prompt_dir = self.catalog_dir / name
        prompt_dir.mkdir(exist_ok=True)

        # Določi številko različice
        versions = sorted(prompt_dir.glob("v*.json"))
        version = len(versions) + 1
        version_str = f"v{version:03d}"

        # Shrani
        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:
        """Pridobi poziv po imenu in različici."""
        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:
        """Pridobi aktivno različico poziva."""
        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):
        """Aktivira različico in deaktivira druge."""
        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]:
        """Izpiše vse različice poziva."""
        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

Uporaba kataloga v tvoji aplikaciji

Na strani klicalca je pravilo preprosto: tvoja koda ne vsebuje besedila poziva; zahteva aktivno različico iz kataloga. To omogoča spreminjanje pozivov brez dotikanja kode aplikacije in preprečuje, da bi se tridesetvrstični nizi izgubili sredi funkcije. Metapodatki, shranjeni med shranjevanjem – avtor, opis, dnevnik sprememb – nimajo vpliva na izvajanje, a naredijo zgodovino berljivo šest mesecev kasneje, ko se nihče več ne spomni, zakaj se je formulacija spremenila.

Ključna podrobnost je na koncu funkcije classifier_ticket: vrnjeni odgovor vključuje prompt_version. To polje zabeleži ob vsakem rezultatu in analiza incidentov postane mogoča – vedel boš, da so napačno razvrščene kartice iz torkovega popoldneva vse prihajale iz različice v004, brez potrebe po križnem preverjanju časovnih žigov uvedbe.

from openai import OpenAI

client = OpenAI()
catalog = PromptCatalog("prompts/")

# Shrani poziv
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": "Samodejna razvrstitev kartic Zendesk",
        "changelog": "Začetna različica"
    }
)

# V produkciji: uporabi aktivno različico
def classifier_ticket(ticket_text: str) -> dict:
    """Razvrsti kartico z uporabo aktivnega poziva."""
    prompt_config = catalog.get_active("ticket-classifier")

    response = client.responses.create(
        model=prompt_config["model"],
        reasoning={"effort": "none"},  # temperatura zahteva napor 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"]
    }

Različičenje z Gitom

Za ekipe shrani svoje pozive v namensko skladišče Git. Spodnje drevo sledi preprosti konvenciji: ena mapa na poziv, ki vsebuje njegovo definicijo, testne primere in dnevnik sprememb. Hranjenje testov ob pozivu, ki ga preverjajo, ni kozmetične narave – zahtevek za združitev (pull request) spremeni oboje hkrati, recenzent pa spremembo oceni na podlagi dokazov in ne deklariranih namenov.

prompts/
  ticket-classifier/
    prompt.yaml
    tests/
      test_cases.json
    CHANGELOG.md
  invoice-extractor/
    prompt.yaml
    tests/
      test_cases.json
    CHANGELOG.md

YAML tu nadomešča JSON iz specifičnega razloga: pozivi so večvrstična besedila in sintaksa | jih prikaže točno tako, kot so poslana, brez ubežnih znakov ali izgubljenih znakov \n. Razlika Git (diff) v tej datoteki se bere kot razlika v prozi – recenzent vidi, da je bil dodan stavek. Shema izhoda potuje v isti datoteki, tako da celotna konfiguracija za klic sodi v en sam artefakt.

# 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

Najboljše prakse

Razlika med živim katalogom in mapo arhiva je v nekaj hišnih pravilih. Ohrani en poziv na datoteko: mešanje več pozivov v enem dokumentu naredi razlike neberljive in povratne korake nemogoče natančno usmeriti. Uveljavi dnevnik sprememb, ki dokumentira ne kaj se je spremenilo – to pokaže razlika – ampak zakaj: „dodano navodilo o večjezičnih karticah po povratnih informacijah podpore” je vredno desetih vrstic tehničnega opisa.

Vsakemu pozivu sistematično dodeli testni niz; v nasprotnem primeru ti bodo uporabniki prvi povedali, kdaj sprememba poruši uveljavljeno obnašanje. Spremembe pozivov usmeri skozi isti postopek pregleda kode kot samo kodo: poziv, ki gre v produkcijo brez pregleda, povzroči enaka presenečenja kot nepregledana koda. Preveri, ali povratni korak traja manj kot minuto, in ga testiraj ob mirnem dnevu, ne med incidentom. Nazadnje, uvedene različice označi z oznakami (tags), da nedvoumno povežeš opaženo obnašanje z določenim stanjem skladišča.

Testiranje kataloga s povratnim korakom

Nastavi PromptCatalog za tri stvarne pozive iz tvoje aplikacije, nato zabeleži dve ali tri različice vsakega z majhnimi koraki evolucije navodil – navodilo o tonu, dodana kategorija. Različičenje dokaže svojo vrednost pri teh drobnozrnatih spremembah, saj so prav tiste, na katere ne boš pomnil, da si jih naredil. Nastavi aktivacijo in deaktivacijo ter vsakemu pozivu pripni testni niz.

Zaključi z najbolj poučno vajo: namerno aktiviraj degradirano različico, opazuj regresijo prek testov in izvedi povratni korak ob merjenju časa. Če operacija preseže eno minuto, popravi postopek, preden dodaš še en poziv v katalog – počasen povratni korak ni povratni korak, temveč dolgotrajen incident.

Ključne ugotovitve

  • Pozivi so programski artefakti, ki zahtevajo različičenje
  • Vsaka različica je datoteka JSON ali YAML z metapodatki
  • Stanje (osnutek, aktivno, zastarelo) omogoča postopno uvajanje
  • Pozive shrani v Git s testi in dnevnikom sprememb
  • Povratni korak mora biti v primeru regresije trenutčen