Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Επικύρωση με JSON Schema και Zod

Μάθημα 11 / 16 Ενημερώθηκε 3 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Επικύρωση με JSON Schema και Zod
  2. Γιατί να επικυρώνετε μετά τη λήψη
  3. Επικύρωση Python με jsonschema
  4. Επικύρωση με Pydantic
  5. Επικύρωση με Zod (TypeScript/Node.js)
  6. Πρότυπο: Επαναληπτική προσπάθεια με διόρθωση
  7. Ένας πάγκος δοκιμών για προσκλήσεις ημερολογίου
  8. Βασικά σημεία

Μάθημα ενημερώθηκε στις 3 Νοεμβρίου 2026 βάσει της τεκμηρίωσης της OpenAI: οι παράμετροι temperature και top_p γίνονται δεκτές μόνο με προσπάθεια συλλογισμού (reasoning effort) ίση με none, ενώ τα μοντέλα GPT-5.6 κάνουν συλλογισμό από προεπιλογή (medium). Επομένως, οι κλήσεις που ορίζουν αυτές τις παραμέτρους πρέπει να καθορίζουν reasoning={"effort": "none"} (Responses API) ή reasoning_effort="none" (Chat Completions). Πηγές: Χρήση GPT-6 · GPT-5.6 Terra.

Επικύρωση με JSON Schema και Zod

Η Δομημένη Έξοδος (Structured Output) εγγυάται τη δομή της απάντησης, αλλά όχι τη σημασιολογική εγκυρότητα των δεδομένων. Ένα πεδίο «email» μπορεί να περιέχει μια συμβολοσειρά που δεν αποτελεί έγκυρη διεύθυνση email. Η επικύρωση στην πλευρά του πελάτη (client-side) με χρήση JSON Schema ή Zod αποτελεί το απαραίτητο συμπλήρωμα για μια αξιόπιστη ροή εργασίας.

Γιατί να επικυρώνετε μετά τη λήψη

Αποτιμήστε τι εγγυάται το API και η κατανομή των αρμοδιοτήτων θα γίνει σαφής. Η Δομημένη Έξοδος της OpenAI διασφαλίζει ότι το JSON είναι συντακτικά έγκυρο, ότι οι δηλωμένοι τύποι τηρούνται—μια συμβολοσειρά παραμένει συμβολοσειρά, ένας ακέραιος παραμένει ακέραιος—ότι όλα τα απαιτούμενα πεδία είναι παρόντα και ότι οι τιμές που περιορίζονται από ένα enum ανήκουν στη λίστα. Σε αυτά τα τέσσερα σημεία, μπορείτε να γράφετε τον κώδικά σας με σιγουριά.

Όλα τα υπόλοιπα εξαρτώνται από εσάς, καλύπτοντας τέσσερις κατηγορίες προβλημάτων. Οι περιορισμοί μορφής ξεφεύγουν από το αυστηρό σχήμα: τίποτα δεν εμποδίζει το μοντέλο να επιστρέψει jean.dupont(at)example.fr σε ένα πεδίο email, ή μια ημερομηνία σε μορφή 15/03/2026 όταν εσείς αναμένετε ISO. Τα όρια δεν ελέγχονται ούτε για το μήκος συμβολοσειράς ούτε για το εύρος αριθμών: μια ηλικία 350 ετών θα περάσει χωρίς δεύτερη σκέψη. Η συνεκτικότητα μεταξύ πεδίων παραμένει εκτός εμβέλειας—μια end_date προγενέστερη της start_date αποτελεί απολύτως έγκυρο JSON. Και η επιχειρηματική εγκυρότητα δεν έχει λόγο να απασχολεί το API: ένα SIRET (γαλλικός αριθμός επιχείρησης) πρέπει να αποτελείται από δεκατέσσερα ψηφία, αλλά αυτή είναι γνώση του τομέα σας, όχι του αποκωδικοποιητή.

Αυτές οι τέσσερις κατηγορίες μοιράζονται ένα ανησυχητικό χαρακτηριστικό: δεν προκαλούν ορατά σφάλματα. Ένα κακοδιατυπωμένο email αποθηκευμένο στη βάση δεδομένων δεν θα εκδηλωθεί μέχρι να αποτύχει η καμπάνια email εβδομάδες αργότερα. Εξ ου και ο κανόνας: επικυρώστε πριν την αποθήκευση, ποτέ μετά.

