Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Promptų versijavimas ir katalogo valdymas

Paskaita 14 iš 16 Atnaujinta 2026 m. lapkričio 3 d. Kūrėjas
Šiame puslapyje
  1. Promptų versijavimas ir katalogo valdymas
  2. Kodėl reikia versijuoti promptus
  3. Katalogo struktūra
  4. Katalogo naudojimas tavo programoje
  5. Versijavimas naudojant „Git“
  6. Geriausios praktikos
  7. Katalogo testavimas su grįžimu atgal
  8. Svarbiausi punktai

Pamoka atnaujinta 2026 m. lapkričio 3 d. pagal „OpenAI“ dokumentaciją: parametrai temperature ir top_p priimami tik esant none samprotavimo pastangoms, tuo tarpu GPT-5.6 modeliai pagal nutylėjimą samprotauja (medium). Todėl kvietimuose, kuriuose nustatomi šie parametrai, būtina nurodyti reasoning={"effort": "none"} (Responses API) arba reasoning_effort="none" (Chat Completions). Šaltiniai: Using GPT-6 · GPT-5.6 Terra.

Promptų versijavimas ir katalogo valdymas

Gamyboje tavo promptai evoliucionuoja taip pat kaip ir kodas. Be versijavimo prarandi pokyčių eigą, negali grįžti atgal ir nežinai, kuri versija veikia gamyboje. Šioje pamokoje sužinosi, kaip valdyti promptus kaip programinės įrangos artefaktus.

Kodėl reikia versijuoti promptus

Prompto pakeitimas gali radikaliai pakeisti tavo programos elgseną. Skirtingai nei kodas, šie pokyčiai dažnai būna subtilūs ir be automatinių testų sunkiai pastebimi: perfrazuotas sakinys, perkeltas žodis – ir modelis pradeda neteisingai klasifikuoti vieną iš dešimties ribinių atvejų. Joks standartinis vieneto testas šios spragos nepagaus, tačiau palaikymo komanda tai pastebės po trijų savaičių kaip miglotą skundą dėl neteisingai nukreiptų bilietų.

Versijavimas tenkina keturis skirtingus poreikius. Pirma, atsekamumas: žinojimas, kas, ką ir kada pakeitė, paverčia sterilias komandos diskusijas paprastu istorijos patikrinimu. Antra, grįžimas atgal (rollback): kai atsiranda regresija, pagrindinis tikslas yra ne suprasti, kodėl taip nutiko, o atkurti žinomą elgseną. Trečia, našumo palyginimas: tam reikia, kad senesnės versijos liktų vykdomos tiksliai taip, kaip buvo sukurtos, su savo originaliu modeliu ir nustatymais. Galiausiai, auditas: sistemoms, kurioms taikomas BDAR (Bendrasis duomenų apsaugos reglamentas) ar kiti atitikties reikalavimai, privalai įrodyti, kurios instrukcijos galiojo konkrečią datą – ekrano kopijos neužtenka.

Katalogo struktūra

PromptCatalog klasė tenkina šiuos poreikius naudojant minimalią infrastruktūrą: vienas aplankas kiekvienam promptui, vienas JSON failas kiekvienai versijai, sunumeruotas nuosekliai. Kiekviename faile sujungiamas sistemos prompto tekstas kartu su susijusiu modeliu ir temperatūra – promptas, suderintas su 0,1 temperatūra, ir tas pats promptas su 0,7 nėra tas pats dalykas, o jų sujungimas apsaugo nuo situacijos, kai atkuriamas tekstas, bet pamirštami jo nustatymai.

Laukas status stebi gyvavimo ciklą. Versija pradedama kaip draft (juodraštis), leidžiant pasiruošti ir testuoti nepaveikiant realaus srauto. Iškvietus activate, ji perjungia būseną į active (aktyvi) ir automatiškai pažemina ankstesnę versiją į deprecated (pasenusi), užtikrindama, kad bet kuriuo metu srautą aptarnautų tik viena versija. Šis metodas daro grįžimą atgal trivialiu: ankstesnės versijos suaktyvinimas yra vienas kvietimas, o ne visas diegimas. Tavo programa gamyboje kviečia get_active, o list_versions palaiko peržiūras ir auditus.

import json
from datetime import datetime
from pathlib import Path

class PromptCatalog:
    """Promptų katalogo valdytojas su versijavimu."""

    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:
        """Išsaugo naują prompto versiją."""
        prompt_dir = self.catalog_dir / name
        prompt_dir.mkdir(exist_ok=True)

        # Nustatome versijos numerį
        versions = sorted(prompt_dir.glob("v*.json"))
        version = len(versions) + 1
        version_str = f"v{version:03d}"

        # Išsaugome
        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:
        """Gauna promptą pagal pavadinimą ir versiją."""
        prompt_dir = self.catalog_dir / name

        if version == "latest":
            versions = sorted(prompt_dir.glob("v*.json"))
            if not versions:
                raise FileNotFoundError(f"Promptas '{name}' nerastas")
            filepath = versions[-1]
        else:
            filepath = prompt_dir / f"{version}.json"

        return json.loads(filepath.read_text())

    def get_active(self, name: str) -> dict:
        """Gauna aktyvią prompto versiją."""
        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"Nėra aktyvios '{name}' versijos"
        )

    def activate(self, name: str, version: str):
        """Suaktyvina versiją ir deaktyvuoja kitas."""
        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]:
        """Išvardija visas prompto versijas."""
        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

