Что такое Structured Output? Зачем AI Agent нужен структурированный вывод? Чем JSON Schema отличается от обычного JSON?

Если модель возвращает JSON, но названия полей и типы постепенно «плывут», не ограничивайте её инструкцией в промпте — передайте явную схему и проверяйте результат до записи в систему. Для ответов, которые должен потребить фронтенд, база данных, рабочий процесс или инструмент AI Agent, Structured Output обычно предпочтительнее обычного JSON.

Обычный JSON — это формат данных, JSON mode обычно направлен на получение синтаксически корректного JSON, а Structured Output использует JSON Schema для ограничения структуры, типов и допустимых значений. Для Tool Calling этого всё равно недостаточно: перед выполнением нужны отдельная бизнес-проверка, контроль разрешений и проверка наличия ресурса.

Эта статья предназначена для трёх групп читателей: начинающих разработчиков AI-приложений, которым нужно разложить по местам три похожих понятия; backend-инженеров, выбирающих способ ограничения вывода; и архитекторов AI Agent, проектирующих параметры инструментов, промежуточные состояния и финальный ответ.

Почему «валидный JSON» всё ещё может ломать приложение?

Представьте задачу: модель должна извлечь из письма данные заказа. В первом ответе она возвращает:

{
  "customer": "Иван Петров",
  "total": 149.90,
  "currency": "EUR"
}

Следующий похожий ответ может выглядеть так:

{
  "customer_name": "Иван Петров",
  "amount": "149,90 EUR",
  "currency": "евро"
}

Оба объекта могут быть корректным JSON. Парсер не обязательно выдаст ошибку, однако downstream-код ожидает customer, числовое поле total и код валюты. Проблема обнаружится уже в базе данных, расчёте стоимости или интерфейсе.

Здесь важно разделить несколько уровней контроля:

• Обычный JSON описывает способ представления данных: объект, массив, строка, число, логическое значение или null. Сам по себе формат не говорит, какие поля обязательны и какие значения допустимы.
• JSON mode помогает получить JSON вместо свободного текста. Но он не превращает автоматически требования к полям, типам и перечислениям в исполняемый контракт.
• JSON Schema описывает ожидаемую структуру данных: свойства, типы, обязательные поля, массивы, перечисления и другие ограничения. Документация JSON Schema: пошаговое введение в схемы отдельно объясняет разницу между схемой и экземпляром данных.
• Structured Output — это режим или механизм API, при котором схема передаётся модели как формальное ограничение ожидаемого ответа. Конкретный набор поддерживаемых ключевых слов и гарантии зависят от платформы и модели.

Именно поэтому «ответ можно распарсить» и «ответ подходит для бизнес-логики» — разные утверждения. В первом случае вы проверяете синтаксис. Во втором — контракт, смысл, разрешённые значения и возможность безопасно продолжить выполнение.

JSON Schema — это разновидность JSON-формата?

Нет. Документ JSON Schema сам записывается в синтаксисе JSON, но описывает не бизнес-данные, а правила проверки других данных. Объект с полем "type": "object" является частью схемы, тогда как объект с "order_id": "A-1042" — экземпляром данных, который этой схеме может соответствовать.

На практике различие похоже на разницу между формой заявки и заполненной заявкой. Форма задаёт поля и правила, а заполненный документ содержит конкретные значения.

Когда естественный язык лучше структурированного вывода?

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

Есть несколько признаков, что Structured Output пока не нужен:

1. Ответ читает только человек, а не программа.
2. У результата нет стабильного набора полей.
3. Ошибка формата не запускает автоматическое действие и легко исправляется вручную.
4. Важнее объяснить исключения и контекст, чем получить фиксированный объект.

Например, в чате поддержки модель может вернуть объяснение причины сбоя, несколько вариантов решения и уточняющий вопрос. Попытка поместить всё в заранее заданные поля reason, solution<em>1, solution</em>2 и question не обязательно улучшит продукт. Вы получите формально аккуратный объект, но потеряете гибкость текста.