Επικύρωση Python με jsonschema

Η πρακτική συνέπεια είναι ότι χρειάζεστε δύο σχήματα για τα ίδια δεδομένα. Το πρώτο πηγαίνει στο API, σκόπιμα λιτό, περιορισμένο σε όσα δέχεται η αυστηρή λειτουργία (strict mode). Το δεύτερο παραμένει σε εσάς και φέρει τους λεπτομερείς περιορισμούς—format, pattern, minimum, maximum. Αυτή η φαινομενική διπλοτυπία αποτελεί διαχωρισμό ευθυνών: το ένα πλαισιώνει τη δημιουργία, το άλλο υπερασπίζεται την αποθήκευσή σας. Στο παρακάτω παράδειγμα, μόνο το enum του ρόλου εμφανίζεται και στα δύο, επειδή είναι ο μόνος περιορισμός που μπορούν να εκφράσουν και τα δύο επίπεδα.

import json
from jsonschema import validate, ValidationError

# Schema for OpenAI API (strict, no format/pattern)
api_schema = {
    "type": "object",
    "properties": {
        "email": {"type": "string"},
        "age": {"type": "integer"},
        "role": {"type": "string", "enum": ["admin", "user", "viewer"]}
    },
    "required": ["email", "age", "role"],
    "additionalProperties": False
}

# Extended schema for client-side validation
validation_schema = {
    "type": "object",
    "properties": {
        "email": {
            "type": "string",
            "format": "email",
            "pattern": r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z]{2,}$"
        },
        "age": {
            "type": "integer",
            "minimum": 0,
            "maximum": 150
        },
        "role": {"type": "string", "enum": ["admin", "user", "viewer"]}
    },
    "required": ["email", "age", "role"]
}

def validate_response(data: dict) -> tuple[bool, str]:
    """Validates the LLM response against the extended schema."""
    try:
        validate(instance=data, schema=validation_schema)
        return True, "Valid"
    except ValidationError as e:
        return False, f"Error: {e.message}"

Επικύρωση με Pydantic

Το Pydantic είναι συχνά πιο βολικό από το jsonschema για επικύρωση σε Python, και η διαφορά έγκειται σε αυτό που λαμβάνετε ως έξοδο. Το jsonschema σας λέει ναι ή όχι και σας αφήνει με ένα λεξικό, το οποίο χειρίζεστε μέσω data["email"] χωρίς βοήθεια από τον επεξεργαστή κώδικα. Το Pydantic επιστρέφει ένα αντικείμενο με τύπους: η αυτόματη συμπλήρωση λειτουργεί, ένα τυπογραφικό λάθος στο όνομα ενός χαρακτηριστικού εντοπίζεται κατά τη συγγραφή και τα δεδομένα κυκλοφορούν στη συνέχεια χωρίς μετατροπή.

Το μοντέλο ContactExtraction εκφράζει τα όρια απευθείας στις δηλώσεις των πεδίων. Το field_validator στο date_extraction καλύπτει την περίπτωση που κανένας τύπος annotation δεν μπορεί να εντοπίσει: η συμβολοσειρά είναι όντως συμβολοσειρά, αλλά πρέπει να αναπαριστά μια πραγματική ημερομηνία—το 2026-02-31 ικανοποιεί οποιοδήποτε λογικό pattern ωστόσο δεν υπάρχει. Η συνάρτηση εξαγωγής δείχνει την πλήρη αλυσίδα, από το λιτό σχήμα που στέλνεται στο API μέχρι την επικυρωμένη δημιουργία στιγμιότυπου.

from pydantic import BaseModel, Field, field_validator
from pydantic import EmailStr
from datetime import date

class ContactExtraction(BaseModel):
    """Validation schema for contact extraction."""
    last_name: str = Field(min_length=2, max_length=100)
    first_name: str = Field(min_length=2, max_length=100)
    email: EmailStr
    phone: str = Field(pattern=r"^\+?[0-9\s\-\.]{10,15}$")
    company: str
    title: str
    extraction_date: str

    @field_validator("extraction_date")
    @classmethod
    def validate_date(cls, v):
        try:
            date.fromisoformat(v)
            return v
        except ValueError:
            raise ValueError(f"Invalid date: {v}")

