Pydantic Structured Outputs: Ръководство…

Q: Каква е разликата между JSON mode и Structured Outputs в OpenAI?

JSON mode ( response_format={"type": "json_object"} ) гарантира само, че отговорът е валиден JSON, но не и че следва вашата схема. Моделът може да върне произволни ключове. Structured Outputs ( {"type": "json_schema", "strict": true} ) използва constrained decoding и гарантира, че всеки токен следва дефинираната схема. В продукция винаги избирайте втория вариант.

Q: Подкрепя ли Claude structured outputs нативно?

Claude няма отделен strict флаг като OpenAI, но реалният еквивалент е tool use с tool_choice={"type": "tool", "name": "..."} . Това принуждава модела да върне аргументи, които отговарят на input_schema на инструмента. Библиотеката instructor обвива този механизъм и го прави прозрачен.

Актуализирано: 18 юни 2026

Структурираният изход от LLM е техника, при която моделът връща данни в строго дефинирана JSON схема (обикновено описана с Pydantic клас) вместо свободен текст, така че всяко поле да има правилен тип и стойност. В средата на 2026 г. OpenAI, Anthropic и Google вече поддържат нативен structured output режим, а библиотеката instructor остава най-практичният абстракционен слой за валидация, повторни опити и стрийминг. В това ръководство ще покажа как ги използвам в продукция, какви грешки видях лично и кога си струва да се връщате към function calling.

OpenAI response_format={"type": "json_schema", "strict": true} гарантира 100% валиден JSON, но има ограничения за oneOf, $ref и максимална дълбочина 5.
Pydantic v2 е де-факто стандартът за схеми. Методът model_json_schema() произвежда JSON Schema, която и OpenAI, и Anthropic приемат директно.
Библиотеката instructor добавя автоматични повторения при ValidationError, частичен стрийминг и поддържа над 15 доставчика през един API.
Function calling е по-подходящ, когато моделът трябва да избира между няколко инструмента. Structured outputs работи по-добре, когато винаги искаме един и същ формат.
Дискриминирани Union типове са най-надеждният начин да моделирате „един от" сценарии без да зависите от oneOf.
Винаги добавяйте полета chain_of_thought или reasoning ПРЕДИ структурните полета. Измерванията показват 8–15% по-висока точност.

Какво е структуриран изход от LLM?

Структурираният изход (на английски structured output или JSON mode) е режим на работа на голям езиков модел, при който отговорът се генерира под строг ограничителен слой на декодера, така че да отговаря точно на предварително дефинирана JSON Schema. На практика, вместо да получите низ, който после се опитвате да парсвате с json.loads и да се молите, директно получавате обект, който вече е валиден спрямо вашия Pydantic клас.

Разликата с „моля те, върни JSON" в системния промпт е огромна. При strict режим на OpenAI (достъпен от gpt-4o-2024-08-06 нагоре, включително gpt-4.1 и gpt-5 линиите от 2026 г.) декодерът използва ограничено вземане на проби (constrained decoding) и буквално не може да генерира токен, който нарушава схемата. Това намалява процента на повредени отговори от типичните 3–7% при свободен JSON до практически нула.

Честно, в моя последен пайплайн за извличане на структури от документи имах 240 000 заявки на месец. Преминаването от json_object към json_schema намали разходите за повторно изпълнение с 11% и махна цял слой защитен код, който досега трябваше да съществува.

OpenAI Structured Outputs в strict режим

Най-важното за strict режима е, че налага едно много стриктно подмножество на JSON Schema. Според официалната OpenAI документация за structured outputs всички полета трябва да бъдат изброени в required, additionalProperties трябва да е false, и не се поддържат $ref към външни схеми, oneOf или максимална дълбочина над 5.

Ето минимален пример с новия SDK (openai>=1.40), който използвам в продукция:

from openai import OpenAI
from pydantic import BaseModel, Field
from typing import Literal

client = OpenAI()

class Invoice(BaseModel):
    vendor_name: str = Field(description="Юридическо име на доставчика")
    invoice_number: str
    total_amount_bgn: float = Field(ge=0)
    currency: Literal["BGN", "EUR", "USD"]
    line_items: list[str]
    reasoning: str = Field(description="Кратко обяснение как е извлечена сумата")

response = client.beta.chat.completions.parse(
    model="gpt-4.1-2026-05",
    messages=[
        {"role": "system", "content": "Извлечи данни от фактурата."},
        {"role": "user", "content": invoice_text},
    ],
    response_format=Invoice,
)

invoice: Invoice = response.choices[0].message.parsed
print(invoice.total_amount_bgn)

Обърнете внимание на полето reasoning. Поставено е последно умишлено, но всъщност това е грешка, която съм поправял неведнъж. По-новите изследвания (включително резултатите, които споделих в напредналите техники за промпт инженеринг) показват, че разполагането на reasoning поле след структурните полета намалява точността, защото моделът ангажира стойности преди да разсъждава. За най-добра точност винаги поставяйте reasoning преди числови или категорни полета.

