Validācija ar JSON Schema un Zod
Šajā lapā
Nodarbība atjaunināta 2026. gada 3. novembrī, pamatojoties uz OpenAI dokumentāciju: parametri
temperatureuntop_ptiek pieņemti tikai tad, ja spriešanas intensitāte (reasoning effort) ir iestatīta uznone, savukārt GPT-5.6 modeļi pēc noklusējuma veic spriešanu (medium). Tādēļ izsaukumos, kuros ir norādīti šie parametri, ir jāprecizēreasoning={"effort": "none"}(Responses API) vaireasoning_effort="none"(Chat Completions). Avoti: Using GPT-6 · GPT-5.6 Terra.
Validācija ar JSON Schema un Zod
Strukturētā izvade (Structured Output) garantē atbildes struktūru, bet ne datu semantisko pareizību. Lauks „e-pasts” var saturēt virkni, kas nav derīga e-pasta adrese. Klienta puses validācija, izmantojot JSON Schema vai Zod, ir būtisks papildinājums, lai nodrošinātu stabilu darbplūsmu.
Kāpēc validēt pēc saņemšanas
Izvērtēsim, ko tieši garantē API, un darba dalījums kļūs skaidrs. OpenAI strukturētā izvade nodrošina, ka JSON ir sintaktiski korekts, ka deklarētie tipi tiek ievēroti (virkne paliek virkne, vesels skaitlis paliek vesels skaitlis), ka visi obligātie lauki ir klāt un ka vērtības, kuras ierobežo enum, pieder noteiktajam sarakstam. Šajos četros punktos vari rakstīt savu kodu ar pārliecību.
Pārējais ir tava ziņā, aptverot četras problēmu grupas. Formāta ierobežojumi izvairās no stingrās shēmas: nekas neliedz modelim atgriezt jean.dupont(at)example.fr laukā email vai datumu formātā 15/03/2026, kamēr tu sagaidi ISO formātu. Arī robežas netiek pārbaudītas – ne virknes garumam, ne skaitļu diapazonam: vecums 350 tiks pieņemts bez mirkšķināšanas. Lauku savstarpējā saskaņotība arī paliek ārpus sasniegumiem – end_date, kas ir agrāks par start_date, ir pilnīgi derīgs JSON. Un biznesa loģikas pareizībai nav iemesla uztraukt API: SIRET (franču uzņēmuma ID) ir jābūt četrpadsmit cipariem, taču tās ir tavas domēna zināšanas, nevis dekodētāja pienākums.
Šīm četrām grupām ir viena biedējoša īpašība: tās nerada redzamas kļūdas. Datubāzē saglabāts nekorekts e-pasts neizpaudīsies, līdz e-pasta kampaņa nedēļas vēlāk atsities pret sienu. Tādēļ likums ir skaidrs: validē pirms saglabāšanas, nevis pēc tās.
Python validācija ar jsonschema
Praktiskās sekas ir tādas, ka vieniem un tiem pašiem datiem ir nepieciešamas divas shēmas. Pirmā tiek nosūtīta API – tā ir apzināti vienkārša, aprobežojoties tikai ar to, ko pieņem stingrais režīms. Otrā paliek pie tevis un nes smalkākus ierobežojumus – format, pattern, minimum, maximum. Šī šķietamā dublēšanās ir atbildību nodalīšana: viena ierāmē ģenerēšanu, otra aizsargā tavu krātuvi. Tālāk redzamajā piemērā abās shēmās parādās tikai lomas enum, jo tas ir vienīgais ierobežojums, ko var izteikt abos līmeņos.
import json
from jsonschema import validate, ValidationError
# Shēma OpenAI API (stingra, bez 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
}
# Paplašināta shēma klienta puses validācijai
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]:
"""Validē LLM atbildi pret paplašināto shēmu."""
try:
validate(instance=data, schema=validation_schema)
return True, "Valid"
except ValidationError as e:
return False, f"Error: {e.message}"
Validācija ar Pydantic
Python valodā Pydantic bieži vien ir ērtāks rīks validācijai nekā jsonschema, un atšķirība slēpjas tajā, ko tu iegūsti izvades brīdī. jsonschema pasaka tikai „jā” vai „nē” un atstāj tevi ar vārdnīcu, ar kuru strādā, rakstot `data[“email”]”, bez redaktora palīdzības. Pydantic atgriež tipizētu objektu: automātiskā pabeigšana strādā, kļūda atribūta nosaukumā tiek pamanīta jau rakstīšanas brīdī, un dati tālāk apritē pārvietojas bez konvertēšanas.
Modelis ContactExtraction izsaka robežas tieši lauku deklarācijās. field_validator laukam date_extraction aptver gadījumu, ko neviens tipa anotācija nevar uztvert: virkne patiešām ir virkne, taču tai ir jāapzīmē reāls datums – 2026-02-31 apmierina jebkuru saprātīgu pattern, taču šāds datums neeksistē. Ekstrakcijas funkcija parāda visu ķēdi, sākot no vienkāršās shēmas, kas nosūtīta API, līdz validētai instancēšanai.
from pydantic import BaseModel, Field, field_validator
from pydantic import EmailStr
from datetime import date
class ContactExtraction(BaseModel):
"""Validācijas shēma kontaktu ekstrakcijai."""
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:
"""Ekstrahē kontaktu un validē datus."""
# Shēma API (bez smalkiem ierobežojumiem)
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 validācija ar smalkiem ierobežojumiem
return ContactExtraction(**data)
Validācija ar Zod (TypeScript/Node.js)
Ja tava backend vide ir TypeScript, Zod ir standarta rīks, un tas nodrošina priekšrocību, ko Pydantic nav jānodrošina: z.infer atvasina TypeScript tipu tieši no validācijas shēmas. Tu apraksti formu vienreiz, un kompilators pēc tam zina Invoice struktūru, tev nevajag uzturēt paralēlu interfeisu, tāpēc nav riska, ka tie novirzīsies viens no otra.
Tālāk redzamā rēķina shēma ilustrē darba dalījumu: API pusē siret ir tikai virkne; Zod pusē tai ir jābūt tieši četrpadsmit zīmēm garai un jāsatur tikai cipari. Galīgais parse izraisa izņēmumu, ja dati neatbilst, un tāda ir vēlamā uzvedība – skaļa kļūda, kas pārtrauc dokumentu apstrādi, ir labāka par fantāzijas SIRET rēķinu, kas saglabāts datubāzē starp desmit tūkstošiem citu.
import { z } from "zod";
import OpenAI from "openai";
const client = new OpenAI();
// Zod shēma ar smalkām validācijām
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 validācija ar smalkiem ierobežojumiem
return InvoiceSchema.parse(data);
}
Paraugs: atkārtošana ar labojumu
Kad validācija neizdodas, nosūti kļūdu atpakaļ modelim labošanai. Šī refleksija maina kļūmes dabu: nepareizā formātā norādīts datums vairs nav izņēmums, kas uzpeld lietotājam, bet gan papildu aprites cikls dažus simtus milisekunžu garumā, ko neviens nepamanīs. Mehānisms ir vienkāršs – mēs atkārtoti ievadām validācijas ziņojumu nākamā mēģinājuma promptā, lai modelis precīzi zinātu, kas nogāja greizi, nevis minētu akli otro reizi.
Tomēr šim komfortam ir nepieciešamas robežas. Ierobežo mēģinājumu skaitu, pretējā gadījumā neiespējams ierobežojums – piemēram, pattern, kas ir pārāk stingrs ārvalstu numuriem – tev izmaksās bezgalīgu izsaukumu ciklu. Un uzraugi atkārtojumu biežumu: ja ceturtdaļa tavu ekstrakciju iziet cauri atkārtojumam, problēma slēpjas sākotnējā promptā vai shēmā, nevis modelī.
def extract_with_retry(prompt: str, schema: dict,
validator, max_retries: int = 3) -> dict:
"""Ekstrahē un validē ar automātisku atkārtošanu."""
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}")
Kalendāra ielūgumu testa stends
Izveido Pydantic shēmu pasākumu ekstrakcijai – nosaukums, datums, laiks, vieta, dalībnieki – un pievieno to aiz strukturētās izvades izsaukuma. Testē uz pieciem e-pastiem, kas satur ielūgumus, noteikti iekļaujot vismaz vienu, kurā laiks ir uzrakstīts vārdos („ceturtdienas vēlā rīta pusē”), un vienu, kurā vieta ir implicīta („kā parasti sanāksmju zālē”). Tie ir gadījumi, kas lauž validāciju, un reālā pastkastītē tie dominē.
Pēc tam pievieno automātisku atkārtošanu un izmēri divus rādītājus: veiksmes rādītāju pirmajā mēģinājumā un rādītāju pēc atkārtojumiem. Otrais pastāsta, ko dod labošana, bet pirmais – vai tev vajadzētu pārstrādāt savas instrukcijas, nevis paļauties uz otro iespēju.
Galvenās atziņas
- Strukturētā izvade garantē struktūru, nevis semantisko pareizību
- Izmanto divas shēmas: vienu API (stingra), otru klientu validācijai
- Pydantic (Python) un Zod (TypeScript) ir standarta rīki
- Atkārtošanas ar atgriezenisko saiti paraugs labo lielāko daļu validācijas kļūdu
- Vienmēr validē klientu pusē pirms datu saglabāšanas