Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Validavimas naudojant JSON Schema ir Zod

Paskaita 11 iš 16 Atnaujinta 2026 m. lapkričio 3 d. Kūrėjas
Šiame puslapyje
  1. Validavimas naudojant JSON Schema ir Zod
  2. Kodėl reikia validuoti gavus duomenis
  3. Python validavimas naudojant jsonschema
  4. Validavimas naudojant Pydantic
  5. Validavimas naudojant Zod (TypeScript/Node.js)
  6. Šablonas: kartojimas su taisymu
  7. Kalendoriaus kvietimų testavimo stendas
  8. Svarbiausi punktai

Pamoka atnaujinta 2026 m. lapkričio 3 d. pagal „OpenAI“ dokumentaciją: parametrai temperature ir top_p priimami tik esant none lygio samprotavimui, tuo tarpu GPT-5.6 modeliai pagal nutylėjimą samprotauja (medium). Todėl kvietimuose, kuriuose nustatomi šie parametrai, būtina nurodyti reasoning={"effort": "none"} (Responses API) arba reasoning_effort="none" (Chat Completions). Šaltiniai: Using GPT-6 · GPT-5.6 Terra.

Validavimas naudojant JSON Schema ir Zod

Struktūrizuota išvestis (Structured Output) garantuoja atsakymo struktūrą, bet ne duomenų semantinį teisingumą. Lauke „el. paštas“ gali būti įvesta eilutė, kuri nėra galiojantis el. pašto adresas. Kliento pusės validavimas naudojant JSON Schema arba Zod yra būtinas papildomas žingsnis kuriant patikimą sistemą.

Kodėl reikia validuoti gavus duomenis

Įsivertink, ką garantuoja API, ir darbo pasiskirstymas taps aiškus. „OpenAI“ struktūrizuota išvestis užtikrina, kad JSON sintaksiškai būtų teisingas, kad deklaruoti tipai būtų gerbiami – eilutė lieka eilute, sveikasis skaičius lieka sveikuoju skaičiumi – kad visi privalomi laukai būtų pateikti ir kad reikšmės, apribotos enum, priklausytų sąrašui. Šiais keturiais aspektais gali rašyti kodą su pasitikėjimu.

Visa kita tenka tau, apimant keturias problemų grupes. Formato apribojimai išvengia griežtos schemos: niekas nesutrukdys modeliui grąžinti jean.dupont(at)example.fr lauke email arba datos formatu 15/03/2026, kai tikiesi ISO. Ribos taip pat netikrinamos – nei eilutės ilgio, nei skaičių diapazono: 350 metų amžius bus priimtas be jokių klausimų. Tarpusavio laukų nuoseklumas taip pat nepasiekiamas – end_date, ankstesnė už start_date, yra visiškai teisingas JSON. Ir verslo taisyklių galiojimas API nerūpi: SIRET (Prancūzijos įmonės ID) turi būti keturiolikos skaitmenų, bet tai tavo dalykinė žinia, o ne dekoderio pareiga.

Šios keturios grupės turi vieną baisų bruožą: jos nesukelia matomų klaidų. Į duomenų bazę įrašytas neteisingas el. pašto adresas pasireikš tik po kelių savaičių, kai el. laiškų kampanija grįš kaip nepristatyta. Todėl taisyklė tokia: validuok prieš įrašydamas, niekada – po to.

Python validavimas naudojant jsonschema

Praktinė išvada ta, kad tiems patiems duomenims reikia dviejų schemų. Pirmoji siunčiama API – ji tyčia supaprastinta, apribota tuo, ką priima griežtas režimas. Antroji lieka pas tave ir turi tikslius apribojimus – format, pattern, minimum, maximum. Šis akivaizdus dubliavimas iš tikrųjų yra atsakomybių atskyrimas: viena schema apibrėžia generavimą, kita saugo tavo saugyklą. Toliau pateiktame pavyzdyje tik rolės enum atsiranda abiejose schemose, nes tai vienintelis apribojimas, kurį gali išreikšti abu lygmenys.

import json
from jsonschema import validate, ValidationError

# Schema OpenAI API (griežta, be 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
}

# Išplėsta schema kliento pusės validavimui
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]:
    """Validuoja LLM atsakymą pagal išplėstą schemą."""
    try:
        validate(instance=data, schema=validation_schema)
        return True, "Valid"
    except ValidationError as e:
        return False, f"Error: {e.message}"

Validavimas naudojant Pydantic

