Δομημένη Έξοδος: Εγγυημένο JSON
Σε αυτήν τη σελίδα
Δομημένη Έξοδος: Εγγυημένο JSON
Η Δομημένη Έξοδος (Structured Output) αποτελεί ένα από τα πιο ισχυρά χαρακτηριστικά του Responses API. Αντί να ελπίζετε ότι το μοντέλο θα επιστρέψει έγκυρο JSON, το εγγυάστε παρέχοντας ένα σχήμα (schema). Το μοντέλο περιορίζεται δομικά ώστε να το ακολουθεί. Αυτό μετατρέπει ένα γλωσσικό μοντέλο από μια δημιουργική μηχανή παραγωγής κειμένου σε ένα αξιόπιστο στοιχείο ενός αυτοματοποιημένου σωλήνα επεξεργασίας.
Το πρόβλημα που λύνει
Το αίτημα για JSON μέσω του prompt λειτουργεί τις περισσότερες φορές, γεγονός που καθιστά ακριβώς αυτή την προσέγγιση επικίνδυνη. Μία φορά στις εκατό, το μοντέλο προσθέτει μια εισαγωγική πρόταση στην αρχή της απάντησης, περικλείει τα πάντα σε ένα μπλοκ κώδικα Markdown ή μετονομάζει ένα πεδίο—και η συνάρτηση json.loads() σας ρίχνει μια εξαίρεση σε περιβάλλον παραγωγής, σε ένα αίτημα που δεν μπορείτε να αναπαράγετε.
from openai import OpenAI
client = OpenAI()
# Χωρίς δομή — το μοντέλο μπορεί να επιστρέψει οποιαδήποτε μορφή
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me info about Paris in JSON."
)
print(response.output_text)
# Απρόβλεπτο αποτέλεσμα:
# Μερικές φορές έγκυρο JSON, μερικές φορές κείμενο που περιέχει JSON,
# μερικές φορές μια απροσδόκητη μορφή...
Η παράμετρος text αλλάζει τη φύση της εγγύησης. Δηλώνετε μια μορφή json_schema μαζί με το αναμενόμενο σχήμα και η έξοδος συμμορφώνεται με αυτό: η αποσειριοποίηση γίνεται μια ασφαλής λειτουργία.
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'])}")
# Αποτέλεσμα ΕΓΓΥΗΜΕΝΑ έγκυρο JSON:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur
Pydantic αντί για χειροκίνητη συγγραφή JSON Schema
Η χειροκίνητη συγγραφή σχημάτων γίνεται γρήγορα κουραστική και επιρρεπής σε τυπογραφικά λάθη. Το Pydantic σάς επιτρέπει να τα περιγράφετε ως κλάσεις Python, να παράγετε το JSON Schema με τη μέθοδο model_json_schema() και στη συνέχεια να επικυρώνετε και να τυποποιείτε την απάντηση με τη μέθοδο model_validate_json(). Στο τέλος της αλυσίδας, λαμβάνετε ένα πλήρες αντικείμενο Python με αυτόματη συμπλήρωση από τον επεξεργαστή κώδικα, αντί για ένα ανώνυμο λεξικό.
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()
}
}
)
# Ανάλυση και επικύρωση με 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'}")
# Αποτέλεσμα:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes
Τίποτα δεν σας περιορίζει σε επίπεδες δομές. Συνθέτοντας κλάσεις, περιγράφετε ένθετα αντικείμενα και λίστες αντικειμένων, κάτι που θα χρειαστείτε μόλις δημιουργήσετε ένα ρεαλιστικό προφίλ πελάτη: μια εταιρεία περιέχει επαφές και κάθε επαφή έχει μια διεύθυνση.
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}")
Δύο συνηθισμένες περιπτώσεις χρήσης
Η πρώτη είναι η εξαγωγή: η μετατροπή γραπτού κειμένου σε μια usable εγγραφή. Μια ανακοίνωση συνεδρίου γραμμένη σε φυσική γλώσσα μετατρέπεται σε μια γραμμή βάσης δεδομένων με τίτλο, ημερομηνία, τοποθεσία και αριθμό συμμετεχόντων—χωρίς κανονικές εκφράσεις και χωρίς να «σπάει» κάθε φορά που αλλάζει η διατύπωση.
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)")
# Αποτέλεσμα: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)
Η δεύτερη είναι η ταξινόμηση. Δηλώνοντας μια απαρίθμηση (enumeration), περιορίζετε το μοντέλο σε ένα κλειστό λεξιλόγιο: δεν μπορεί να απαντήσει «μάλλον θετικό» ή «θετικό» όταν ο κώδικάς σας αναμένει positive. Αυτή είναι η διαφορά μεταξύ μιας τιμής που μπορείτε να χρησιμοποιήσετε απευθείας και μιας τιμής που πρέπει να κανονικοποιήσετε εκ των υστέρων.
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%})")
# Αποτέλεσμα: Sentiment: positive (95%)
Τι απαιτεί η αυστηρή λειτουργία (strict mode)
Η εγγύηση συνοδεύεται από μια αντάλλαγμα: όταν strict: True, το σχήμα πρέπει να τηρεί ένα συγκεκριμένο υποσύνολο του JSON Schema. Αυτοί οι περιορισμοί είναι η κύρια αιτία σφαλμάτων 400 για τους αρχάριους, οπότε είναι καλύτερο να τους γνωρίζετε πριν τους συναντήσετε:
- Όλες οι ιδιότητες πρέπει να αναφέρονται στο
required - Το
additionalPropertiesπρέπει να είναιFalse - Υποστηριζόμενοι τύποι:
string,number,integer,boolean,array,object,null - Όχι
oneOfήanyOfμε μικτούς τύπους - Χρησιμοποιήστε
Optional[str], το οποίο μεταφράζεται σε{"anyOf": [{"type": "string"}, {"type": "null"}]}
Ο κανόνας σχετικά με το required συχνά εκπλήσσει τους χρήστες: ένα προαιρετικό πεδίο δεν εκφράζεται αφαιρώντας το από τη λίστα, αλλά επιτρέποντας την τιμή null, ακριβώς όπως παράγει το Optional[str] στην πλευρά του Pydantic.
Βασικά σημεία
- Η Δομημένη Έξοδος εγγυάται ότι η απάντηση τηρεί το σχήμα JSON σας
- Χρησιμοποιήστε
text={"format": {"type": "json_schema", ...}}στο Responses API - Το Pydantic είναι το ιδανικό εργαλείο για τον ορισμό και την επικύρωση σχημάτων
- Ενεργοποιήστε το
strict: Trueγια εγγυημένη συμμόρφωση με το σχήμα - Ιδανικό για εξαγωγή δεδομένων, ταξινόμηση και δομημένη παραγωγή