Structured Output: JSON и Pydantic для LLM

Свободный текст неудобен для кода: формат может меняться, поле исчезнуть, а число прийти строкой. Structured output задаёт схему результата и позволяет получить объект с предсказуемыми полями. В Python схему удобно описывать Pydantic-моделью.

from typing import Literal
from pydantic import BaseModel, Field

class Ticket(BaseModel):
    category: Literal["billing", "technical", "other"]
    priority: int = Field(ge=1, le=5)
    summary: str = Field(min_length=1, max_length=300)

Названия, типы, ограничения и описания полей становятся контрактом между моделью и приложением. Провайдер или orchestration library может поддерживать schema-native output либо эмулировать его через tool calling.

JSON mode не равен schema enforcement

Режим «валидный JSON» гарантирует синтаксис JSON, но не обязательно нужные поля и типы. Schema-native structured output ограничивает форму ответа сильнее. После получения всё равно полезно прогнать runtime-валидацию Pydantic: она защищает внутренний код и нормализует обработку ошибок.

Схема должна быть небольшой и однозначной. Используйте enum или Literal вместо произвольной строки, задавайте допустимые диапазоны и отличайте nullable поле от необязательного. Не просите модель вычислять поля, которые надёжнее получить программно.

Если провайдер не поддерживает часть JSON Schema, адаптер может использовать tool strategy. Поведение и поддерживаемые ограничения сверяйте для конкретной модели и версии SDK.

Отказ, ошибка и небезопасное действие

Structured output уменьшает форматные ошибки, но не гарантирует фактическую истинность. Модель может вернуть идеально валидный объект с вымышленными значениями. Для критичных полей нужны источники, business validation и иногда подтверждение человеком.

Обрабатывайте отдельно: отказ модели отвечать, сетевую ошибку, отсутствие результата, schema validation error и нарушение бизнес-правил. Не исправляйте неизвестные данные тихими defaults. Ограниченный retry допустим для случайной форматной ошибки, но не должен бесконечно повторять один и тот же запрос.

Логируйте версию схемы, модель, request id и класс ошибки без секретов и персональных данных. При изменении схемы добавляйте контрактные тесты и совместимость с уже сохранёнными объектами.