Verżjonar tal-prompts u ġestjoni tal-katalogu
F'din il-paġna
Lezzjoni aġġornata fit-3 ta’ Novembru 2026 abbażi tad-dokumentazzjoni ta’ OpenAI:
temperatureutop_phuma 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ċifikawreasoning={"effort": "none"}(Responses API) jewreasoning_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