Если же фронтенд должен отрисовать карточку, база — сохранить запись, а workflow — передать параметры следующему узлу, свободный ответ становится источником лишних отказов. В таком сценарии схема оправдана даже при более сложной интеграции.

Почему AI Agent не может всегда ограничиться обычным JSON?

Потому что агент передаёт не только данные, но и состояние выполнения. Ему могут потребоваться имя инструмента, идентификатор вызова, аргументы, статус, результат, ошибка и признак необходимости повторить операцию. Если эти элементы каждый раз называются по-разному или меняют тип, маршрутизатору приходится угадывать намерение модели.

При этом не нужно заставлять модель выводить внутренние рассуждения. Для оркестратора достаточно наблюдаемого состояния: какой шаг запрошен, какой инструмент выбран, какие параметры переданы и что вернула внешняя система. Внутреннее рассуждение не должно становиться обязательным JSON-полем только ради иллюзии прозрачности.

Как Structured Output меняет извлечение данных?

Для извлечения реквизитов, классификации обращений, разбора счетов и нормализации документов можно представить три уровня зрелости.

Первый уровень: инструкция в промпте

Вы пишете: «Верни только JSON с полями name, email и priority». Такой подход дёшев в разработке и подходит для прототипа. Его слабое место — инструкция остаётся частью текста, а не отдельным машинным контрактом.

Модель может добавить пояснение, переименовать поле, вернуть число как строку или использовать значение high там, где система ожидала urgent. Даже если вы добавите пример, пример не является полноценной проверкой.

Второй уровень: JSON mode

JSON mode полезен, когда основное требование — не допустить текст вокруг объекта. В документации OpenAI Structured Outputs и форматы JSON в API JSON Schema рекомендуется для поддерживаемых моделей, тогда как json_object рассматривается как более старый способ генерации JSON. При этом JSON mode не определяет автоматически нужные свойства и не проверяет смысл полученных значений.

Поэтому JSON mode разумен для слабого обменного контракта, промежуточного прототипа или ответа, который дополнительно нормализуется вашим кодом. Для продуктивной записи в базу данных его нельзя считать заменой схеме.

Третий уровень: Structured Output

Здесь вы задаёте контракт заранее:

• какие поля существуют;
• какие из них обязательны;
• какой тип у каждого значения;
• какие варианты разрешены через enum;
• является ли поле массивом или вложенным объектом;
• разрешены ли дополнительные свойства;
• что делать, если значение отсутствует.

OpenAI указывает, что строгий режим Structured Outputs предназначен для следования переданной схеме, однако поддерживается только подмножество JSON Schema. Подробные ограничения и формат json_schema описаны в официальной документации OpenAI Structured Outputs.

Gemini также поддерживает Structured Output на основе подмножества JSON Schema. В документации Gemini Structured Output перечислены поддерживаемые типы, свойства объектов, обязательные поля, перечисления и ограничения сложных схем. Там же отдельно подчёркивается необходимость проверять значения в приложении даже после получения синтаксически корректного результата.

Anthropic использует JSON Schema для определения параметров инструментов Claude через input<em>schema. Формат и порядок обработки блоков tool</em>use и tool_result описаны в официальной документации Anthropic по Tool Use. Это полезная граница для параметров инструмента, но она не отменяет авторизацию и проверку бизнес-условий.

Чем Structured Output отличается от JSON mode?

JSON mode отвечает прежде всего на вопрос «является ли результат JSON-документом?». Structured Output отвечает на более узкий вопрос: «соответствует ли результат заданной структуре и ограничениям схемы, которые поддерживает этот API?»

Это не делает Structured Output универсальной гарантией. Если модель неверно извлекла дату, перепутала владельца счёта или придумала идентификатор, объект может идеально соответствовать схеме и при этом быть фактически неверным.

Что нужно проверить перед Tool Calling?

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

Допустим, агент формирует запрос на возврат товара:

{
  "order_id": "A-1042",
  "amount": 149.90,
  "reason": "defect"
}

