Валидация с JSON Schema и Zod
На тази страница
Урокът е актуализиран на 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) са референтните инструменти
- Шаблонът за повторен опит с обратна връзка коригира повечето грешки при валидация
- Винаги валидирайте на страната на клиента преди запазване на данните