Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Verżjonar tal-prompts u ġestjoni tal-katalogu

Lezzjoni 14 / 16 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Verżjonar tal-prompts u ġestjoni tal-katalogu
  2. Għaliex tipverżjona l-prompts
  3. Struttura tal-katalogu
  4. Użu tal-katalogu fl-applikazzjoni tiegħek
  5. Verżjonar b’Git
  6. Aħjar prattiki
  7. Ittestja l-katalogu b’rollback
  8. Punti Ewlenin

Lezzjoni aġġornata fit-3 ta’ Novembru 2026 abbażi tad-dokumentazzjoni ta’ OpenAI: temperature u top_p huma aċċettati biss b’sforz ta’ raġunar ta’ none, filwaqt li l-mudelli GPT-5.6 jirraġunaw b’mod awtomatiku (medium). Għalhekk, is-sejħiet li jistabbilixxu dawn il-parametri jridu jispeċifikaw reasoning={"effort": "none"} (Responses API) jew reasoning_effort="none" (Chat Completions). Sorsi: L-użu ta’ GPT-6 · GPT-5.6 Terra.

Verżjonar tal-prompts u ġestjoni tal-katalogu

Fil-produzzjoni, il-prompts tiegħek jevolvu daqs il-kodiċi tiegħek. Mingħajr verżjonar, titlef il-kont tal-bidliet, ma tistax terġa’ lura, u m’għandekx idea liema verżjoni qed taħdem fil-produzzjoni. Din il-lezzjoni turi kif tiġġestixxi l-prompts bħala artefatti tas-software.

Għaliex tipverżjona l-prompts

Bidla fil-prompt tista’ tbiddel radikalment l-imġiba tal-applikazzjoni tiegħek. B’kuntrarju għall-kodiċi, dawn il-bidliet spiss ikunu sottili u diffiċli biex jiskopruhom mingħajr testijiet awtomatizzati: sentenza riformulata, kelma li bdiltilha postha, u l-mudell jibda jikklassifika ħażin każ fruntiera wieħed minn għaxra. L-ebda unit test standard ma jaqbad dan id-distakk, iżda s-support jinnotah tliet ġimgħat wara bħala lment ġeneriku dwar tickets diretti ħażin.

Il-verżjonar jindirizza erba’ bżonnijiet distinti. L-ewwel, it-traċċabbiltà: li tkun taf min biddel x’ u meta jibdel diskussjoni sterili ta’ tim f’ċekk sempliċi tal-istorja. It-tieni, ir-rollback: meta tidher reġressjoni, l-għan immedjat mhuwiex li tifhem għaliex, imma li terġa’ tistabbilixxi l-imġiba magħrufa. It-tielet, it-tqabbil tal-prestazzjoni: dan jeħtieġ li l-verżjonijiet il-qodma jibqgħu eżegwibbli eżatt kif kienu, bil-mudell u l-parametri oriġinali tagħhom. Fl-aħħarnett, l-auditing: għal sistemi soġġetti għall-GDPR (Regolament Ġenerali dwar il-Protezzjoni tad-Data) jew għal frameworks ta’ konformità oħra, trid turi liema struzzjonijiet kienu fis-seħħ f’data partikolari—screenshot mhux biżżejjed.

Struttura tal-katalogu

Il-klassi PromptCatalog tilħaq dawn il-bżonnijiet b’infrastruttura minima: folder għal kull prompt, fajl JSON għal kull verżjoni, numerati b’mod sekwenzjali. Kull fajl jiġbor fih it-test tas-system prompt flimkien mal-mudell u l-temperature assoċjati—prompt b’temperature ta’ 0.1 u l-istess prompt b’0.7 mhumiex l-istess ħaġa, u li tgħaqqadhom flimkien jipprevjeni li terġa’ tistabbilixxi t-test u tintesa’ l-parametri tiegħu.

Il-kamp status iġib il-lifecycle. Verżjoni tibda bħala draft, li tippermetti tħejjija uittestjar mingħajr ma taffettwa t-traffiku live. Sejħa ta’ activate tbiddilha għal active u awtomatikament tniżżel il-verżjoni preċedenti għal deprecated, u tiżgura li verżjoni waħda biss isservi t-traffiku f’kull ħin. Dan il-metodu jagħmel ir-rollback banali: li terġa’ tattiva verżjoni ta’ qabel hija sejħa waħda, mhux depljament. L-applikazzjoni tiegħek issejjaħ get_active fil-produzzjoni, filwaqt li list_versions isservi r-reviews u l-audits.

import json
from datetime import datetime
from pathlib import Path

class PromptCatalog:
    """Prompt catalog manager with versioning."""

    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:
        """Saves a new version of a prompt."""
        prompt_dir = self.catalog_dir / name
        prompt_dir.mkdir(exist_ok=True)

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

        # Save
        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:
        """Retrieves a prompt by name and version."""
        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:
        """Retrieves the active version of a prompt."""
        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):
        """Activates a version and deactivates others."""
        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]:
        """Lists all versions of a prompt."""
        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

Użu tal-katalogu fl-applikazzjoni tiegħek

