Versionarea prompturilor și gestionarea catalogului
Pe această pagină
Lecție actualizată la 3 noiembrie 2026 pe baza documentației OpenAI: parametrii
temperatureșitop_psunt acceptați doar cu un efort de raționament denone, în timp ce modelele GPT-5.6 raționează implicit (medium). Apelurile care setează acești parametri trebuie, prin urmare, să specificereasoning={"effort": "none"}(API-ul Responses) saureasoning_effort="none"(Chat Completions). Surse: Utilizarea GPT-6 · GPT-5.6 Terra.
Versionarea prompturilor și gestionarea catalogului
În producție, prompturile dumneavoastră evoluează la fel de mult ca și codul. Fără versionare, pierdeți șirul modificărilor, nu puteți reveni la o stare anterioară și nu aveți nicio idee despre ce versiune rulează în producție. Această lecție vă arată cum să gestionați prompturile ca artefacte software.
De ce să versionați prompturile
O modificare a unui prompt poate altera radical comportamentul aplicației dumneavoastră. Spre deosebire de cod, aceste modificări sunt adesea subtile și greu de detectat fără teste automate: o frază reformulată, un cuvânt mutat și modelul începe să clasifice greșit unul din zece cazuri limită. Niciun test unitar standard nu va prinde această discrepanță, dar echipa de suport o va semnala trei săptămâni mai târziu sub forma unei plângeri vagi despre tichete direcționate eronat.
Versionarea răspunde la patru nevoi distincte. În primul rând, trasabilitatea: știința cine a modificat ce și când transformă o dezbatere sterilă în echipă într-o simplă verificare a istoricului. În al doilea rând, revenirea la starea anterioară (rollback): când apare o regresie, obiectivul imediat nu este să înțelegeți de ce, ci să restaurați un comportament cunoscut. În al treilea rând, compararea performanței: acest lucru necesită ca versiunile mai vechi să rămână executabile exact așa cum au fost, cu modelul și setările lor originale. În final, auditul: pentru sistemele supuse GDPR (Regulamentul General privind Protecția Datelor) sau altor cadre de conformitate, trebuie să demonstrați ce instrucțiuni erau în vigoare la o anumită dată – o simplă captură de ecran nu este suficientă.
Structura catalogului
Clasa PromptCatalog răspunde acestor nevoi cu o infrastructură minimă: un dosar per prompt, un fișier JSON per versiune, numerotate secvențial. Fiecare fișier grupează textul promptului de sistem împreună cu modelul asociat și temperatura – un prompt calibrat la 0.1 și același prompt la 0.7 nu sunt același lucru, iar blocarea lor împreună previne restaurarea textului uitând setările sale.
Câmpul status urmărește ciclul de viață. O versiune începe ca draft (ciornă), permițând pregătirea și testarea fără a afecta traficul live. Apelarea metodei activate o comută în active și retrogradează automat versiunea anterioară la deprecated (depreciată), asigurând că doar o singură versiune deservește traficul în orice moment. Această metodă face rollback-ul trivial: reactivarea unei versiuni anterioare este un singur apel, nu o nouă implementare. Aplicația dumneavoastră apelează get_active în producție, în timp ce list_versions suportă revizuirile și auditurile.
import json
from datetime import datetime
from pathlib import Path
class PromptCatalog:
"""Gestionar de catalog de prompturi cu versionare."""
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:
"""Salvează o nouă versiune a unui prompt."""
prompt_dir = self.catalog_dir / name
prompt_dir.mkdir(exist_ok=True)
# Determină numărul versiunii
versions = sorted(prompt_dir.glob("v*.json"))
version = len(versions) + 1
version_str = f"v{version:03d}"
# Salvează
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:
"""Recuperează un prompt după nume și versiune."""
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:
"""Recuperează versiunea activă a unui 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):
"""Activează o versiune și dezactivează celelalte."""
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]:
"""Listează toate versiunile unui 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
Utilizarea catalogului în aplicația dumneavoastră
Din partea apelantului, regula este simplă: codul dumneavoastră nu conține niciun text de prompt; acesta solicită versiunea activă din catalog. Acest lucru menține prompturile modificabile fără a atinge codul aplicației și previne îngroparea șirurilor de treizeci de linii în mijlocul unei funcții. Metadatele salvate în timpul stocării – autor, descriere, jurnal de modificări – nu au niciun efect asupra execuției, dar fac istoricul lizibil peste șase luni, când nimeni nu mai ține minte de ce s-a schimbat formularea.
Detaliul critic se află la sfârșitul funcției classifier_ticket: răspunsul returnat include prompt_version. Înregistrați în jurnal (log) acest câmp cu fiecare rezultat, iar analiza incidentelor devine posibilă – veți ști că tichetele clasificate eronat în după-amiaza de marți provin toate din v004, fără a necesita corelarea cu timestamp-urile de implementare.
from openai import OpenAI
client = OpenAI()
catalog = PromptCatalog("prompts/")
# Salvează un 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": "Clasificarea automată a tichetelor Zendesk",
"changelog": "Versiune inițială"
}
)
# În producție: utilizează versiunea activă
def classifier_ticket(ticket_text: str) -> dict:
"""Clasifică un tichet folosind promptul activ."""
prompt_config = catalog.get_active("ticket-classifier")
response = client.responses.create(
model=prompt_config["model"],
reasoning={"effort": "none"}, # temperatura necesită efort 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"]
}
Versionarea cu Git
Pentru echipe, stocați-vă prompturile într-un repository Git dedicat. Arborele de mai jos urmează o convenție simplă: un dosar per prompt, conținând definiția sa, cazurile de test și jurnalul de modificări. Păstrarea testelor alături de promptul pe care îl verifică nu este un moft – un pull request modifică ambele elemente împreună, iar recenzorul judecă modificarea pe baza dovezilor, nu a intenției declarate.
prompts/
ticket-classifier/
prompt.yaml
tests/
test_cases.json
CHANGELOG.md
invoice-extractor/
prompt.yaml
tests/
test_cases.json
CHANGELOG.md
YAML înlocuiește aici JSON dintr-un motiv specific: prompturile sunt texte pe mai multe linii, iar sintaxa | le afișează exact așa cum sunt trimise, fără caractere de evadare sau \n stray. Un diff Git pe acest fișier se citește ca un diff de proză – recenzorul vede că a fost adăugată o propoziție. Schema de ieșire călătorește în același fișier, astfel încât configurația completă pentru un apel încapă într-un singur artefact.
# 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
Cele mai bune practici
Ceea ce separă un catalog viu de un dosar de arhivă se rezumă la câteva reguli de întreținere. Păstrați un singur prompt per fișier: amestecarea mai multor prompturi într-un singur document face diff-urile ilizibile și rollback-urile imposibil de țintit. Impuneți un jurnal de modificări (changelog) care să documenteze nu ce s-a schimbat – diff-ul arată asta – ci de ce: „adăugată instrucțiune privind tichetele multilingve în urma feedback-ului suportului“ valorează cât zece linii de descriere tehnică.
Asociați sistematic o suită de teste fiecărui prompt; în caz contrar, utilizatorii vor fi primii care vă vor spune când o modificare strică un comportament stabilit. Dirijați modificările de prompturi prin același proces de revizuire a codului ca și codul însuși: un prompt care ajunge în producție fără revizuire produce aceleași surprize ca un cod nerevizuit. Verificați dacă rollback-ul durează mai puțin de un minut și testați-l într-o zi liniștită, nu în timpul unui incident. În final, marcați versiunile implementate cu tag-uri pentru a lega fără echivoc comportamentul observat de o stare specifică a repository-ului.
Testarea catalogului cu un rollback
Configurați un PromptCatalog pentru trei prompturi reale din aplicația dumneavoastră, apoi înregistrați două sau trei versiuni pentru fiecare, evoluând instrucțiunile în pași mici – o instrucțiune de ton, o categorie adăugată. Versionarea își dovedește valoarea în cazul acestor modificări fine, deoarece acestea sunt cele pe care nu vă veți aminti că le-ați făcut. Configurați activarea și dezactivarea și atașați o suită de teste fiecărui prompt.
Terminați cu exercițiul cel mai instructiv: activați deliberat o versiune degradată, observați regresia prin teste și executați rollback-ul cronometrând operațiunea. Dacă operațiunea depășește un minut, remediați procedura înainte de a adăuga un singur prompt în catalog – un rollback lent nu este un rollback, ci un incident prelungit.
Puncte cheie
- Prompturile sunt artefacte software care necesită versionare
- Fiecare versiune este un fișier JSON sau YAML cu metadate
- Statusul (draft, active, deprecated) permite o implementare graduală
- Stocați prompturile în Git împreună cu testele și un changelog
- Rollback-ul trebuie să fie instantaneu în caz de regresie