Schema может потребовать строковый order_id, положительное число amount и одно из значений defect, duplicate или other. Но перед вызовом платёжного или складского сервиса нужны дополнительные проверки:

• существует ли заказ с таким идентификатором;
• принадлежит ли он текущему пользователю;
• не превышает ли сумма фактически оплаченный остаток;
• разрешён ли возврат по сроку и статусу заказа;
• имеет ли текущая сессия право выполнять эту операцию;
• не был ли такой вызов уже выполнен ранее.

Поэтому безопасный конвейер выглядит так:

1. Модель создаёт вызов инструмента по схеме.
2. Сервер разбирает JSON и проверяет схему.
3. Бизнес-слой проверяет состояние заказа, лимиты и идемпотентность.
4. Слой авторизации проверяет пользователя, роль и область доступа.
5. Только после этого вызывается внешняя система.
6. Результат инструмента возвращается агенту с исходным call_id или эквивалентным идентификатором.

В руководстве OpenAI по Function Calling параметры функций описываются объектом JSON Schema, а модельный вызов отделён от фактического выполнения функции приложением. В руководстве Gemini по инструментам и Function Calling также разделены генерация вызова, исполнение функции в вашем окружении и возврат результата модели.

Формат аргументов — только первый уровень защиты. Инструмент должен сам проверять разрешения, существование ресурса, диапазоны, лимиты, повторную отправку и потенциально опасные последствия.

Нужна ли Schema и для параметров инструмента, и для финального ответа?

В большинстве производственных агентов — да, но это будут два разных контракта. Схема параметров инструмента защищает границу «модель → исполнитель». Схема финального ответа защищает границу «агент → интерфейс, база или workflow».

Не следует бездумно использовать одну схему для обоих направлений. Инструменту нужны минимальные аргументы для операции, а пользователю — статус, объяснение, отображаемое сообщение и, возможно, ссылки или следующие действия. Разделение контрактов упрощает версии и уменьшает риск, что внутреннее поле случайно станет частью публичного API.

Версионирование интерфейсов и промежуточных состояний

Динамические формы, карточки рекомендаций и панели контроля часто строятся на JSON-описании компонентов. Модель может вернуть тип блока, заголовок, список полей, значения по умолчанию и доступные действия. Frontend затем превращает объект в интерфейс.

Преимущество очевидно: не нужно заранее кодировать каждый вариант ответа вручную. Но появляется скрытая стоимость — схема становится частью клиентского контракта. Если backend начнёт возвращать новый тип компонента, старое приложение может его проигнорировать, отобразить пустой блок или завершиться ошибкой.

Для такого сценария используйте следующие правила:

• добавляйте версию схемы или версию отдельных компонентов;
• задавайте безопасные значения по умолчанию;
• делайте новые поля необязательными, если старый клиент способен их игнорировать;
• сохраняйте текстовый fallback, чтобы пользователь получил результат даже при неизвестном компоненте;
• не позволяйте модели свободно создавать произвольные имена UI-компонентов;
• тестируйте старый клиент на ответах новой версии;
• отдельно проверяйте локализацию, пустые массивы и отсутствие необязательных значений.

В многошаговом AI Agent разделяйте публичный ответ и внутреннее состояние. Публичный ответ может содержать текст для пользователя и компактный объект для интерфейса. Внутреннее состояние должно хранить только то, что нужно оркестратору: текущий шаг, статус, идентификатор операции, ожидаемое действие и результат инструмента.

Определите состояния вроде planned, requested, executed, failed и needs_review, а затем задайте разрешённые переходы. Тогда агент не сможет повторно списать средства только потому, что модель ещё раз сгенерировала похожий вызов.

Изменение имени поля, типа значения или обязательности свойства — это изменение API. Сохраняйте номер версии, миграцию и тестовые примеры. Если новый клиент ожидает поле total_amount, а старый использует total, совместимость должна быть решена на сервере, а не оставлена на усмотрение модели.

Может ли Structured Output гарантировать правильность содержания?

