Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Output Istrutturat: JSON Garantit

Lezzjoni 9 / 22 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Output Istrutturat: JSON Garantit
  2. Il-problema li ssolvi
  3. Pydantic minflok JSON Schema miktub bl-idejn
  4. Żewġ każijiet ta’ użu komuni
  5. X’titlob il-modalità stretta (strict mode)
  6. Punti Ewlenin

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
  • additionalProperties għandu jkun False
  • Tipi appoġġjati: string, number, integer, boolean, array, object, null
  • L-ebda oneOf jew anyOf b’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: True għal konformità garantita mal-iskema
  • Ideali għall-estrazzjoni tad-data, il-klassifikazzjoni u l-ġenerazzjoni strutturata