Output Istrutturat: JSON Garantit
F'din il-paġna
Output Istrutturat: JSON Garantit
L-Output Istrutturat huwa waħda mill-aktar karatteristiċi qawwija tal-API tar-Risposti. Minflok ma ttama li l-mudell jirritorna JSON validu, inti tiggarantixxih billi tipprovdi skema. Imbagħad, il-mudell ikun kostrett strutturalment li jsegwiha. Dan ibiddel mudell tal-lingwa minn ġeneratur kreattiv ta’ test f’komponent affidabbli ta’ pipeline ta’ pproċessar awtomatizzat.
Il-problema li ssolvi
It-talba għal JSON fil-prompt taħdem il-biċċa l-kbira tal-ħin, li huwa preċiżament dak li jagħmel dan l-approċċ perikoluż. Darba minn mitt, il-mudell jippreċedi r-risposta tiegħu b’sentenza introduttorja, jgħaqqad kollox f’blokka ta’ kodiċi Markdown, jew ibiddel isem qasam—u l-json.loads() tiegħek itfa’ eċċezzjoni fil-produzzjoni fuq talba li ma tistax tirriproduċi.
from openai import OpenAI
client = OpenAI()
# Mingħajr struttura — il-mudell jista' jirritorna kwalunkwe format
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me info about Paris in JSON."
)
print(response.output_text)
# Riżultat mhux prevedibbli:
# Xi kultant JSON validu, xi kultant test li fih JSON,
# xi kultant format mhux mistenni...
Il-parametru text ibiddel in-natura tal-garanzija. Inti tiddikjara format json_schema flimkien mal-iskema mistennija, u l-output jikkonforma magħha: id-deserjalizzazzjoni ssir operazzjoni sikura.
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'])}")
# Riżultat GARANTIT li jkun JSON validu:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur
Pydantic minflok JSON Schema miktub bl-idejn
Il-kitba ta’ skemi bl-idejn malajr issir tedjanti u suxxettibbli għal żbalji tat-typing. Pydantic jippermettilek tiddeskrivihom bħala klassijiet Python, tiġġenera l-JSON Schema b’model_json_schema(), u mbagħad tivvalida u ttajpja r-risposta b’model_validate_json(). Fl-aħħar tal-katina, tikseb oġġett Python sħiħ b’awtokompletament tal-editur, minflok dizzjunarju anonimu.
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()
}
}
)
# Ipparsja u vvalida ma' 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'}")
# Riżultat:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes
Xejn ma jillimitak għal strutturi ċatti. Billi tikkumponi klassijiet, tiddeskrivi oġġetti mbejjta u listi ta’ oġġetti, li se jkollok bżonnhom hekk kif toħloq profil ta’ klijent realistiku: kumpanija fiha kuntatti, u kull kuntatt għandu indirizz.
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}")
Żewġ każijiet ta’ użu komuni
L-ewwel huwa l-estrazzjoni: li tbiddel test miktub f’rekord utilizzabbli. Avviż ta’ konferenza miktub f’lingwa naturali jsir ringiela ta’ database b’titolu, data, post, u għadd ta’ parteċipanti—mingħajr espressjonijiet regolari, u mingħajr ma jinkiser kull darba li tinbidel il-formulazzjoni.
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)")
# Riżultat: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)
It-tieni hija l-klassifikazzjoni. Billi tiddikjara enumerazzjoni, tillimita l-mudell għal vokabolarju magħluq: ma jistax iwieġeb “pjuttost pożittiv” jew “pożittiv” meta l-kodiċi tiegħek jistenna positive. Din hija d-differenza bejn valur li tista’ tuża direttament u valur li trid tinnormalizza wara.
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%})")
# Riżultat: Sentiment: positive (95%)
X’titlob il-modalità stretta (strict mode)
Il-garanzija ġġib magħha kompromess: meta strict: True, l-iskema trid taderixxi ma’ sottoinsiem speċifiku ta’ JSON Schema. Dawn il-vincoli huma l-kawża ewlenija ta’ żbalji 400 għall-bidu, għalhekk huwa aħjar li tkun tafihom qabel ma tiltaqa’ magħhom:
- Il-proprjetajiet kollha għandhom ikunu elenkati f’
required additionalPropertiesgħandu jkunFalse- Tipi appoġġjati:
string,number,integer,boolean,array,object,null - L-ebda
oneOfjewanyOfb’tipi mħallta - Uża
Optional[str], li jittraduċi għal{"anyOf": [{"type": "string"}, {"type": "null"}]}
Ir-regola dwar required spiss tissorpriża lin-nies: qasam opzjonali ma jiġix espress billi titneħħa mil-lista, iżda billi tippermetti l-valur null, eżattament dak li Optional[str] jipproduċi fuq in-naħa ta’ Pydantic.
Punti Ewlenin
- L-Output Istrutturat jiggarantixxi li r-risposta taderixxi mal-iskema JSON tiegħek
- Uża
text={"format": {"type": "json_schema", ...}}fl-API tar-Risposti - Pydantic huwa l-għodda ideali biex tiddefinixxi u tivvalida skemi
- Ippermetti
strict: Truegħal konformità garantita mal-iskema - Ideali għall-estrazzjoni tad-data, il-klassifikazzjoni u l-ġenerazzjoni strutturata