Python kalboje Pydantic dažnai yra patogesnis už jsonschema, o skirtumas slypi gaunamoje išvestyje. jsonschema tau pasako taip arba ne ir palieka su žodynu, kuriuo manipuliuoji per `data[“email”]” be redaktoriaus pagalbos. Pydantic grąžina tipizuotą objektą: veikia automatinis užbaigimas, rašybos klaida atributo pavadinime aptinkama rašymo metu, o duomenys toliau cirkuliuoja be konvertavimo.

Modelis ContactExtraction išreiškia ribas tiesiogiai laukų deklaracijose. field_validator laukui date_extraction apima atvejį, kurio negali sugauti joks tipo anotavimas: eilutė iš tiesų yra eilutė, bet ji turi vaizduoti realią datą – 2026-02-31 tenkina bet kokį pagrįstą pattern, tačiau tokios datos nėra. Ekstrahavimo funkcija rodo visą grandinę – nuo supaprastintos schemos, siunčiamos API, iki validuoto instancijavimo.

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

class ContactExtraction(BaseModel):
    """Validavimo schema kontaktų ekstrahavimui."""
    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:
    """Ekstrahuoja kontaktą ir validuoja duomenis."""
    # Schema API (be tikslių apribojimų)
    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 validavimas su tiksliais apribojimais
    return ContactExtraction(**data)

Validavimas naudojant Zod (TypeScript/Node.js)

Jei tavo serverio pusė parašyta TypeScript, Zod yra pagrindinis įrankis, turintis pranašumą, kurio Pydantic neturi: z.infer išveda TypeScript tipą tiesiai iš validavimo schemos. Formą aprašai vieną kartą, o kompiliatorius tada žino Invoice struktūrą be poreikio palaikyti lygiagrečią sąsają, todėl nėra rizikos, kad jos išsiskirs.

Toliau pateikta sąskaitos faktūros schema iliustruoja atsakomybių atskyrimą: API pusėje siret yra tiesiog eilutė; Zod pusėje ji turi būti tiksliai keturiolikos simbolių ir sudaryta tik iš skaitmenų. Galutinis parse išmeta išimtį, jei duomenys neatitinka, ir tai yra pageidaujamas elgesys – garsi klaida, nutraukianti dokumento apdorojimą, yra geriau nei į duomenų bazę tarp dešimties tūkstančių kitų įrašyta fiktyvi sąskaita su neteisingu SIRET.

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

const client = new OpenAI();

// Zod schema su tiksliais validavimais
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 validavimas su tiksliais apribojimais
  return InvoiceSchema.parse(data);
}

Šablonas: kartojimas su taisymu

Kai validavimas nepavyksta, nusiųsk klaidą atgal modeliui, kad jis ją ištaisytų. Šis refleksas pakeičia nesėkmės pobūdį: neteisingo formato data tampa ne išimtimi, kylančia iki vartotojo, o papildomu keliavimu pirmyn ir atgal, trunkančiu kelias šimtus milisekundžių, kurio niekas nepastebi. Mechanizmas paprastas – validavimo pranešimą vėl įterpiame į kito bandymo užklausą, todėl modelis tiksliai žino, kas nutiko, užuot aklai spėliojęs antrą kartą.

Tačiau šiam komfortui reikia ribų. Apribok bandymų skaičių, kitaip neįmanomas apribojimas – pavyzdžiui, per griežtas pattern užsienio numeriams – kainuos tau begalinį kvietimų ciklą. Ir stebėk kartojimų dažnį: jei ketvirtadalis tavo ekstrahavimų eina per pakartotinį bandymą, problema slypi pradiniame raginime (prompt) arba schemoje, o ne modelyje.

def extract_with_retry(prompt: str, schema: dict,
                       validator, max_retries: int = 3) -> dict:
    """Ekstrahuoja ir validuoja su automatiniu kartojimu."""
    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}")

Kalendoriaus kvietimų testavimo stendas

Sukurk Pydantic schemą renginiams ekstrahuoti – pavadinimas, data, laikas, vieta, dalyviai – ir prijunk ją prie Struktūrizuotos išvesties kvietimo. Ištirk penkis el. laiškus su kvietimais, būtinai įtraukdamas bent vieną, kuriame laikas parašytas žodžiais („ketvirtadienį vėlyvą rytą“), ir vieną, kuriame vieta numanoma („kaip įprasta posėdžių salėje“). Būtent šie atvejai sugriauna validavimą, ir realioje pašto dėžutėje jie vyrauja.

Tada pridėk automatinį kartojimą ir išmatuok du rodiklius: pirmojo bandymo sėkmės rodiklį ir rodiklį po kartojimų. Antrasis parodo, ką duoda taisymas, o pirmasis – ar turėtum perdirbti savo instrukcijas, užuot tikėjęsis antro šanso.

Svarbiausi punktai

  • Struktūrizuota išvestis garantuoja struktūrą, bet ne semantinį teisingumą
  • Naudok dvi schemas: vieną API (griežtą), kitą kliento pusės validavimui
  • Pydantic (Python) ir Zod (TypeScript) yra pagrindiniai įrankiai
  • Kartojimo su grįžtamuoju ryšiu šablonas ištaiso daugumą validavimo klaidų
  • Visada validuok kliento pusėje prieš įrašydamas duomenis