Valideerimine JSON Schema ja Zodiga
Sellel lehel
Tund uuendatud 3. novembril 2026 OpenAI dokumentatsiooni põhjal: parameetreid
temperaturejatop_paktsepteeritakse ainult siis, kui arutluse jõupingutus (reasoning effort) onnone, samas kui GPT-5.6 mudelid kasutavad vaikimisi arutlust (medium). Seetõttu peavad need parameetrid määravad päringud sisaldamareasoning={"effort": "none"}(Responses API) võireasoning_effort="none"(Chat Completions). Allikad: GPT-6 kasutamine · GPT-5.6 Terra.
Valideerimine JSON Schema ja Zodiga
Struktureeritud väljund (Structured Output) garanteerib vastuse struktuuri, kuid mitte andmete semantilist kehtivust. Väli „email“ võib sisaldada stringi, mis ei ole tegelik kehtiv e-posti aadress. Kliendipoolne valideerimine, kasutades JSON Schema’t või Zodi, on töökindla torustiku hädavajalik täiendus.
Miks valideerida pärast vastuse saamist
Vaata üle, mida API garanteerib, ja tööjaotus selgub kohe. OpenAI Struktureeritud Väljund tagab, et JSON on süntaktiliselt korrektne, et deklareeritud tüüpe austatakse – string jääb stringiks, täisarv jääb täisarvuks – et kõik nõutud väljad on olemas ja et väärtused, mida piirab enum, kuuluvad loetellu. Nende nelja punkti osas saad oma koodi kirjutada kindlustundega.
Kõik muu on sinu teha, hõlmates nelja probleemi kategooriat. Vormingupiirangud jäävad rangest skeemist välja: miski ei takista mudelit tagastamast jean.dupont(at)example.fr väljal email või kuupäeva formaadis 15/03/2026, kui ootad ISO-formaati. Piire samuti ei kontrollita, ei stringi pikkuse ega arvu vahemiku osas: vanus 350 pääseb läbi ilma pilgutamata. Väljadevaheline kooskõla jääb samuti kättesaamatuks – end_date, mis on varasem kui start_date, on täiesti kehtiv JSON. Ja ärireeglite kehtivus ei peaks API-t huvitama: SIRET (Prantsuse ettevõtte ID) peab olema neliteist numbrit, kuid see on sinu domeeni teadmine, mitte dekooderi oma.
Nendel neljal kategoorial on üks hirmutav ühine joon: need ei põhjusta nähtavaid vigu. Andmebaasi salvestatud vigane e-posti aadress ei avaldu enne, kui e-posti kampaania nädalaid hiljem tagasi põrkab. Seega reegel: valideeri enne püsivustamist, mitte kunagi pärast.
Pythoni valideerimine jsonschema-ga
Praktiline järeldus on, et vajad samade andmete jaoks kahte skeemi. Esimene läheb API-le, tahtlikult lahja, piirdudes sellega, mida range režiim aktsepteerib. Teine jääb sinu juurde ja kannab peenemaid piiranguid – format, pattern, minimum, maximum. See näiline dubleerimine on tegelikult murede eraldamine: üks raamistab genereerimist, teine kaitseb sinu salvestusruumi. Allpool toodud näites ilmub mõlemasse ainult rolli enum, sest see on ainus piirang, mida mõlemal tasandil väljendada saab.
import json
from jsonschema import validate, ValidationError
# Skeem OpenAI API-le (range, ilma formaadi/mustrita)
api_schema = {
"type": "object",
"properties": {
"email": {"type": "string"},
"age": {"type": "integer"},
"role": {"type": "string", "enum": ["admin", "user", "viewer"]}
},
"required": ["email", "age", "role"],
"additionalProperties": False
}
# Laiendatud skeem kliendipoolseks valideerimiseks
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]:
"""Valideerib LLM-i vastuse laiendatud skeemi vastu."""
try:
validate(instance=data, schema=validation_schema)
return True, "Kehtiv"
except ValidationError as e:
return False, f"Viga: {e.message}"
Valideerimine Pydanticuga
Pydantic on Pythonis valideerimiseks sageli mugavam kui jsonschema ja erinevus seisneb selles, mida sa väljundina saad. jsonschema ütleb sulle jah või ei ja jätab sind sõnastikuga, mida manipuleerid data["email"] kaudu ilma toimetaja abita. Pydantic tagastab tüübitud objekti: automaatne täitmine töötab, atribuudi nimes olev trükiviga avastatakse kirjutamise ajal ja andmed liiguvad edasi ilma teisendamiseta.
Mudel ContactExtraction väljendab piire otse väljade deklaratsioonides. field_validator väljal date_extraction katab juhtumi, mida ükski tüübimärge tabada ei saa: string on tõesti string, kuid see peab esindama tegelikku kuupäeva – 2026-02-31 rahuldab iga mõistliku pattern-i, kuid seda ei eksisteeri. Ekstraktsioonifunktsioon näitab tervet ahelat, alates API-le saadetud lahjast skeemist kuni valideeritud instantsieerimiseni.
from pydantic import BaseModel, Field, field_validator
from pydantic import EmailStr
from datetime import date
class ContactExtraction(BaseModel):
"""Valideerimisskeem kontakti ekstraktsiooniks."""
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"Vigane kuupäev: {v}")
def extract_and_validate(text: str) -> ContactExtraction:
"""Ekstrahib kontakti ja valideerib andmed."""
# Skeem API-le (ilma peenemate piiranguteta)
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="Ekstrahi kontaktinfo. "
"Kuupäeva formaat: YYYY-MM-DD.",
input=text,
text={
"format": {
"type": "json_schema",
"name": "contact",
"schema": api_schema,
"strict": True
}
}
)
data = json.loads(response.output_text)
# Pydanticu valideerimine peenemate piirangutega
return ContactExtraction(**data)
Valideerimine Zodiga (TypeScript/Node.js)
Kui sinu taustasüsteem on TypeScriptis, on Zod referentstööriist ja see toob kaasa eelise, mida Pydantic pakkuma ei pea: z.infer tuletab TypeScripti tüübi otse valideerimisskeemist. Kirjeldad kuju üks kord ja kompilaator teab seejärel Invoice struktuuri, ilma et peaksid paralleelset liidest hooldama, nii et lahknevuse ohtu pole.
Allpool olev arve skeem illustreerib tööjaotust: API poolel on siret lihtsalt string; Zodi poolel peab see olema täpselt neliteist tähemärki pikk ja sisaldama ainult numbreid. Lõplik parse tõstab erindi, kui andmed ei sobi, ja see ongi soovitud käitumine – valju veateade, mis katkestab dokumendi töötlemise, on parem kui fantaasia-SIRET-iga arve, mis salvestatakse andmebaasi kümne tuhande muu sekka.
import { z } from "zod";
import OpenAI from "openai";
const client = new OpenAI();
// Zodi skeem peenemate valideerimistega
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: "Ekstrahi arve andmed.",
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);
// Zodi valideerimine peenemate piirangutega
return InvoiceSchema.parse(data);
}
Muster: kordus parandusega
Kui valideerimine ebaõnnestub, saada viga mudelile tagasi parandamiseks. See refleks muudab tõrke olemust: vale formaadis kuupäev pole enam kasutajani jõudev erind, vaid mõnesaja millisekundi pikkune lisaring, mida keegi ei märka. Mehhanism on lihtne – süstime valideerimissõnumi järgmise katse vihjesse uuesti, nii et mudel teab täpselt, mis valesti läks, selle asemel et teist korda pimesi arvata.
See mugavus nõuab siiski piire. Piira katsete arvu, muidu maksab võimatu piirang – näiteks välismaiste numbrite jaoks liiga range pattern – sulle kõnesid lõputus tsüklis. Ja jälgi korduste määra: kui veerand sinu ekstraktsioonidest läbib korduse, peitub probleem algses vihjes või skeemis, mitte mudelis.
def extract_with_retry(prompt: str, schema: dict,
validator, max_retries: int = 3) -> dict:
"""Ekstrahib ja valideerib automaatse kordusega."""
last_error = None
for attempt in range(max_retries):
input_text = prompt
if last_error:
input_text += (f"\n\nHOIATUS: Sinu eelmisel vastusel oli "
f"see valideerimisviga: {last_error}\n"
f"Paranda ja proovi uuesti.")
response = client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature nõuab 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"Ebaõnnestus pärast {max_retries} katset: {last_error}")
Kalendrikutsete testpink
Ehita Pydanticu skeem sündmuste ekstrakteerimiseks – pealkiri, kuupäev, kellaaeg, asukoht, osalejad – ja ühenda see Struktureeritud Väljundi kutse taha. Testi viiel kutseid sisaldaval e-kirjal, veendudes, et kaasad vähemalt ühe, kus kellaaeg on kirjutatud sõnadega („neljapäeva hilises hommikupoolikus“), ja ühe, kus asukoht on kaudne („nagu tavaliselt nõupidamisruumis“). Need on juhtumid, mis valideerimise lõhuvad, ja need domineerivad päris postkastis.
Seejärel lisa automaatne kordus ja mõõda kaht näitajat: esimese katse õnnestumise määra ja pärast kordust saadud määra. Teine ütleb sulle, mida parandus annab, esimene aga seda, kas peaksid oma juhiseid ümber tegema, mitte lootma teisele võimalusele.
Peamised punktid
- Struktureeritud Väljund garanteerib struktuuri, mitte semantilist kehtivust
- Kasuta kahte skeemi: üks API-le (range), teine kliendi valideerimiseks
- Pydantic (Python) ja Zod (TypeScript) on referentstööriistad
- Tagasisidega korduse muster parandab enamiku valideerimisvigadest
- Valideeri alati kliendipoolselt enne andmete püsivustamist