Нет. Он снижает класс ошибок, связанных с форматом, но не доказывает истинность фактов. Схема может гарантировать, что confidence является числом, однако не подтверждает, что оценка действительно обоснована. Она может ограничить статус значениями approved, rejected и review, но не определяет, правильно ли модель выбрала статус.

Для критичных данных добавляйте:

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

Иными словами, Structured Output — это контроль формы, а не сертификат достоверности.

Пошаговая проверка перед запуском

Шаг 1. Определите потребителя

Запишите, кто читает результат: человек, валидатор, инструмент, база, интерфейс или следующий агент. Это решение важнее названия модели.

Шаг 2. Зафиксируйте поля и типы

Для каждого поля укажите тип, обязательность, допустимые значения, единицы измерения и поведение при отсутствии данных. Не добавляйте поля «на будущее», если они не имеют конкретного потребителя.

Шаг 3. Проверьте совместимость платформы

Сравните вашу схему с официальной документацией выбранного API. OpenAI, Gemini и Anthropic могут поддерживать разные подмножества JSON Schema, поэтому перенос схемы между платформами без адаптации рискован.

Шаг 4. Разделите синтаксическую и бизнес-валидацию

Первая проверяет JSON и Schema. Вторая проверяет факты, права, лимиты, существование ресурса и допустимость операции. Обе проверки должны быть видны в логах.

Шаг 5. Добавьте обработку отказов

Модель может вернуть отказ, неполный результат, ошибку инструмента или схему, которую API не принимает. Подготовьте повтор с упрощённым контрактом, текстовый fallback и передачу задачи оператору.

Шаг 6. Протестируйте одинаковый набор входов

Сравните свободный ответ, инструкцию «верни JSON», JSON mode и строгий Structured Output на одних и тех же документах. Записывайте не только успешный парсинг, но и дрейф названий полей, неверные типы, пропуски, придуманные значения и ошибки бизнес-валидации.

Шаг 7. Повторяйте тест после изменений

Проверка нужна после смены модели, API, версии схемы и промпта. Поддержка конкретных ключевых слов JSON Schema и гарантии Structured Output могут меняться, поэтому документацию необходимо пересматривать перед продуктивным обновлением.

Выбор формата по сценарию

Ниже — рабочая схема выбора по конечному потребителю. Она не заменяет документацию конкретного API: OpenAI, Gemini и Claude могут по-разному поддерживать отдельные элементы JSON Schema и разные режимы строгого вывода.

Если вы только прототипируете идею, начните с обычного JSON и валидатора. Если результат уже записывается в продуктивную базу, запускает действие или передаётся в другой автоматизированный узел, переходите к Structured Output до того, как ошибки формата начнут маскироваться под ошибки бизнес-логики.

При эксплуатации таких решений на удалённой среде заранее проверьте доступ к SDK, логированию, секретам и тестовым сервисам через центр поддержки kvmboot. Для временного стенда или проверки нескольких вариантов развёртывания также можно оценить доступные регионы аренды Mac, но сама аренда не заменяет проектирование схемы и тестирование API.

Если сравнивать текущий подход «промпт плюс ручной парсер» с отдельной средой Mac для разработки и проверок, у первого есть несколько реальных недостатков: ошибки часто обнаруживаются только после интеграции, локальные зависимости могут отличаться от CI-среды, а повторяемый тест нескольких моделей требует стабильного окружения и доступа к инструментам. Для краткосрочного проекта, миграции SDK или параллельной проверки Structured Output аренда Mac через kvmboot может оказаться удобнее покупки отдельного компьютера: вы получаете удалённую среду без длительной настройки, а после завершения тестов не остаётесь с простаивающим оборудованием. Для постоянной тяжёлой нагрузки или работы с физическими интерфейсами собственный Mac всё же может быть рациональнее; выбор зависит от длительности проекта, требований к доступу и режима эксплуатации.

Главное правило простое: человеку отдавайте естественное объяснение, слабосвязанным сервисам — обычный JSON, а данным для производства, инструментам и состояниям AI Agent — версионированную JSON Schema вместе с проверкой содержания, прав и фактического существования ресурсов.