Гайд · TNWS AI
Как получить Structured Outputs в OpenAI API по JSON Schema
Как заставить модель вернуть данные по JSON Schema, проверить обязательные поля и корректно обработать отказ или неполный ответ.
Зачем нужна строгая схема
Если ответ передаётся в интерфейс, базу данных или следующий процесс, свободный текст неудобен. Structured Outputs позволяет описать ожидаемые поля через JSON Schema и снизить число ошибок парсинга.
Как настроить
- Опишите минимальную JSON Schema: тип объекта, свойства и обязательные поля.
- Запретите лишние свойства, если они не нужны приложению.
- Передайте схему в поддерживаемом формате ответа или определении инструмента.
- Получите результат и всё равно проверьте его валидатором на сервере.
- Отдельно обработайте отказ, обрыв ответа и сетевую ошибку.
Пример структуры
Для карточки статьи достаточно полей title, summary и tags. Не просите модель возвращать двадцать вложенных объектов, если бизнес-задача использует только три значения.
Как проверять
Добавьте тесты на пустые строки, неожиданный язык, слишком длинный заголовок и отсутствие данных в исходнике. Схема проверяет форму, но не истинность факта.
Чего не делать
Не вставляйте результат в SQL или HTML без дополнительной безопасной обработки и не считайте валидный JSON достоверным ответом.
Официальный источник
OpenAI Platform Documentation: https://platform.openai.com/docs/guides/structured-outputs
Частые вопросы
Это просто просьба вернуть JSON?
Нет, Structured Outputs связывает ответ с заданной схемой, но приложение всё равно должно валидировать результат.
Что делать при отказе модели?
Обработать отказ как отдельный ожидаемый результат, а не пытаться парсить его как бизнес-объект.
Что проверить перед продакшеном?
Схему ответа, обработку ошибок, лимиты, стоимость на тестовом объёме и отсутствие секретов в клиентском коде.
Читайте также
Как использовать OpenAI Batch API для больших пачек запросов
Пошаговый гайд по Batch API: подготовка JSONL, уникальные идентификаторы, проверка статуса и сопоставление результатов без путаницы.
Как использовать OpenAI Moderation API для проверки пользовательского контента
Как встроить модерацию текста и изображений: проверка входа и выхода, пороги продукта, ручная эскалация и журнал решений.
Как использовать OpenAI Responses API: первый запрос и структура ответа
Пошаговый старт с Responses API: серверный ключ, входные сообщения, чтение результата, обработка ошибок и безопасный запуск.
Комментарии
Пока тихо. Скажите первое слово