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

Rezultat structurat: JSON garantat

Lecția 9 din 22 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Rezultat structurat: JSON garantat
  2. Problema pe care o rezolvă
  3. Pydantic în locul schemelor JSON scrise manual
  4. Două cazuri de utilizare frecvente
  5. Ce impune modul strict
  6. Puncte cheie

Rezultat structurat: JSON garantat

Rezultatul structurat (Structured Output) este una dintre cele mai puternice funcționalități ale API-ului Responses. În loc să sperați că modelul va returna un JSON valid, îl garantați furnizând o schemă. Modelul este apoi constrâns structural să o respecte. Aceasta transformă un model lingvistic dintr-un generator creativ de text într-o componentă fiabilă a unui flux de procesare automatizat.

Problema pe care o rezolvă

Solicitarea unui JSON direct în prompt funcționează de cele mai multe ori, ceea ce face tocmai această abordare periculoasă. O dată la o sută, modelul își prefixează răspunsul cu o propoziție introductivă, încadrează totul într-un bloc de cod Markdown sau redenumește un câmp, iar funcția dumneavoastră json.loads() aruncă o excepție în producție pentru o cerere pe care nu o puteți reproduce.

from openai import OpenAI
client = OpenAI()

# Fără structură — modelul poate returna orice format
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Give me info about Paris in JSON."
)
print(response.output_text)
# Rezultat imprevizibil:
# Uneori JSON valid, uneori text care conține JSON,
# uneori un format neașteptat...

Parametrul text schimbă natura garanției. Declarați un format json_schema împreună cu schema așteptată, iar ieșirea se va conforma acesteia: deserializarea devine o operațiune sigură.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Give me information about Paris.",
    text={
        "format": {
            "type": "json_schema",
            "name": "city_info",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "country": {"type": "string"},
                    "population": {"type": "integer"},
                    "official_language": {"type": "string"},
                    "landmarks": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                },
                "required": ["name", "country", "population", "official_language", "landmarks"],
                "additionalProperties": False
            }
        }
    }
)

import json
data = json.loads(response.output_text)
print(f"City: {data['name']}")
print(f"Population: {data['population']:,}")
print(f"Landmarks: {', '.join(data['landmarks'])}")

# Rezultat GARANTAT a fi JSON valid:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur

Pydantic în locul schemelor JSON scrise manual

Scrierea schemelor manual devine rapid obositoare și predispusă la greșeli de tastare. Pydantic vă permite să le descrieți ca clase Python, să generați schema JSON cu model_json_schema() și apoi să validați și să tipizați răspunsul cu model_validate_json(). La capătul lanțului, obțineți un obiect Python complet, cu autocompletare în editor, în loc de un dicționar anonim.

from pydantic import BaseModel
from typing import Optional
import json

class Product(BaseModel):
    name: str
    price: float
    category: str
    in_stock: bool
    description: Optional[str] = None

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Describe a high-end gaming laptop.",
    text={
        "format": {
            "type": "json_schema",
            "name": "product",
            "strict": True,
            "schema": Product.model_json_schema()
        }
    }
)

# Analizare și validare cu Pydantic
product = Product.model_validate_json(response.output_text)
print(f"Product: {product.name}")
print(f"Price: {product.price} EUR")
print(f"In stock: {'Yes' if product.in_stock else 'No'}")

# Rezultat:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes

Nimic nu vă limitează la structuri plate. Prin compunerea claselor, descrieți obiecte imbricate și liste de obiecte, de care veți avea nevoie imediat ce creați un profil realist de client: o companie conține contacte, iar fiecare contact are o adresă.

from pydantic import BaseModel

class Address(BaseModel):
    street: str
    city: str
    postal_code: str
    country: str

class Contact(BaseModel):
    last_name: str
    first_name: str
    email: str
    phone: str
    address: Address

class Company(BaseModel):
    name: str
    sector: str
    employees: int
    contacts: list[Contact]

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Generate a fictional company profile in the tech sector "
          "with 2 contacts.",
    text={
        "format": {
            "type": "json_schema",
            "name": "company",
            "strict": True,
            "schema": Company.model_json_schema()
        }
    }
)

company = Company.model_validate_json(response.output_text)
print(f"Company: {company.name} ({company.sector})")
for c in company.contacts:
    print(f"  - {c.first_name} {c.last_name}: {c.email}")

Două cazuri de utilizare frecvente

Primul este extragerea: transformarea textului scris într-o înregistrare utilizabilă. Un anunț de conferință redactat în limbaj natural devine un rând în baza de date cu titlu, dată, locație și număr de participanți – fără expresii regulate și fără a se strica de fiecare dată când formularea se schimbă.

class Event(BaseModel):
    title: str
    date: str
    location: str
    attendees: int

text = """
The PyCon France 2026 conference will be held on November 15 and 16
at the Palais des Congrès in Lyon. More than 800 Python developers
are expected for this edition.
"""

response = client.responses.create(
    model="gpt-5.6-terra",
    input=f"Extract the information from this event:\n{text}",
    text={
        "format": {
            "type": "json_schema",
            "name": "event",
            "strict": True,
            "schema": Event.model_json_schema()
        }
    }
)

evt = Event.model_validate_json(response.output_text)
print(f"{evt.title} - {evt.date} at {evt.location} ({evt.attendees} attendees)")
# Result: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)

Al doilea este clasificarea. Prin declararea unei enumerări, restricționați modelul la un vocabular închis: acesta nu poate răspunde „destul de pozitiv“ sau „pozitiv“ atunci când codul dumneavoastră se așteaptă la positive. Aceasta este diferența dintre o valoare pe care o puteți utiliza direct și una pe care trebuie să o normalizați ulterior.

from enum import Enum

class Sentiment(str, Enum):
    positive = "positive"
    negative = "negative"
    neutral = "neutral"

class Analysis(BaseModel):
    sentiment: Sentiment
    confidence: float
    keywords: list[str]

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Analyze this comment: 'Great service, fast delivery!'",
    text={
        "format": {
            "type": "json_schema",
            "name": "sentiment_analysis",
            "strict": True,
            "schema": Analysis.model_json_schema()
        }
    }
)

analysis = Analysis.model_validate_json(response.output_text)
print(f"Sentiment: {analysis.sentiment.value} ({analysis.confidence:.0%})")
# Result: Sentiment: positive (95%)

Ce impune modul strict

Garanția vine cu un compromis: când strict: True, schema trebuie să adere la un subset specific de JSON Schema. Aceste constrângeri sunt cauza principală a erorilor 400 pentru începători, așa că este bine să le cunoașteți înainte de a le întâlni:

  • Toate proprietățile trebuie listate în required
  • additionalProperties trebuie să fie False
  • Tipuri suportate: string, number, integer, boolean, array, object, null
  • Fără oneOf sau anyOf cu tipuri mixte
  • Utilizați Optional[str], care se traduce prin {"anyOf": [{"type": "string"}, {"type": "null"}]}

Regula privind required îi surprinde adesea pe utilizatori: un câmp opțional nu este exprimat prin eliminarea sa din listă, ci prin允许area valorii null, exact ceea ce produce Optional[str] din partea Pydantic.

Puncte cheie

  • Rezultatul structurat garantează că răspunsul respectă schema dumneavoastră JSON
  • Utilizați text={"format": {"type": "json_schema", ...}} în API-ul Responses
  • Pydantic este instrumentul ideal pentru definirea și validarea schemelor
  • Activați strict: True pentru conformitate garantată la schemă
  • Ideal pentru extragerea datelor, clasificare și generare structurată