Дефиниране на схеми с Pydantic v2

Pydantic v2 (актуална версия 2.9 към юни 2026) е практически стандартът за описване на схеми за LLM. Причината е проста: можете да напишете един клас и да получите едновременно (1) JSON Schema за модела, (2) Python типове за вашия IDE и (3) валидатори за входни данни. Конкурентите като TypedDict или dataclass нямат толкова добра поддръжка на JSON Schema, а ръчното писане е изтощително. Официалната документация на Pydantic за JSON Schema покрива всички нюанси, включително draft-2020-12 съвместимостта.

Особено полезни шаблони, които използвам редовно:

from pydantic import BaseModel, Field, model_validator
from typing import Annotated, Literal
from datetime import date

# 1. Дискриминиран Union (заместител на oneOf)
class CreditCardPayment(BaseModel):
    method: Literal["credit_card"]
    last_four: str = Field(pattern=r"^\d{4}$")
    expiry: date

class BankTransferPayment(BaseModel):
    method: Literal["bank_transfer"]
    iban: str = Field(pattern=r"^[A-Z]{2}\d{2}[A-Z0-9]+$")

Payment = Annotated[
    CreditCardPayment | BankTransferPayment,
    Field(discriminator="method"),
]

# 2. Валидация след извличане
class ExtractedDate(BaseModel):
    raw_text: str
    iso_date: date

    @model_validator(mode="after")
    def date_must_match_text(self):
        if str(self.iso_date.year) not in self.raw_text:
            raise ValueError("Извлечената година не съвпада с текста")
        return self

Дискриминираните типове са истинска магия за LLM. Моделът връща method първо, после знае кои полета да попълни. Без дискриминатор често виждам халюциниране на смесени полета (например IBAN с дата на изтичане), което изобщо не е забавно за дебъгване.

Библиотеката Instructor: повторения, стрийминг и мулти-доставчик

Когато трябва да работите с повече от един доставчик (или просто не искате да управлявате повторения ръчно), instructor от Jason Liu е най-зрелият избор. Документацията за библиотеката instructor описва над 15 поддържани доставчика: OpenAI, Anthropic, Google, Mistral, Cohere, Groq, Ollama и други.

import instructor
from anthropic import Anthropic
from pydantic import BaseModel, Field

client = instructor.from_anthropic(Anthropic())

class Ticket(BaseModel):
    priority: Literal["low", "medium", "high", "critical"]
    category: Literal["bug", "feature", "support"]
    estimated_hours: float = Field(ge=0, le=200)
    summary: str

ticket = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    response_model=Ticket,
    max_retries=3,
    messages=[{"role": "user", "content": ticket_email}],
)

Това, което прави instructor наистина полезен в продукция, са три неща. Първо, max_retries автоматично повтаря с грешката от Pydantic ValidationError като допълнителен контекст към модела, така че нямам нужда от обвиващ код. Второ, create_partial() ми позволява да стриймвам структуриран изход и да рендерирам частично попълнен обект в UI преди да е готов целият отговор. Трето, един и същ response_model работи навсякъде. Мога да сменя Anthropic с OpenAI чрез един ред.

Структуриран изход с Anthropic Claude

Claude (Opus 4.8 и Sonnet 4.6 към юни 2026) няма същия strict механизъм като OpenAI, но има два надеждни подхода. Първият е чрез tool use: дефинирате един инструмент с очакваната схема и принуждавате модела да го извика чрез tool_choice. Това е техниката, която instructor използва вътрешно.

import anthropic, json

client = anthropic.Anthropic()

extract_tool = {
    "name": "save_extraction",
    "description": "Запази извлечените полета",
    "input_schema": Invoice.model_json_schema(),
}

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=2048,
    tools=[extract_tool],
    tool_choice={"type": "tool", "name": "save_extraction"},
    messages=[{"role": "user", "content": invoice_text}],
)

raw = next(b for b in response.content if b.type == "tool_use").input
invoice = Invoice.model_validate(raw)

Вторият подход (prefilling) е по-евтин: добавяте {"role": "assistant", "content": "{"} като последно съобщение, така Claude задължително продължава с JSON. На практика комбинирам двата: tool_choice за strict схема и prefill за по-кратки отговори без оверхеда на tool wrapping.

Как да се справяме с грешки при валидация?

Дори при strict режим грешките се случват, най-често когато бизнес логиката (например „общата сума трябва да съвпада със сбора на редовете") не може да се изрази в JSON Schema. Моят шаблон за обработка изглежда така:

from pydantic import ValidationError
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10))
def extract_with_repair(text: str, schema: type[BaseModel]) -> BaseModel:
    try:
        return _call_llm(text, schema)
    except ValidationError as e:
        # Подайте грешката обратно към модела като контекст
        repair_prompt = (
            f"Предишният ти отговор не премина валидация:\n{e.json()}\n"
            f"Поправи отговора, така че да съответства на схемата."
        )
        return _call_llm(text + "\n\n" + repair_prompt, schema)

