Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Verzioniranje promptova i upravljanje katalogom

Lekcija 14 od 16 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Verzioniranje promptova i upravljanje katalogom
  2. Zašto verzionirati promptove
  3. Struktura kataloga
  4. Korištenje kataloga u tvojoj aplikaciji
  5. Verzioniranje s Gitom
  6. Najbolje prakse
  7. Testiranje kataloga s povratkom na staro
  8. Ključne točke

Lekcija ažurirana 3. studenog 2026. na temelju OpenAI dokumentacije: parametri temperature i top_p prihvaćeni su samo uz napor rezoniranja (reasoning effort) vrijednosti none, dok GPT-5.6 modeli prema zadanim postavkama rezoniraju s razinom medium. Pozivi koji postavljaju ove parametre stoga moraju specificirati reasoning={"effort": "none"} (Responses API) ili reasoning_effort="none" (Chat Completions). Izvori: Korištenje GPT-6 · GPT-5.6 Terra.

Verzioniranje promptova i upravljanje katalogom

U proizvodnji se tvoji promptovi razvijaju jednako kao i tvoj kod. Bez verzioniranja gubiš pregled nad promjenama, ne možeš se vratiti na staru verziju i nemaš pojma koja se verzija trenutno izvršava u proizvodnji. Ova lekcija pokazuje ti kako upravljati promptovima kao softverskim artefaktima.

Zašto verzionirati promptove

Promjena prompta može radikalno alterirati ponašanje tvoje aplikacije. Za razliku od koda, ove su promjene često suptilne i teško ih je otkriti bez automatiziranih testova: preformulirana rečenica, pomaknuta riječ i model počne krivo klasificirati jedan od deset rubnih slučajeva. Nijedan standardni jedinični test neće uhvatiti ovaj propust, ali će korisnička podrška to prijaviti tri tjedna kasnije kao nejasnu pritužbu na pogrešno usmjerene tikete.

Verzioniranje odgovara na četiri različite potrebe. Prvo, sljedivost: znati tko je što i kada promijenio pretvara sterilnu raspravu u timu u jednostavnu provjeru povijesti. Drugo, povratak na staro (rollback): kada se pojavi regresija, trenutni cilj nije razumjeti zašto, već vratiti poznato ponašanje. Treće, usporedba performansi: to zahtijeva da starije verzije ostanu izvršive točno onako kako su bile, sa svojim izvornim modelom i postavkama. Konačno, revizija: za sustave podložne GDPR-u (Opća uredba o zaštiti podataka) ili drugim okvirima usklađenosti, moraš dokazati koje su upute bile na snazi određenog datuma – snimka zaslona neće biti dovoljna.

Struktura kataloga

Klasa PromptCatalog zadovoljava ove potrebe uz minimalnu infrastrukturu: jedna mapa po promptu, jedna JSON datoteka po verziji, numerirane uzastopno. Svaka datoteka sadrži tekst sistemskog prompta zajedno s pridruženim modelom i temperaturom – prompt podešen na 0.1 i isti taj prompt na 0.7 nisu ista stvar, a njihovo zajedničko zaključavanje sprječava vraćanje teksta uz zaboravljanje njegovih postavki.

Polje status prati životni ciklus. Verzija započinje kao draft (nacrt), što omogućuje pripremu i testiranje bez utjecaja na promet uživo. Pozivom activate prelazi u active (aktivno) i automatski degradira prethodnu verziju u deprecated (zastarjelo), osiguravajući da samo jedna verzija opslužuje promet u bilo kojem trenutku. Ova metoda čini povratak na staro trivijalnim: reaktiviranje ranije verzije je jedan poziv, a ne cijelo deployanje. Tvoja aplikacija u proizvodnji poziva get_active, dok list_versions podržava pregled i revizije.

import json
from datetime import datetime
from pathlib import Path

