Rezultat structurat: JSON garantat
Pe această pagină
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 additionalPropertiestrebuie să fieFalse- Tipuri suportate:
string,number,integer,boolean,array,object,null - Fără
oneOfsauanyOfcu 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: Truepentru conformitate garantată la schemă - Ideal pentru extragerea datelor, clasificare și generare structurată