Structured Outputs срещу Function Calling

Често ме питат кога да избера structured outputs и кога function calling. Накратко: structured outputs е, когато винаги искате един и същ формат на отговор; function calling е, когато моделът трябва да избира между няколко действия. Ето подробно сравнение:

Критерий	Structured Outputs	Function Calling
Гарантирана JSON валидност	Да (strict mode)	Да (при tool_choice="required")
Множество схеми наведнъж	Не, една на заявка	Да, моделът избира
Латентност	По-ниска (1 преминаване)	По-висока (избор + аргументи)
Подходящо за	Извличане на данни, класификация	Агенти, инструментални пайплайни
Цена за tokens	По-ниска (без tool wrapping)	+5–15% overhead
Поддръжка на oneOf	Не, само дискриминирани Union	Да, чрез отделни tools
Стрийминг	Да (partial parsing)	Частична, само аргументи

Ако вашият случай е „анализирай това писмо и върни структурирани метаданни", изберете structured outputs. Ако е „на базата на това писмо реши дали да изпратиш отговор, да създадеш билет или да го игнорираш", изберете function calling. За по-сложни случаи разгледайте подробното ми ръководство за function calling и tool use.

Продукционни шаблони и наблюдаемост

След две години изграждане на пайплайни със структуриран изход, ето шепа шаблони, които винаги използвам:

1. Версиониране на схемите

Всяка Pydantic схема в продукция има поле schema_version: Literal["2026-06-18"]. Когато променя схемата, пиша мигратор, който чете стари записи и ги привежда към новата версия. Без това след шест месеца ще имате данни в БД, които не съвпадат с актуалния клас, а тестовете ще се чупят неочаквано.

2. Двустепенно извличане за дълги документи

За документи над 10 страници първо извличам „индекс" (списък от страници и какво съдържат), после извиквам отделна структурирана заявка за всеки сегмент. Така избягвам ограничението за дълбочина 5 и моделът работи по-точно върху по-малки контексти. Това е същият принцип, който прилагам и в RAG пайплайните. Вижте ръководството за реранкинг в RAG.

3. Наблюдаемост с тагнати поля

Добавям поле confidence: Literal["high", "medium", "low"] към всяка извличана схема и групирам метриките по него. Грешките при валидация почти винаги корелират с „low", така че мога да филтрирам и да изпращам само тези за човешки преглед. За цялостен подход към измерване вижте моето ръководство за оценка на LLM модели.

4. Кеширане на схемата при доставчика

OpenAI компилира JSON Schema при първото използване (около 2–10 секунди при сложни схеми) и я кешира за около 10 минути. В продукция това означава първата заявка да е по-бавна, затова затоплете кеша при стартиране на услугата чрез фалшива заявка. Подобна оптимизация описвам и в статията за MCP сървър с Python.

5. Pydantic v2 strict mode

Винаги включвам model_config = ConfigDict(strict=True, extra="forbid"). Това хваща типови грешки на ниво валидатор. Например, ако моделът върне "5" вместо 5, ще получите ValidationError, която instructor ще опита да поправи автоматично.

Често задавани въпроси

Каква е разликата между JSON mode и Structured Outputs в OpenAI?

JSON mode (response_format={"type": "json_object"}) гарантира само, че отговорът е валиден JSON, но не и че следва вашата схема. Моделът може да върне произволни ключове. Structured Outputs ({"type": "json_schema", "strict": true}) използва constrained decoding и гарантира, че всеки токен следва дефинираната схема. В продукция винаги избирайте втория вариант.

Подкрепя ли Claude structured outputs нативно?

Claude няма отделен strict флаг като OpenAI, но реалният еквивалент е tool use с tool_choice={"type": "tool", "name": "..."}. Това принуждава модела да върне аргументи, които отговарят на input_schema на инструмента. Библиотеката instructor обвива този механизъм и го прави прозрачен.

Как да форсирам JSON изход от LLM без strict режим?

Три проверени техники: (1) добавете „Отговори САМО с валиден JSON, без обяснения" в системния промпт; (2) използвайте prefilling, тоест добавете { като начало на отговора (работи в Claude и локални модели); (3) обвийте отговора с json.loads и при грешка повторете с грешката в промпта. За продукция комбинирайте техника 2 с Pydantic валидация.

Защо моделът връща празни полета при опционални стойности?

В strict режим всички полета са задължителни. Ако обявите поле като Optional[str] = None, Pydantic генерира тип ["string", "null"], който strict приема. Моделът ще върне null вместо да пропусне ключа. Никога не маркирайте полета само като Optional без подразбираща се стойност, защото това чупи генерирането на JSON Schema.

Колко струва допълнително structured output срещу свободен текст?

В моите измервания (gpt-4.1, юни 2026) разликата в цената е под 2%, основно от допълнителните токени в JSON форматирането. Latency-то обаче е до 30% по-високо при сложни схеми с над 20 полета заради constrained decoding. За схеми с под 10 полета разликата е незабележима.