def extract_and_validate(text: str) -> ContactExtraction:
    """Extracts a contact and validates the data."""
    # Schema for API (without fine-grained constraints)
    api_schema = {
        "type": "object",
        "properties": {
            "last_name": {"type": "string"},
            "first_name": {"type": "string"},
            "email": {"type": "string"},
            "phone": {"type": "string"},
            "company": {"type": "string"},
            "title": {"type": "string"},
            "extraction_date": {"type": "string"}
        },
        "required": ["last_name", "first_name", "email", "phone",
                      "company", "title", "extraction_date"],
        "additionalProperties": False
    }

    response = client.responses.create(
        model="gpt-5.6-terra",
        instructions="Extract contact information. "
                     "Date format: YYYY-MM-DD.",
        input=text,
        text={
            "format": {
                "type": "json_schema",
                "name": "contact",
                "schema": api_schema,
                "strict": True
            }
        }
    )

    data = json.loads(response.output_text)
    # Pydantic validation with fine-grained constraints
    return ContactExtraction(**data)

Επικύρωση με Zod (TypeScript/Node.js)

Εάν το backend σας είναι σε TypeScript, το Zod είναι το εργαλείο αναφοράς και φέρνει ένα πλεονέκτημα που το Pydantic δεν χρειάζεται να παρέχει: το z.infer παράγει τον τύπο TypeScript απευθείας από το σχήμα επικύρωσης. Περιγράφετε τη δομή μία φορά και ο μεταγλωττιστής γνωρίζει thereafter τη δομή του Invoice χωρίς εσείς να συντηρείτε μια παράλληλη διεπαφή, οπότε δεν υπάρχει κίνδυνος απόκλισης.

Το παρακάτω σχήμα τιμολογίου illustrates τη διαίρεση των αρμοδιοτήτων: στην πλευρά του API, το siret είναι απλώς μια συμβολοσειρά· στην πλευρά του Zod, πρέπει να έχει ακριβώς δεκατέσσερις χαρακτήρες και να περιέχει μόνο ψηφία. Το τελικό parse προκαλεί εξαίρεση εάν τα δεδομένα δεν ταιριάζουν, και αυτή είναι η επιθυμητή συμπεριφορά—ένα ηχηρό σφάλμα που διακόπτει την επεξεργασία του εγγράφου είναι προτιμότερο από ένα φανταστικό τιμολόγιο SIRET αποθηκευμένο στη βάση δεδομένων ανάμεσα σε δέκα χιλιάδες άλλα.

import { z } from "zod";
import OpenAI from "openai";

const client = new OpenAI();

// Zod schema with fine-grained validations
const InvoiceSchema = z.object({
  number: z.string().regex(/^[A-Z]{2}-\d{4}-\d{4}$/),
  date: z.string().date(),
  amount_excl_tax: z.number().positive(),
  vat_rate: z.number().min(0).max(100),
  amount_incl_tax: z.number().positive(),
  supplier: z.object({
    name: z.string().min(2),
    siret: z.string().length(14).regex(/^\d+$/),
  }),
});

type Invoice = z.infer<typeof InvoiceSchema>;

async function extractInvoice(text: string): Promise<Invoice> {
  const response = await client.responses.create({
    model: "gpt-5.6-terra",
    instructions: "Extract invoice data.",
    input: text,
    text: {
      format: {
        type: "json_schema",
        name: "invoice",
        schema: {
          type: "object",
          properties: {
            number: { type: "string" },
            date: { type: "string" },
            amount_excl_tax: { type: "number" },
            vat_rate: { type: "number" },
            amount_incl_tax: { type: "number" },
            supplier: {
              type: "object",
              properties: {
                name: { type: "string" },
                siret: { type: "string" },
              },
              required: ["name", "siret"],
              additionalProperties: false,
            },
          },
          required: ["number", "date", "amount_excl_tax",
                     "vat_rate", "amount_incl_tax", "supplier"],
          additionalProperties: false,
        },
        strict: true,
      },
    },
  });

  const data = JSON.parse(response.output_text);

  // Zod validation with fine-grained constraints
  return InvoiceSchema.parse(data);
}

Πρότυπο: Επαναληπτική προσπάθεια με διόρθωση

