Премини към основното съдържание
Български— Изберете език
Меню

Валидация с JSON Schema и Zod

Урок 11 от 16 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Валидация с JSON Schema и Zod
  2. Защо да валидирате след получаване
  3. Python валидация с jsonschema
  4. Валидация с Pydantic
  5. Валидация със Zod (TypeScript/Node.js)
  6. Шаблон: повторен опит с корекция
  7. Тестова среда за покани за календар
  8. Ключови изводи

Урокът е актуализиран на 3 ноември 2026 г. въз основа на документацията на OpenAI: параметрите temperature и top_p се приемат само при усилие за разсъждение (reasoning effort) от none, докато моделите GPT-5.6 разсъждават по подразбиране (medium). Заявките, които задават тези параметри, следователно трябва да специфицират reasoning={"effort": "none"} (Responses API) или reasoning_effort="none" (Chat Completions). Източници: Използване на GPT-6 · GPT-5.6 Terra.

Валидация с JSON Schema и Zod

Структурираният изход (Structured Output) гарантира структурата на отговора, но не и семантичната валидност на данните. Полето „email“ може да съдържа низ, който не е валиден имейл адрес. Валидацията на страната на клиента, използваща JSON Schema или Zod, е същественото допълнение за изграждане на надежден процес.

Защо да валидирате след получаване

Направете преглед на това какво гарантира API, и разделението на труда става ясно. Structured Output на OpenAI осигурява, че JSON е синтактично валиден, че декларираните типове се спазват – низът остава низ, цялото число остава цяло число – че всички задължителни полета присъстват и че стойностите, ограничени от enum, принадлежат към списъка. По тези четири точки можете да пишете кода си с увереност.

Всичко останало зависи от Вас, обхващайки четири семейства проблеми. Ограниченията за формат избягват строгата схема: нищо не пречи на модела да върне jean.dupont(at)example.fr в поле email или дата във формат 15/03/2026, когато очаквате ISO. Границите също не се проверяват, нито за дължина на низа, нито за числови диапазони: възраст от 350 години ще премине без проблем. Съгласуваността между полетата остава извън обхвата – end_date, по-ранна от start_date, е напълно валиден JSON. И бизнес валидността няма причина да тревожи API: SIRET (френски бизнес идентификатор) трябва да бъде от четиринадесет цифри, но това е знание на Вашата предметна област, а не на декодера.

Тези четири семейства споделят една обезпокоителна черта: те не причиняват видими грешки. Неправилен имейл, запазен в базата данни, няма да се прояви, докато имейл кампанията не се провали седмици по-късно. Оттук и правилото: валидирайте преди запазване, никога след това.

Python валидация с jsonschema

Практическото следствие е, че се нуждаете от две схеми за едни и същи данни. Първата отива към API, умишлено олекотена, ограничена до това, което строгият режим приема. Втората остава при Вас и носи детайлните ограничения – format, pattern, minimum, maximum. Това привидно дублиране е разделение на отговорностите: едното рамкира генерирането, другото защитава Вашето хранилище. В примера по-долу само enum за ролята се появява и в двете, защото това е единственото ограничение, което и двете нива могат да изразят.

import json
from jsonschema import validate, ValidationError

# Схема за OpenAI API (строга, без 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
}

# Разширена схема за валидация на страната на клиента
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]:
    """Валидира отговора на LLM спрямо разширената схема."""
    try:
        validate(instance=data, schema=validation_schema)
        return True, "Valid"
    except ValidationError as e:
        return False, f"Error: {e.message}"

Валидация с Pydantic

Pydantic често е по-удобен от jsonschema за валидация в Python, а разликата се крие в това, което получавате като изход. jsonschema Ви казва да или не и Ви оставя с речник, манипулиран чрез data["email"] без помощ от редактора. Pydantic връща типизиран обект: автодопълването работи, правописна грешка в името на атрибут се улавя по време на писане и данните циркулират оттук нататък без конвертиране.

