Salt la conținutul principal
Română— Alege o limbă
Meniu

Versionarea prompturilor și gestionarea catalogului

Lecția 14 din 16 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Versionarea prompturilor și gestionarea catalogului
  2. De ce să versionați prompturile
  3. Structura catalogului
  4. Utilizarea catalogului în aplicația dumneavoastră
  5. Versionarea cu Git
  6. Cele mai bune practici
  7. Testarea catalogului cu un rollback
  8. Puncte cheie

Lecție actualizată la 3 noiembrie 2026 pe baza documentației OpenAI: parametrii temperature și top_p sunt acceptați doar cu un efort de raționament de none, în timp ce modelele GPT-5.6 raționează implicit (medium). Apelurile care setează acești parametri trebuie, prin urmare, să specifice reasoning={"effort": "none"} (API-ul Responses) sau reasoning_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