Fuq in-naħa tal-caller, ir-regola hija sempliċi: il-kodiċi tiegħek ma fihx it-test ta’ prompt; jitlob il-verżjoni attiva mill-katalogu. Dan iżomm il-prompts modifikabbli mingħajr ma tmiss il-kodiċi tal-applikazzjoni, u jipprevjeni li stringijiet ta’ tletin linja jkunu midfuna f’nofs funzjoni. Il-metadata maħżuna waqt il-ħażna—awtur, deskrizzjoni, changelog—ma għandha l-ebda effett fuq l-eżekuzzjoni iżda tagħmel l-istorja leġġibbli sitt xhur wara, meta ħadd ma jiftakar għaliex inbidlu l-kliem.

Id-dettal kritiku jinsab fit-tmiem ta’ classifier_ticket: ir-risposta lura tinkludi prompt_version. Irrreġistra dan il-kamp ma’ kull riżultat, u l-analiżi tal-inċidenti ssir possibbli—tkun taf li t-tickets ikklassifikati ħażin ta’ wara nofsinhar it-Tlieta ġejjin kollha minn v004, mingħajr ma tqabbel it-timstamps tad-depljament.

from openai import OpenAI

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

# Save a 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": "Automatic classification of Zendesk tickets",
        "changelog": "Initial version"
    }
)

# In production: use the active version
def classifier_ticket(ticket_text: str) -> dict:
    """Classifies a ticket using the active prompt."""
    prompt_config = catalog.get_active("ticket-classifier")

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

Verżjonar b’Git

Għal timijiet, ħażen il-prompts f’repo Git iddedikat. Is-siġra hawn taħt issegwi konvenzjoni sempliċi: folder għal kull prompt, li fih id-definizzjoni, il-każijiet ta’ test, u changelog. Li żżomm it-testijiet maġenb il-prompt li jiċċekkjaw mhuwiex kosmetiku—pull request tbiddel it-tnejn flimkien, u r-reviewer jiġġudika l-bidla fuq l-evidenza u mhux fuq l-intenzjoni ddikjarata.

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

YAML jieħu post JSON hawn għal raġuni preċiża: il-prompts huma testi b’ħafna linji, u s-sintassi | turihom eżatt kif jintbagħtu, mingħajr escaping jew karattri \n ħarġin. Diff ta’ Git fuq dan il-fajl jinqara bħala diff ta’ prosa—ir-reviewer jara li żdiedet sentenza. L-output schema jivvjaġġa fl-istess fajl, u għalhekk il-konfigurazzjoni kompluta għal sejħa tidħol f’artefatt wieħed.

# 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

Aħjar prattiki

Dak li jifred katalogu ħaj minn folder ta’ arkivju jinvol xi regoli żgħar ta’ tindif. Żomm prompt għal kull fajl: li taħlat diversi prompts f’dokument wieħed jagħmel id-diffs ma jinqrawx u r-rollbacks impossibbli li timmirahom. Infurza changelog li ddokumenta mhux x’inbidel—id-diff juri dak—imma għaliex: “żdiedet istruzzjoni dwar tickets multilingual wara feedback tas-support” ta’ valur għaxar linji ta’ deskrizzjoni teknika.

Assoċja sistemikament suite ta’ testijiet ma’ kull prompt; inkella, l-utenti se jkunu l-ewwel jgħidulek meta modifika tkisser imġiba stabbilita. Għaddi l-bidliet fil-prompt mill-istess proċess ta’ code review tal-kodiċi innifsu: prompt li jmur għall-produzzjoni mingħajr review jagħti l-istess sorpriżi ta’ kodiċi mhux reviewed. Ivverifika li r-rollback jieħu anqas minn minuta, u ttestjah f’jum kwieta u mhux waqt inċident. Fl-aħħarnett, immarka l-verżjonijiet iddeplikati b’tags biex torbot mingħajr ambigwità l-imġiba osservata ma’ stat partikolari tar-repo.

Ittestja l-katalogu b’rollback

Issettja PromptCatalog għal tliet prompts reali mill-applikazzjoni tiegħek, imbagħad irreġistra żewġ jew tliet verżjonijiet għal kull wieħed billi tevolvi l-istruzzjonijiet f’passi żgħar—istruzzjoni fuq it-ton, kategorija miżjuda. Il-verżjonar juri l-valur tiegħu f’dawn il-bidliet fini, għax huma dawk li mhux se tiftakar għamilt. Issettja l-attivazzjoni u d-diżattivazzjoni, u waħħal suite ta’ testijiet ma’ kull prompt.

Spiċċa bl-eżerċizzju l-aktar sinifikanti: attiva verżjoni dgħajfa intenzjonalment, osserva r-reġressjoni permezz tat-testijiet, u wettaq ir-rollback filwaqt li tkejjel il-ħin. Jekk l-operazzjoni taqbeż minuta, irrevedi l-proċedura qabel ma żżid anke prompt wieħed mal-katalogu—rollback bil-mod mhuwiex rollback, huwa inċident imtawwal.

Punti Ewlenin

  • Il-prompts huma artefatti tas-software li jeħtieġu verżjonar
  • Kull verżjoni hija fajl JSON jew YAML b’metadata
  • L-istatus (draft, active, deprecated) jippermetti depljament gradwali
  • Ħażen il-prompts f’Git flimkien mat-testijiet u ma’ changelog
  • Ir-rollback irid ikun istantanju f’każ ta’ reġressjoni