Моделът ContactExtraction изразява границите директно в декларациите на полетата. field_validator върху date_extraction покрива случая, който никоя типова анотация не може да улови: низът наистина е низ, но трябва да представлява реална дата – 2026-02-31 удовлетворява всеки разумен pattern, въпреки че не съществува. Функцията за извличане показва цялата верига, от олекотената схема, изпратена до API, до валидираната инстанциация.

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

class ContactExtraction(BaseModel):
    """Схема за валидация при извличане на контакти."""
    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:
    """Извлича контакт и валидира данните."""
    # Схема за API (без детайлни ограничения)
    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 валидация с детайлни ограничения
    return ContactExtraction(**data)

Валидация със Zod (TypeScript/Node.js)

Ако Вашият бекенд е на TypeScript, Zod е референтният инструмент и той носи предимство, което Pydantic не трябва да предоставя: z.infer извежда TypeScript типа директно от схемата за валидация. Описвате структурата веднъж и компилаторът след това познава структурата на Invoice, без Вие да поддържате паралелен интерфейс, така че няма риск от разминаване.

Схемата за фактура по-долу илюстрира разделението на труда: от страна на API, siret е просто низ; от страна на Zod, той трябва да бъде точно четиринадесет знака и да съдържа само цифри. Крайният parse поражда изключение, ако данните не отговарят, и това е желаното поведение – силна грешка, която прекъсва обработката на документа, е по-добра от фактура с фантазиен SIRET, съхранена в базата данни сред десетки хиляди други.

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

const client = new OpenAI();

// Zod схема с детайлни валидации
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 валидация с детайлни ограничения
  return InvoiceSchema.parse(data);
}

Шаблон: повторен опит с корекция

Когато валидацията се провали, изпратете грешката обратно към модела за корекция. Този рефлекс променя природата на неуспеха: дата в грешен формат вече не е изключение, което излиза към потребителя, а допълнително обръщение от няколкостотин милисекунди, което никой не забелязва. Механизмът е прост – инжектираме отново съобщението за валидация в подсказката за следващия опит, така че моделът да знае точно какво се е объркало, вместо да гадае на сляпо втори път.

Този комфорт обаче изисква граници. Ограничете броя на опитите, иначе невъзможно ограничение – например pattern, твърде стриктен за чуждестранни номера – ще Ви струва повиквания в цикъл. И следете процента на повторните опити: ако една четвърт от Вашите извличания минават през повторен опит, проблемът е в първоначалната подсказка или схемата, а не в модела.

def extract_with_retry(prompt: str, schema: dict,
                       validator, max_retries: int = 3) -> dict:
    """Извлича и валидира с автоматичен повторен опит."""
    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 изисква 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}")

Тестова среда за покани за календар

Изградете Pydantic схема за извличане на събития – заглавие, дата, час, местоположение, участници – и я свържете зад извикване на Structured Output. Тествайте върху пет имейла, съдържащи покани, като се уверите, че включвате поне един, където часът е изписан с думи („четвъртък късно сутринта“) и един, където местоположението е подразбиращо се („както обикновено в заседателната зала“). Това са случаите, които разрушават валидацията, и те доминират в реална пощенска кутия.

След това добавете автоматичен повторен опит и измерете две фигури: процента на успех при първия опит и процента след повторния опит. Вторият Ви показва какво печелите от корекцията, първият – дали трябва да преработите инструкциите си, вместо да разчитате на втори шанс.

Ключови изводи

  • Structured Output гарантира структурата, а не семантичната валидност
  • Използвайте две схеми: една за API (строга), една за валидация на клиента
  • Pydantic (Python) и Zod (TypeScript) са референтните инструменти
  • Шаблонът за повторен опит с обратна връзка коригира повечето грешки при валидация
  • Винаги валидирайте на страната на клиента преди запазване на данните