Όταν η επικύρωση αποτύχει, στείλτε το σφάλμα πίσω στο μοντέλο για διόρθωση. Αυτός ο αντανακλασμός αλλάζει τη φύση της αποτυχίας: μια ημερομηνία σε λάθος μορφή δεν αποτελεί πλέον εξαίρεση που αναδύεται στον χρήστη, αλλά έναν επιπλέον γύρο επικοινωνίας μερικών εκατοντάδων χιλιοστών του δευτερολέπτου που κανείς δεν αντιλαμβάνεται. Ο μηχανισμός είναι απλός—επανεισάγουμε το μήνυμα επικύρωσης στο prompt της επόμενης προσπάθειας, ώστε το μοντέλο να γνωρίζει ακριβώς τι πήγε στραβά αντί να μαντεύει τυφλά για δεύτερη φορά.

Αυτή η άνεση απαιτεί ωστόσο όρια. Θέστε ένα όριο στον αριθμό των προσπαθειών, διαφορετικά ένας αδύνατος περιορισμός—για παράδειγμα, ένα pattern πολύ αυστηρό για ξένους αριθμούς—θα σας κοστίσει κλήσεις σε βρόχο. Και παρακολουθείτε τον ρυθμό επανάληψης: εάν το ένα τέταρτο των εξαγωγών σας περνά από επανάληψη, το πρόβλημα βρίσκεται στο αρχικό prompt ή στο σχήμα, όχι στο μοντέλο.

def extract_with_retry(prompt: str, schema: dict,
                       validator, max_retries: int = 3) -> dict:
    """Extracts and validates with automatic retry."""
    last_error = None

    for attempt in range(max_retries):
        input_text = prompt
        if last_error:
            input_text += (f"\n\nWARNING: Your previous response had "
                          f"this validation error: {last_error}\n"
                          f"Correct and try again.")

        response = client.responses.create(
            model="gpt-5.6-terra",
            reasoning={"effort": "none"},  # temperature requires effort none
            input=input_text,
            text={"format": {"type": "json_schema",
                             "name": "data",
                             "schema": schema,
                             "strict": True}},
            temperature=0.1
        )

        data = json.loads(response.output_text)
        is_valid, error = validator(data)

        if is_valid:
            return data
        last_error = error

    raise ValueError(f"Failed after {max_retries} attempts: {last_error}")

Ένας πάγκος δοκιμών για προσκλήσεις ημερολογίου

Δημιουργήστε ένα σχήμα Pydantic για την εξαγωγή γεγονότων—τίτλος, ημερομηνία, ώρα, τοποθεσία, συμμετέχοντες—και συνδέστε το πίσω από μια κλήση Δομημένης Εξόδου. Δοκιμάστε σε πέντε emails που περιέχουν προσκλήσεις, φροντίζοντας να συμπεριλάβετε τουλάχιστον ένα όπου η ώρα είναι γραμμένη λεκτικά («Πέμπτη αργά το πρωί») και ένα όπου η τοποθεσία είναι υπονοούμενη («ως συνήθως στην αίθουσα συνεδριάσεων»). Αυτές είναι οι περιπτώσεις που «σπάνε» την επικύρωση και κυριαρχούν σε ένα πραγματικό inbox.

Στη συνέχεια, προσθέστε αυτόματη επανάληψη και μετρήστε δύο μεγέθη: τον ρυθμό επιτυχίας στην πρώτη προσπάθεια και τον ρυθμό μετά την επανάληψη. Το δεύτερο σας λέει τι κερδίζετε με τη διόρθωση, το πρώτο εάν θα πρέπει να αναθεωρήσετε τις οδηγίες σας αντί να βασίζεστε σε μια δεύτερη ευκαιρία.

Βασικά σημεία

  • Η Δομημένη Έξοδος εγγυάται τη δομή, όχι τη σημασιολογική εγκυρότητα
  • Χρησιμοποιήστε δύο σχήματα: ένα για το API (αυστηρό), ένα για επικύρωση στον πελάτη
  • Το Pydantic (Python) και το Zod (TypeScript) είναι τα εργαλεία αναφοράς
  • Το πρότυπο επανάληψης με ανατροφοδότηση διορθώνει τα περισσότερα σφάλματα επικύρωσης
  • Επικυρώνετε πάντα στην πλευρά του πελάτη πριν αποθηκεύσετε τα δεδομένα