Validacija s shemo JSON in Zod
Na tej strani
Lekcija posodobljena 3. novembra 2026 na podlagi dokumentacije OpenAI: parametra
temperatureintop_psta sprejeta le pri naporu razmišljanja (reasoning effort) vrednostinone, medtem ko modeli GPT-5.6 privzeto razmišljajo (medium). Klici, ki nastavljajo te parametre, morajo zato določitireasoning={"effort": "none"}(Responses API) alireasoning_effort="none"(Chat Completions). Viri: Uporaba GPT-6 · GPT-5.6 Terra.
Validacija s shemo JSON in Zod
Strukturirani izhod (Structured Output) zagotavlja strukturo odgovora, ne pa tudi semantične veljavnosti podatkov. Polje „email” lahko vsebuje niz, ki ni veljaven e-poštni naslov. Validacija na strani odjemalca z uporabo sheme JSON ali knjižnice Zod je bistven dopolnilni korak za robustno cevovodno obdelavo.
Zakaj validirati po prejemu
Ocenimo, kaj API zagotavlja, in razdelitev dela bo jasna. Strukturirani izhod OpenAI zagotavlja, da je JSON sintaktično veljaven, da so spoštovane deklarirane vrste – niz ostane niz, celo število ostane celo število – da so prisotna vsa zahtevana polja in da vrednosti, omejene z enum, spadajo na seznam. Na teh štirih točkah lahko svojo kodo pišeš z zaupanjem.
Vse drugo je tvoja odgovornost, kar zajema štiri družine težav. Omejitve oblike se izognejo strogi shemi: nič ne preprečuje modelu, da v polju email vrne jean.dupont(at)example.fr ali datum v obliki 15/03/2026, ko pričakuješ ISO. Meje prav tako niso preverjene, niti za dolžino niza niti za obseg števil: starost 350 bo minila brez težav. Skladnost med polji ostaja nedosegljiva – end_date, ki je zgodnejši od start_date, je popolnoma veljaven JSON. In poslovna veljavnost API-ja ne zanima: SIRET (francoska identifikacijska številka podjetja) mora imeti štirinajst števk, vendar je to znanje tvoje domene, ne dekodirnika.
Te štiri družine imajo eno zastrašujočo lastnost: ne povzročajo vidnih napak. Nepravilno oblikovan e-poštni naslov, shranjen v bazo podatkov, se ne bo pokazal, dokler e-poštna kampanja tedne kasneje ne bo zavrnjena. Zato velja pravilo: validiraj pred trajnim shranjevanjem, nikoli po njem.
Validacija v Pythonu z jsonschema
Praktična posledica je, da potrebuješ dve shemi za iste podatke. Prva gre v API, namerno vitka, omejena na tisto, kar strogi način sprejme. Druga ostane pri tebi in nosi fino nastavitvene omejitve – format, pattern, minimum, maximum. Ta navidezna podvojenost je ločevanje odgovornosti: ena okvirja generiranje, druga brani tvoje shrambe. V spodnjem primeru se v obeh pojavi le enum za vlogo, ker je to edina omejitev, ki jo lahko izrazita obe ravni.
import json
from jsonschema import validate, ValidationError
# Shema za OpenAI API (stroga, brez 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
}
# Razširjena shema za validacijo na strani odjemalca
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]:
"""Validira odgovor LLM glede na razširjeno shemo."""
try:
validate(instance=data, schema=validation_schema)
return True, "Valid"
except ValidationError as e:
return False, f"Error: {e.message}"
Validacija s Pydantic
Pydantic je v Pythonu pogosto priročnejši od jsonschema za validacijo, razlika pa je v tem, kaj dobiš na izhodu. jsonschema ti pove da ali ne in te pusti z slovarjem, s katerim upravljaš preko data["email"] brez pomoči urejevalnika. Pydantic vrne tipiziran objekt: samodejno dopolnjevanje deluje, tipkarska napaka v imenu atributa je zaznana ob zapisu, podatki pa nato krožijo brez pretvorbe.
Model ContactExtraction izraža meje neposredno v deklaracijah polj. field_validator na date_extraction pokriva primer, ki ga nobena anotacija vrste ne more zajeti: niz je res niz, vendar mora predstavljati pravi datum – 2026-02-31 zadošča vsakemu razumnemu pattern, vendar ne obstaja. Funkcija za ekstrakcijo prikazuje celoten verig, od vitke sheme, poslane API-ju, do validirane instanciacije.
from pydantic import BaseModel, Field, field_validator
from pydantic import EmailStr
from datetime import date
class ContactExtraction(BaseModel):
"""Shema validacije za ekstrakcijo kontaktov."""
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:
"""Ekstrahira kontakt in validira podatke."""
# Shema za API (brez fino nastavljenih omejitev)
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)
# Validacija s Pydantic s fino nastavljenimi omejitvami
return ContactExtraction(**data)
Validacija z Zod (TypeScript/Node.js)
Če je tvoje zaledje v TypeScriptu, je Zod referenčno orodje in prinaša prednost, ki je Pydanticu ni treba zagotavljati: z.infer izpelje vrsto TypeScript neposredno iz sheme validacije. Obliko opišeš enkrat, kompilator pa nato pozna strukturo Invoice, ne da bi moral vzdrževati vzporedni vmesnik, tako da ni tveganja za razhajanje.
Spodnja shema računa ilustrira razdelitev dela: na strani API-ja je siret le niz; na strani Zod mora imeti natanko štirinajst znakov in vsebovati le števke. Končni parse sproži izjemo, če se podatki ne ujemajo, in to je želeno vedenje – glasna napaka, ki prekine obdelavo dokumenta, je boljša od računa z izmišljenim SIRET-om, shranjenega v bazi podatkov med desetimi tisoč drugimi.
import { z } from "zod";
import OpenAI from "openai";
const client = new OpenAI();
// Shema Zod s fino nastavljenimi validacijami
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);
// Validacija Zod s fino nastavljenimi omejitvami
return InvoiceSchema.parse(data);
}
Vzorec: ponovni poskus s popravkom
Ko validacija ne uspe, pošlji napako nazaj modelu za popravek. Ta refleks spremeni naravo napake: datum v napačni obliki ni več izjema, ki brbota do uporabnika, temveč dodaten krog, ki traja nekaj sto milisekund in ga nihče ne opazi. Mehanizem je preprost – sporočilo o validaciji ponovno vbrizgamo v poziv za naslednji poskus, tako da model točno ve, kaj je šlo narobe, namesto da bi drugič ugibal na slepo.
Vendar ta udobje zahteva meje. Omeji število poskusov, sicer te bo nemogoča omejitev – na primer pattern, ki je prestrog za tuja števila – stala klicev v zanki. In spremljaj stopnjo ponovnih poskusov: če četrtina tvojih ekstrakcij gre skozi ponovni poskus, težava ni v modelu, temveč v začetnem pozivu ali shemi.
def extract_with_retry(prompt: str, schema: dict,
validator, max_retries: int = 3) -> dict:
"""Ekstrahira in validira z avtomatskim ponovnim poskusom."""
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}")
Preskusna plošča za vabila v koledar
Zgradi shemo Pydantic za ekstrakcijo dogodkov – naslov, datum, čas, lokacija, udeleženci – in jo priklopi za klicem Strukturiranega izhoda. Preizkusi na petih e-poštnih sporočilih z vabili, pri čemer poskrbi, da vključiš vsaj eno, kjer je čas zapisan z besedami („četrtek pozno dopoldne”), in eno, kjer je lokacija implicitna („kot običajno v sejni sobi”). To so primeri, ki porušijo validacijo, in v pravem nabiralniku prevladujejo.
Nato dodaj samodejni ponovni poskus in izmeri dve številki: stopnjo uspeha pri prvem poskusu in stopnjo po ponovnem poskusu. Druga ti pove, kaj ti prinese popravek, prva pa, ali bi moral predelati svoja navodila, namesto da bi računal na drugo priložnost.
Ključne ugotovitve
- Strukturirani izhod zagotavlja strukturo, ne pa semantične veljavnosti
- Uporabi dve shemi: eno za API (strogo), eno za validacijo na strani odjemalca
- Pydantic (Python) in Zod (TypeScript) sta referenčni orodji
- Vzorec ponovnega poskusa z povratnimi informacijami popravi večino napak pri validaciji
- Pred trajnim shranjevanjem podatkov vedno validiraj na strani odjemalca