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

Modul JSON și aplicarea schemelor

Lecția 10 din 16 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Modul JSON și aplicarea schemelor
  2. Modul JSON vs. Ieșire Structurată
  3. Ieșire Structurată cu schemă JSON
  4. Reguli pentru Ieșirea Structurată Strictă
  5. Asistent pentru construirea schemelor
  6. Exemplu: Extragerea datelor structurate
  7. Măsurarea aportului constrângerii
  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.

Modul JSON și aplicarea schemelor

Ieșirea structurată (Structured Output) de la OpenAI garantează că răspunsul modelului este un JSON valid, care respectă o schemă definită de dumneavoastră. Nu mai este nevoie de analizarea fragilă cu expresii regulate (regex) sau de gestionarea erorilor de format; constrângerea este aplicată direct la nivelul generării.

Această nuanță este critică și schimbă totul pentru un dezvoltator. A cere „răspunde în JSON“ în prompt este o rugăminte: modelul se conformează majoritatea timpului, dar într-o zi va prefixa răspunsul cu „Iată JSON-ul solicitat:“, va adăuga backtick-uri Markdown sau va uita o virgulă, iar funcția dumneavoastră json.loads va arunca o excepție în producție la ora 3 dimineața, în timpul celui mai mare lot săptămânal. Cu Ieșirea Structurată, constrângerea se aplică în timpul decodificării: tokenii care ar produce un JSON invalid sau neconform pur și simplu nu pot fi aleși. Încetați să mai cereți și începeți să impuneți.

Modul JSON vs. Ieșire Structurată

OpenAI oferă două niveluri de constrângere, iar distincția se rezumă la un singur cuvânt. Modul JSON garantează un JSON valid fără constrângeri structurale; Ieșirea Structurată garantează un JSON care respectă o schemă JSON scrisă de dumneavoastră.

Modul JSON rezolvă doar jumătate din problemă. Sunteți sigur că puteți analiza răspunsul, dar nu sunteți sigur ce conține acesta: modelul ar putea numi un câmp annee la o cerere și year la următoarea, sau ar putea încadra lista sa într-un obiect resultats pe care nu l-a folosit cu o zi înainte. Pentru un prototip sau o afișare brută destinată unui om, acest lucru este suficient; de îndată ce ieșirea alimentează un cod care accesează câmpuri după nume, aveți nevoie de al doilea nivel.

from openai import OpenAI

client = OpenAI()

# Mod JSON simplu (JSON valid, structură liberă)
response = client.responses.create(
    model="gpt-5.6-terra",
    instructions="Always respond in JSON.",
    input="List 3 programming languages with their year of creation.",
    text={"format": {"type": "json_object"}}
)

import json
data = json.loads(response.output_text)
print(data)

Ieșire Structurată cu schemă JSON

Aceasta este cea mai puternică funcționalitate. Definiți o schemă JSON, iar API-ul garantează că ieșirea se conformează acesteia. Exemplul de mai jos analizează sentimentul unei recenzii a unui client și ilustrează trei utilizări complementare ale schemei.

Enumerația (enum) de la câmpul sentiment împiedică modelul să inventeze o categorie intermediară precum „destul de pozitiv“: acesta trebuie să aleagă între cele patru valori furnizate, făcând ieșirea direct utilizabilă într-un filtru sau tablou de bord. Descrierea (description) câmpului score acționează ca un mini-prompt local, indicând scara așteptată fără a fi nevoie să o explicați în instrucțiunile generale, și rămâne atașată câmpului chiar dacă promptul evoluează. În final, tabloul aspects vă permite să descompuneți o recenzie contradictorie—aici, un produs apreciat, dar o livrare eșuată—în loc să striviți această nuanță într-un singur scor care nu ajută pe nimeni.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Analyze the sentiment of: 'The product is excellent "
          "but the delivery was catastrophic.'",
    text={
        "format": {
            "type": "json_schema",
            "name": "sentiment_analysis",
            "schema": {
                "type": "object",
                "properties": {
                    "sentiment": {
                        "type": "string",
                        "enum": ["positive", "negative", "mixed", "neutral"]
                    },
                    "score": {
                        "type": "number",
                        "description": "Score from -1.0 (very negative) to 1.0 (very positive)"
                    },
                    "aspects": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "aspect": {"type": "string"},
                                "sentiment": {
                                    "type": "string",
                                    "enum": ["positive", "negative", "neutral"]
                                }
                            },
                            "required": ["aspect", "sentiment"],
                            "additionalProperties": False
                        }
                    },
                    "summary": {"type": "string"}
                },
                "required": ["sentiment", "score", "aspects", "summary"],
                "additionalProperties": False
            },
            "strict": True
        }
    }
)

result = json.loads(response.output_text)
# Garantat: result are exact câmpurile definite
print(f"Sentiment: {result['sentiment']}")
print(f"Score: {result['score']}")
for aspect in result["aspects"]:
    print(f"  - {aspect['aspect']}: {aspect['sentiment']}")

Reguli pentru Ieșirea Structurată Strictă

Modul strict: true impune propriile sale constrângeri asupra schemei. Toate câmpurile trebuie să apară în required, iar additionalProperties trebuie să fie false pentru fiecare obiect. Tipurile permise sunt string, number, integer, boolean, array, object și null, plus enum pentru a constrânge valorile. Totuși, nici pattern, nici minLength/maxLength nu sunt acceptate: validarea detaliată se face la nivelul clientului.