Katalogo naudojimas tavo programoje

Kviečiančiojo pusėje taisyklė paprasta: tavo kode nėra jokio prompto teksto; jis prašo aktyvios versijos iš katalogo. Tai leidžia keisti promptus neliečiant programos kodo ir neleidžia trisdešimties eilučių eilučių pasislėpti funkcijos viduryje. Saugojimo metu įrašyti metaduomenys – autorius, aprašymas, pakeitimų žurnalas – neturi įtakos vykdymui, tačiau po šešių mėnesių daro istoriją suprantamą, kai niekas nebeprisimena, kodėl buvo pakeista formuluotė.

Svarbiausia detalė yra classifier_ticket pabaigoje: grąžinamas atsakymas apima prompt_version. Registruok šį lauką su kiekvienu rezultatu, ir incidentų analizė taps įmanoma – žinosi, kad antradienio popietę neteisingai klasifikuoti bilietai visi kilo iš v004 versijos, nereikės kryžminėti diegimo laiko žymų.

from openai import OpenAI

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

# Išsaugome 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": "Automatinis Zendesk bilietų klasifikavimas",
        "changelog": "Pradinė versija"
    }
)

# Gamyboje: naudojame aktyvią versiją
def classifier_ticket(ticket_text: str) -> dict:
    """Klasifikuoja bilietą naudojant aktyvų promptą."""
    prompt_config = catalog.get_active("ticket-classifier")

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

Versijavimas naudojant „Git“

Komandoms saugokite savo promptus atskiroje „Git“ saugykloje. Toliau pateikta medžio struktūra laikosi paprastos konvencijos: vienas aplankas kiekvienam promptui, kuriame yra jo apibrėžimas, testų atvejai ir pakeitimų žurnalas. Testų laikymas šalia tikrinamo prompto nėra tik kosmetinis dalykas – „pull request“ pakeičia abu kartu, o recenzentas vertina pokytį pagal įrodymus, o ne deklaruotus ketinimus.

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

Čia YAML pakeičia JSON dėl specifinės priežasties: promptai yra daugiaeilutis tekstas, o | sintaksė juos rodo tiksliai taip, kaip jie siunčiami, be pabėgimo simbolių ar klaidingų \n ženklų. „Git diff“ šiame faile skaitomas kaip prozos skirtumas – recenzentas mato, kad buvo pridėtas sakinys. Išvesties schema keliauja tame pačiame faile, todėl visa kvietimo konfigūracija telpa į vieną 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

Geriausios praktikos

Kas atskiria gyvą katalogą nuo archyvo aplanko, priklauso nuo kelių tvarkos taisyklių. Laikykitės vieno prompto viename faile principo: kelių promptų maišymas viename dokumente daro skirtumus neskaitytinus, o grįžimą atgal – neįmanomą tiksliai nukreipti. Reikalaukite pakeitimų žurnalo, kuriame dokumentuojama ne kas pasikeitė (tai parodo skirtumas), o kodėl: „pridėta instrukcija dėl daugiakalbių bilietų po palaikymo komandos grįžtamojo ryšio“ verta dešimties techninio aprašymo eilučių.

Sistemingai susiekite testų rinkinį su kiekvienu promptu; priešingu atveju vartotojai bus pirmieji, kurie praneš, kai pakeitimas sugriaus nusistovėjusią elgseną. Nukreipkite promptų pakeitimus per tą pačią kodo peržiūros procesą kaip ir kodą: promptas, patenkantis į gamybą be peržiūros, sukelia tokias pačias staigmenas kaip ir neperžiūrėtas kodas. Patikrinkite, ar grįžimas atgal trunka mažiau nei minutę, ir išbandykite tai ramią dieną, o ne incidento metu. Galiausiai, pažymėkite išdiegtas versijas žymomis (tags), kad vienareikšmiškai susietumėte stebimą elgseną su konkrečia saugyklos būsena.

Katalogo testavimas su grįžimu atgal

Sukonfigūruok PromptCatalog trims realiems tavo programos promptams, tada įrašyk dvi ar tris kiekvieno versijas, mažais žingsniais keisdami instrukcijas – tonacijos instrukcija, pridėta kategorija. Versijavimas įrodo savo vertę būtent šiuose smulkiuose pokyčiuose, nes būtent jų nepamenate padarę. Nustatykite aktyvavimą ir deaktyvavimą bei pridėkite testų rinkinį kiekvienam promptui.

Baigkite informatyviausia pratyba: tyčia suaktyvinkite suprastėjusią versiją, stebėkite regresiją per testus ir vykdykite grįžimą atgal, matuodami laiką. Jei operacija trunka ilgiau nei minutę, sutvarkykite procedūrą prieš pridėdami bent vieną promptą į katalogą – lėtas grįžimas atgal nėra grįžimas, tai užsitęsęs incidentas.

Svarbiausi punktai

  • Promptai yra programinės įrangos artefaktai, kuriems reikia versijavimo
  • Kiekviena versija yra JSON arba YAML failas su metaduomenimis
  • Būsena (draft, active, deprecated) leidžia laipsnišką diegimą
  • Saugokite promptus „Git“ su testais ir pakeitimų žurnalu
  • Grįžimas atgal regresijos atveju turi būti momentinis