Структурированный вывод

Решение: Укрощение свободного текста в структуры данных

Structured output (структурированный вывод) — это способ ограничить ответ LLM так, чтобы он следовал конкретной схеме: JSON-объекту, типизированному набору параметров функции или любой валидируемой структуре данных, вместо свободного текста. Представь, что ты даёшь модели форму для заполнения, а не чистый лист. Обычный промпт может вернуть «Конечно! Клиента зовут Анна, сумма заказа примерно 42 доллара.» — отлично читается человеком, но для кода это кошмар. Структурированный вывод заставляет тот же ответ принять вид { "name": "Анна", "total": 42.0 }, и так каждый раз.

Как это работает

Под капотом есть два основных механизма. JSON mode сообщает модели, что весь её ответ должен быть одним валидным JSON-документом, — это убирает «полезную» болтовню вокруг данных. Function calling (вызов функций, он же tool calling) идёт дальше: ты описываешь функцию и её параметры как схему, и API ограничивает генерацию так, что модель может выдать только аргументы, совпадающие по именам полей и типам с твоим описанием. Многие провайдеры реализуют это через ограниченное декодирование (constrained decoding) — на каждом шаге модель может выбрать только те токены, которые сохраняют вывод синтаксически валидным по схеме, так что некорректный ответ становится структурно невозможным, а не просто маловероятным.

Когда применять — и в чём подвох

Используй структурированный вывод всегда, когда ответ LLM напрямую подаётся в другой код: пайплайны извлечения данных, ответы API, запись в базу, вызовы инструментов агентом или генерация конфигов. Главный выигрыш в том, что можно выбросить хрупкие регулярки и парсинг строк и доверять форме данных. Ключевой подвох: валидный JSON — это не то же самое, что верные данные. Схема гарантирует форму (есть поле total, и оно число), но никогда не гарантирует смысл — модель всё ещё может галлюцинировать неправильное число или перевернуть булево значение. Например, попроси счёт в виде { "amount": number, "currency": string, "paid": boolean } — и получишь идеально валидный JSON, где amount ошибается на разряд, а paid перевёрнут. Всегда валидируй значения инструментом вроде Pydantic или Zod, а не только схему, и при ошибке возвращай её модели для одной-двух повторных попыток.

Где это используется?

• Форматирование ответов API: Гарантированные JSON-ответы, которые парсеры могут использовать без обработки ошибок формата
• Пайплайны извлечения данных: Извлечение структурированных полей (имя, дата, сумма) из неструктурированных документов в масштабе
• Автоматизация заполнения форм: Преобразование произвольных форм или писем в валидированные записи базы данных
• Генерация конфигурации: Превращение описаний фич на естественном языке в типизированные объекты конфигурации или infrastructure-as-code
• Частая ловушка: семантически неверные значения: Даже в JSON mode LLM может выдать валидный JSON с неверными значениями (придуманные даты, инвертированные булевы) — всегда валидируйте значения, а не только форму схемы, с помощью Pydantic или Zod

Попробуйте сами!

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