Aceste reguli pot fi surprinzătoare la prima încercare, deoarece interzic câmpul opțional așa cum este scris de obicei în JSON Schema. Compromisul este confortabil: codul dumneavoastră nu trebuie niciodată să testeze dacă o cheie există; aceasta este întotdeauna prezentă. Pentru un câmp care poate fi legitim gol—un număr de telefon lipsă dintr-un document, o dată de sfârșit pentru un contract în curs—răspunsul nu este să îl eliminați din required, ci să permiteți să fie null. În ceea ce privește absența lui pattern și a limitelor de lungime, aceasta semnalează lecția următoare: schema garantează forma, dar validarea logică de afaceri rămâne sarcina dumneavoastră odată ce răspunsul este primit.

Asistent pentru construirea schemelor

Scrierea manuală a blocului text.format pentru fiecare apel devine rapid obositoare și predispusă la greșeli de tastare—o cheie name lipsă, un strict plasat greșit, iar eroarea vine de la API fără a indica unde să căutați. Câteva linii de cod wrapper centralizează structura, aplică o temperatură scăzută implicit (deoarece variabilitatea nu aduce nimic extragerii) și fac locul apelului lizibil.

def structured_query(prompt: str, schema: dict,
                     schema_name: str = "response",
                     model: str = "gpt-5.6-terra",
                     system: str = "") -> dict:
    """Wrapper pentru cererile de Ieșire Structurată."""
    response = client.responses.create(
        model=model,
        reasoning={"effort": "none"},  # temperatura necesită efort none
        instructions=system or "Respond in JSON according to the provided schema.",
        input=prompt,
        text={
            "format": {
                "type": "json_schema",
                "name": schema_name,
                "schema": schema,
                "strict": True
            }
        },
        temperature=0.1
    )
    return json.loads(response.output_text)

Exemplu: Extragerea datelor structurate

Iată cazul de utilizare care singur justifică învățarea acestei tehnici: transformarea unei facturi primite ca text simplu într-un obiect utilizabil de sistemul dumneavoastră de contabilitate. Schema descrie trei niveluri—antetul facturii, un obiect imbricat vendor și un tablou lines unde fiecare element are aceeași formă. Modelul trebuie, prin urmare, să localizeze informațiile împrăștiate în document și să le plaseze în locul potrivit, inclusiv pentru o linie exprimată în ore și nu în unități, unde prețul unitar este înțeles ca o rată orară.

Rețineți că totalurile apar în schemă ca câmpuri de extras, nu de recalculat. Cerem modelului să citească; controlul aritmetic are loc ulterior în codul dumneavoastră, unde o simplă comparație între suma liniilor și total_ht extras va semnala documentele pentru revizuire umană.

invoice_schema = {
    "type": "object",
    "properties": {
        "invoice_number": {"type": "string"},
        "date": {"type": "string"},
        "vendor": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "siret": {"type": "string"},
                "address": {"type": "string"}
            },
            "required": ["name", "siret", "address"],
            "additionalProperties": False
        },
        "lines": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "description": {"type": "string"},
                    "quantity": {"type": "integer"},
                    "unit_price_excl_tax": {"type": "number"},
                    "vat_percent": {"type": "number"}
                },
                "required": ["description", "quantity",
                             "unit_price_excl_tax", "vat_percent"],
                "additionalProperties": False
            }
        },
        "total_excl_tax": {"type": "number"},
        "total_incl_tax": {"type": "number"}
    },
    "required": ["invoice_number", "date", "vendor",
                  "lines", "total_excl_tax", "total_incl_tax"],
    "additionalProperties": False
}

invoice_text = """
Invoice No. 2026-0042
Date: 15/03/2026
Vendor: TechServ SARL, SIRET 123 456 789 00012
12 rue de la Paix, 75002 Paris

- REST API Development x1: 3500.00 EUR excl. tax (VAT 20%)
- Cloud hosting (3 months) x1: 450.00 EUR excl. tax (VAT 20%)
- Technical support x10h: 150.00 EUR excl. tax/h (VAT 20%)

Total excl. tax: 5450.00 EUR
Total incl. tax: 6540.00 EUR
"""

result = structured_query(
    invoice_text,
    invoice_schema,
    schema_name="invoice",
    system="Extract the data from this invoice."
)

Măsurarea aportului constrângerii

Aplicați acest principiu unui document pe care îl cunoașteți bine: definiți o schemă JSON pentru a extrage informațiile cheie dintr-un CV—nume, experiență, competențe, educație—și testați-o pe trei CV-uri în text simplu, alese deliberat pentru aspectele lor eterogene. Verificați dacă ieșirea respectă schema chiar și atunci când o secțiune lipsește complet.

Apoi repetați aceeași extragere fără Ieșire Structurată, cerând pur și simplu JSON în prompt, și păstrați cele șase ieșiri una lângă alta. Compararea celor două serii arată ce aduce constrângerea: diferența rareori constă în conținutul extras, ci aproape întotdeauna în stabilitatea numelor câmpurilor și în prezența cheilor așteptate.

Puncte cheie

  • Ieșirea Structurată garantează un JSON conform schemei la nivelul generării
  • Utilizați strict: true pentru conformitate maximă
  • Toate câmpurile trebuie să fie required cu additionalProperties: false
  • Ideal pentru extragerea datelor, clasificare și fluxuri de procesare
  • Validarea detaliată (lungime, model) se face la nivelul clientului după recepție