Validare cu JSON Schema și Zod
Pe această pagină
Lecție actualizată la 3 noiembrie 2026 pe baza documentației OpenAI: parametrii
temperatureșitop_psunt acceptați doar cu un efort de raționament denone, în timp ce modelele GPT-5.6 raționează implicit (medium). Apelurile care setează acești parametri trebuie, prin urmare, să specificereasoning={"effort": "none"}(API-ul Responses) saureasoning_effort="none"(Chat Completions). Surse: Utilizarea GPT-6 · GPT-5.6 Terra.
Validare cu JSON Schema și Zod
Ieșirea structurată (Structured Output) garantează structura răspunsului, dar nu și validitatea semantică a datelor. Un câmp „email“ poate conține un șir de caractere care nu este o adresă de e-mail validă. Validarea lato-client folosind JSON Schema sau Zod este complementul esențial pentru un flux de lucru robust.
De ce să validați după recepție
Evaluați ceea ce garantează API-ul, iar diviziunea muncii devine clară. Funcționalitatea Structured Output de la OpenAI asigură că JSON-ul este sintactic valid, că tipurile declarate sunt respectate—un șir rămâne un șir, un întreg rămâne un întreg—că toate câmpurile obligatorii sunt prezente și că valorile constrânse de un enum aparțin listei. Pe aceste patru puncte, puteți scrie codul cu încredere.
Tot restul vă revine dumneavoastră, acoperind patru familii de probleme. Constrângerile de format scapă schemei stricte: nimic nu împiedică modelul să returneze jean.dupont(at)example.fr într-un câmp email, sau o dată în formatul 15/03/2026 când vă așteptați la ISO. Limitele nu sunt verificate nici ele, nici pentru lungimea șirului, nici pentru intervalul numeric: o vârstă de 350 de ani va trece neobservată. Consistența între câmpuri rămâne inaccesibilă—o end_date anterioară lui start_date este un JSON perfect valid. Iar validitatea comercială nu are niciun motiv să preocupe API-ul: un SIRET (identificator de afacere francez) trebuie să aibă paisprezece cifre, dar aceasta este cunoașterea domeniului dumneavoastră, nu a decodorului.
Aceste patru familii au o trăsătură comună îngrijorătoare: nu provoacă erori vizibile. Un e-mail malformat salvat în baza de date nu se va manifesta decât atunci când campania de e-mailuri va eșua săptămâni mai târziu. De aici regula: validați înainte de persistență, niciodată după.
Validare Python cu jsonschema
Consecința practică este că aveți nevoie de două scheme pentru aceleași date. Prima merge către API, intenționat simplă, limitată la ceea ce acceptă modul strict. A doua rămâne la dumneavoastră și poartă constrângerile fine—format, pattern, minimum, maximum. Această aparentă duplicare este o separare a responsabilităților: una încadrează generarea, cealaltă apără stocarea. În exemplul de mai jos, doar enum-ul pentru rol apare în ambele, deoarece este singura constrângere pe care ambele niveluri o pot exprima.
import json
from jsonschema import validate, ValidationError
# Schema pentru API-ul OpenAI (strict, fără 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
}
# Schema extinsă pentru validarea lato-client
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]:
"""Validează răspunsul LLM față de schema extinsă."""
try:
validate(instance=data, schema=validation_schema)
return True, "Valid"
except ValidationError as e:
return False, f"Eroare: {e.message}"
Validare cu Pydantic
Pydantic este adesea mai convenabil decât jsonschema pentru validarea în Python, iar diferența constă în ceea ce obțineți la ieșire. jsonschema vă spune da sau nu și vă lasă cu un dicționar, manipulat prin data["email"] fără asistență din partea editorului. Pydantic returnează un obiect tipizat: autocompletarea funcționează, o greșeală de tastare în numele unui atribut este prinsă la scriere, iar datele circulă ulterior fără conversie.
Modelul ContactExtraction exprimă limitele direct în declarațiile câmpurilor. field_validator pentru date_extraction acoperă cazul pe care nicio adnotare de tip nu îl poate prinde: șirul este într-adevăr un șir, dar trebuie să reprezinte o dată reală—2026-02-31 satisface orice pattern rezonabil, totuși nu există. Funcția de extragere arată lanțul complet, de la schema simplă trimisă API-ului până la instanțierea validată.
from pydantic import BaseModel, Field, field_validator
from pydantic import EmailStr
from datetime import date
class ContactExtraction(BaseModel):
"""Schema de validare pentru extragerea contactelor."""
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"Dată invalidă: {v}")
def extract_and_validate(text: str) -> ContactExtraction:
"""Extrage un contact și validează datele."""
# Schema pentru API (fără constrângeri fine)
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="Extrage informațiile de contact. "
"Formatul datei: YYYY-MM-DD.",
input=text,
text={
"format": {
"type": "json_schema",
"name": "contact",
"schema": api_schema,
"strict": True
}
}
)
data = json.loads(response.output_text)
# Validare Pydantic cu constrângeri fine
return ContactExtraction(**data)
Validare cu Zod (TypeScript/Node.js)
Dacă backend-ul dumneavoastră este în TypeScript, Zod este instrumentul de referință, iar acesta aduce un avantaj pe care Pydantic nu trebuie să îl ofere: z.infer derivă tipul TypeScript direct din schema de validare. Descrieți forma o singură dată, iar compilatorul cunoaște apoi structura lui Invoice fără ca dumneavoastră să mențineți o interfață paralelă, astfel încât nu există risc de divergență.
Schema de factură de mai jos ilustrează diviziunea muncii: din partea API-ului, siret este doar un șir; din partea Zod, trebuie să aibă exact paisprezece caractere și să conțină doar cifre. Metoda parse finală aruncă o excepție dacă datele nu se potrivesc, iar acesta este comportamentul dorit—o eroare sonoră care întrerupe procesarea documentului este mai bună decât o factură cu un SIRET fantezist stocată în baza de date printre alte zece mii.
import { z } from "zod";
import OpenAI from "openai";
const client = new OpenAI();
// Schema Zod cu validări fine
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: "Extrage datele facturii.",
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);
// Validare Zod cu constrângeri fine
return InvoiceSchema.parse(data);
}
Model: reîncercare cu corecție
Când validarea eșuează, trimiteți eroarea înapoi modelului pentru corecție. Acest reflex schimbă natura eșecului: o dată în format greșit nu mai este o excepție care urcă până la utilizator, ci o rundă suplimentară de câteva sute de milisecunde pe care nimeni nu o observă. Mecanismul este simplu—reinjectăm mesajul de validare în promptul următoarei încercări, astfel încât modelul să știe exact ce nu a funcționat, în loc să ghicească orb a doua oară.
Această comoditate necesită totuși limite. Limitați numărul de încercări, sau o constrângere imposibilă—un pattern prea strict pentru numerele străine, de exemplu—vă va costa apeluri într-o buclă. Și monitorizați rata de reîncercare: dacă un sfert din extragerile dumneavoastră trec printr-o reîncercare, problema stă în promptul inițial sau în schemă, nu în model.
def extract_with_retry(prompt: str, schema: dict,
validator, max_retries: int = 3) -> dict:
"""Extrage și validează cu reîncercare automată."""
last_error = None
for attempt in range(max_retries):
input_text = prompt
if last_error:
input_text += (f"\n\nAVERTISMENT: Răspunsul anterior a avut "
f"această eroare de validare: {last_error}\n"
f"Corectați și încercați din nou.")
response = client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature necesită 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"Eșec după {max_retries} încercări: {last_error}")
Un banc de test pentru invitațiile la calendar
Construiți o schemă Pydantic pentru a extrage evenimente—titlu, dată, oră, locație, participanți—apoi conectați-o în spatele unui apel Structured Output. Testați pe cinci e-mailuri care conțin invitații, asigurându-vă că includeți cel puțin unul unde ora este scrisă textual („joi spre prânz“) și unul unde locația este implicită („ca de obicei în sala de ședințe“). Acestea sunt cazurile care sparg validarea și domină într-o cutie poștală reală.
Apoi adăugați reîncercarea automată și măsurați două cifre: rata de succes din prima încercare și rata după reîncercare. A doua vă spune ce câștigă corecția, prima vă indică dacă ar trebui să refaceți instrucțiunile mai degrabă decât să contați pe o a doua șansă.
Puncte cheie
- Structured Output garantează structura, nu validitatea semantică
- Folosiți două scheme: una pentru API (strictă), una pentru validarea lato-client
- Pydantic (Python) și Zod (TypeScript) sunt instrumentele de referință
- Modelul de reîncercare cu feedback corectează majoritatea erorilor de validare
- Validați întotdeauna lato-client înainte de a persista datele