class PromptCatalog:
    """Upravitelj katalogom promptova s verzioniranjem."""

    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:
        """Sprema novu verziju prompta."""
        prompt_dir = self.catalog_dir / name
        prompt_dir.mkdir(exist_ok=True)

        # Odredi broj verzije
        versions = sorted(prompt_dir.glob("v*.json"))
        version = len(versions) + 1
        version_str = f"v{version:03d}"

        # Spremi
        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:
        """Dohvaća prompt po imenu i verziji."""
        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:
        """Dohvaća aktivnu verziju prompta."""
        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 verziju i deaktivira ostale."""
        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]:
        """Ispisuje sve verzije prompta."""
        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

Korištenje kataloga u tvojoj aplikaciji

Na strani pozivatelja pravilo je jednostavno: tvoj kod ne sadrži tekst prompta; on traži aktivnu verziju iz kataloga. To održava promptove modificirabilnima bez diranja u kod aplikacije i sprječava da se nizovi od trideset redaka zakopaju usred funkcije. Metapodaci spremljeni tijekom pohrane – autor, opis, dnevnik promjena – nemaju utjecaja na izvršavanje, ali čine povijest čitljivom šest mjeseci kasnije, kada se nitko ne sjeća zašto je formulacija promijenjena.

Kritični detalj nalazi se na kraju funkcije classifier_ticket: vraćeni odgovor uključuje prompt_version. Zabilježi ovo polje uz svaki rezultat i analiza incidenata postaje moguća – znat ćeš da su pogrešno klasificirani tiketi iz utorka poslijepodne svi došli iz verzije v004, bez potrebe za unakrsnim referenciranjem vremenskih oznaka deployanja.

from openai import OpenAI

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

# Spremi 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": "Automatska klasifikacija Zendesk tiketa",
        "changelog": "Početna verzija"
    }
)

# U proizvodnji: koristi aktivnu verziju
def classifier_ticket(ticket_text: str) -> dict:
    """Klasificira tiket koristeći aktivni prompt."""
    prompt_config = catalog.get_active("ticket-classifier")

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

Verzioniranje s Gitom

Za timove, spremi svoje promptove u namjensko Git spremište. Stablo u nastavku slijedi jednostavnu konvenciju: jedna mapa po promptu, koja sadrži njegovu definiciju, testne slučajeve i dnevnik promjena. Čuvanje testova uz prompt koji verificiraju nije kozmetičko – pull request modificira oboje zajedno, a recenzent procjenjuje promjenu na temelju dokaza, a ne deklarirane namjere.

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

YAML ovdje zamjenjuje JSON iz specifičnog razloga: promptovi su višeredni tekstovi, a sintaksa | prikazuje ih točno onako kako su poslani, bez escapiranja ili lutajućih \n znakova. Git diff na ovoj datoteci čita se kao diff proze – recenzent vidi da je rečenica dodana. Shema izlaza putuje u istoj datoteci, tako da cijela konfiguracija za poziv stane u jedan 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

Najbolje prakse

Ono što živi katalog razlikuje od mape arhive svodi se na nekoliko pravila održavanja. Drži jedan prompt po datoteci: miješanje više promptova u jednom dokumentu čini diffove nečitkivima i povratak na staro nemogućim za ciljano izvođenje. Nametni dnevnik promjena koji dokumentira ne što se promijenilo – to diff pokazuje – već zašto: „dodana uputa o višejezičnim tiketima nakon povratne informacije podrške“ vrijedi deset redaka tehničkog opisa.

Sustavno poveži testni suite sa svakim promptom; u suprotnom, korisnici će ti prvi javiti kada modifikacija razbije uspostavljeno ponašanje. Usmjeri promjene promptova kroz isti proces recenzije koda kao i sam kod: prompt koji ode u proizvodnju bez recenzije proizvodi ista iznenađenja kao i nerecenzirani kod. Provjeri traje li povratak na staro manje od minute i testiraj ga tijekom mirnog dana, a ne tijekom incidenta. Konačno, označi deployane verzije tagovima kako bi se nedvosmisleno povezalo opaženo ponašanje s određenim stanjem spremišta.

Testiranje kataloga s povratkom na staro

Postavi PromptCatalog za tri stvarna prompta iz tvoje aplikacije, zatim zabilježi dvije ili tri verzije svakog od njih evoluirajući upute u malim koracima – uputa o tonu, dodana kategorija. Verzioniranje dokazuje svoju vrijednost na ovim finim promjenama, jer su to one kojih se nećeš sjetiti da si napravio. Postavi aktivaciju i deaktivaciju te pridruži testni suite svakom promptu.

Završi s najpoučnijom vježbom: namjerno aktiviraj degradiranu verziju, promatraj regresiju putem testova i izvrši povratak na staro mjereći vrijeme. Ako operacija traje dulje od jedne minute, popravi postupak prije dodavanja ijednog prompta u katalog – spor povratak na staro nije povratak, to je dugotrajan incident.

Ključne točke

  • Promptovi su softverski artefakti koji zahtijevaju verzioniranje
  • Svaka verzija je JSON ili YAML datoteka s metapodacima
  • Status (draft, active, deprecated) omogućuje postupno deployanje
  • Pohrani promptove u Git s testovima i dnevnikom promjena
  • Povratak na staro mora biti trenutan u slučaju regresije