Structured output в LLM: валидный JSON, схема и проверка смысла

Как получать структурированный вывод от LLM без хрупкого парсинга. Разбираем JSON Schema, отказы, усечение, проверку бизнес-правил и локальный пример на Python.

11 мин чтенияai · json · llm · python

Коротко

Структурированный вывод (structured output) — ответ модели в формате, который приложение заранее описало схемой. Используйте его для полей формы, решений классификатора и других значений, которые дальше читает код. Схема помогает получить нужные поля, а приложение проверяет, закончен ли ответ и верны ли значения для конкретного обращения.

  • JSON-парсер подтверждает синтаксис. Схема ограничивает типы, поля и допустимые значения.
  • Храните отказ и незавершённый ответ как отдельные исходы. Не пытайтесь получить результат из обрезанного потока.
  • Проверяйте связь с данными запроса, даже если провайдер обещает соответствие поддерживаемой схеме.
  • Преобразуйте проверенный результат во внутренний тип и только после этого показывайте действие пользователю.

Что извлекаем из обращения

Сотрудник получает сообщение «Заказ 42 пришёл с треснувшим экраном». Приложение должно предложить черновик заявки на дефект. Для нашего сценария нужны номер, категория, приоритет и короткое основание. Поля придут из модели, а исходный номер доверенная часть интерфейса уже получила из карточки заказа. Если в результате появится заказ 43, JSON может быть совершенно валидным и всё равно относиться к чужой записи.

ПолеДопустимые данныеЧто проверяет приложение
order_idПоложительное целое числоСовпадает с открытой карточкой и доступно человеку
categorydamage или otherПрименимо к данному тексту
prioritynormal или highСогласуется с правилами службы поддержки
reasonКороткая строкаЕсть опора в обращении, текст безопасно показать

Зафиксируйте границу. Модель предлагает черновик, а сотрудник подтверждает создание. Если фраза сообщает повреждение без номера, интерфейс использует карточку либо просит уточнение. Значение «0» в поле номера не годится для обозначения неизвестности. Если нужны неизвестные значения, опишите отдельный допустимый исход, например «нужно уточнение», и обрабатывайте его явно. Это помогает и фронтенду, и журналу результата.

Три проверки вместо одного парсера

Первая проверка — синтаксис. {"order_id": 42} читается как JSON, а объект с оборванной фигурной скобкой нет. Синтаксис ничего не говорит об обязательных полях. Вторая проверка — соответствие форме. Спецификация JSON Schema Validation задаёт ограничения вроде type, enum и требований к полям. Если схема допускает только normal и high, результат urgent не пройдёт проверку. Третья — смысл. Даже допустимый high требует подтверждения по правилам команды.

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

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

ШагКто → комуЧто передаёт
1. ЗапросПриложение → адаптер моделиСообщение, контекст карточки и версия схемы
2. РезультатАдаптер → валидаторГотовый JSON либо отдельный отказ или незавершённость
3. ФормаВалидатор → правила приложенияТипизированные поля при успешной проверке
4. СмыслПравила → интерфейсЧерновик либо конкретная причина отклонения
5. ЗаписьСотрудник → сервис заявокПодтверждённые данные, право и ключ операции

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

Минимальная проверка на Python

Функция получает статус от адаптера и сырое тело. Она не реализует весь JSON Schema, а проверяет небольшой фиксированный контракт приложения. Номер в примере берётся из активной карточки, а отдельный флаг приоритета определяется серверной политикой. Выход на ошибке содержит код для интерфейса, чтобы он мог выбрать правильное действие.

import json def parse_draft(status, raw, active_order, high_allowed): if status != "complete": return status try: draft = json.loads(raw) except json.JSONDecodeError: return "invalid_json" fields = {"order_id", "category", "priority", "reason"} if not isinstance(draft, dict) or set(draft) != fields: return "invalid_fields" if type(draft["order_id"]) is not int or draft["order_id"] < 1: return "invalid_order_id" if draft["category"] not in ("damage", "other"): return "invalid_category" if draft["priority"] not in ("normal", "high"): return "invalid_priority" reason = draft["reason"] if not isinstance(reason, str) or not 1 <= len(reason.strip()) <= 160: return "invalid_reason" if draft["order_id"] != active_order: return "wrong_order" if draft["priority"] == "high" and not high_allowed: return "priority_requires_review" return "draft_ready" base = { "order_id": 42, "category": "damage", "priority": "normal", "reason": "Треснувший экран", } cases = [ ("Обычный черновик", "complete", json.dumps(base)), ("Другой номер", "complete", json.dumps(dict(base, order_id=43))), ("Запрошен высокий приоритет", "complete", json.dumps(dict(base, priority="high"))), ("Неизвестное значение", "complete", json.dumps(dict(base, priority="urgent"))), ("Оборванный ответ", "incomplete", '{"order_id":'), ("Синтаксическая ошибка", "complete", '{"order_id":'), ("Отказ", "refusal", ""), ] for label, status, raw in cases: print(label, "→", parse_draft(status, raw, 42, False)) assert parse_draft("complete", json.dumps(dict(base, order_id=True)), 42, False) == "invalid_order_id"

Вывод программы.

Обычный черновик → draft_ready Другой номер → wrong_order Запрошен высокий приоритет → priority_requires_review Неизвестное значение → invalid_priority Оборванный ответ → incomplete Синтаксическая ошибка → invalid_json Отказ → refusal

Результаты wrong_order и priority_requires_review проходят проверку формы и отклоняются позже. Это разные классы ошибок. Для incomplete сначала выясните, почему оборвался ответ. При сетевом отказе допустим ограниченный повтор всей операции получения черновика. Для refusal не используйте код, который превращает отказ в пустой успешный объект. Если интерфейс нужен для ручной маршрутизации, покажите форму с заполненными достоверными полями и объясните, какие остались пустыми.

У текста основания есть предел длины, но код не доказывает, что строка подтверждается сообщением. Если это критично, попросите извлечь дословную выдержку и проверьте, что она есть во входе. Для пересказа проверьте соответствие вручную на эталонном наборе. Не выдавайте объяснение как фактическую причину из карточки, если его сгенерировала модель. Поле может оставаться полезной подсказкой рядом с исходным сообщением.

Как обрабатывать поток и сбои

В потоковом режиме JSON может приходить по частям. Обновляйте индикатор ожидания, но не применяйте значение поля, пока ответ не завершён и не прошёл проверки. Если сервер отправил priority, а окончание reason не пришло, заявка остаётся черновиком без подтверждения. Проверьте это тестом, который рвёт ответ на середине строки. Последний прочитанный байт и финальное событие — разные признаки.

Если исчерпан лимит вывода, сначала проверьте размер схемы и полей. Возможно, вы запросили десять длинных объяснений, хотя интерфейс показывает одно основание. Уменьшите объём, выделите этап резюме отдельно либо испытайте больший лимит на наборе. Для временной недоступности используйте ограниченный повтор с общим дедлайном, как в разборе повторов. Не повторяйте создание уже подтверждённой заявки как часть восстановления черновика.

Измеряйте четыре показателя раздельно: неполные ответы, отклонения формы, отклонения правил и исправления сотрудником. Для проблемного заказа 42 первый показатель не изменится, если модель начала подставлять номер 43. Третий вырастет сразу. Сохраняйте версию схемы, стадии и безопасные коды причин. В обычный лог не нужен полный текст обращения. Для тестов достаточно примеров без реальных данных и идентификатора сценария.

Как выбирать форму ответа для интерфейса

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

Проверьте совместимость с бизнес-правилами на нескольких входах. Категория damage с текстом «коробка помята, экран работает» может быть допустимым черновиком, если сервис принимает жалобы на упаковку. Если damage у вас включает только повреждение товара, модель должна предложить другое значение или уточнение. Внесите это различие в описание и эталон. Не добавляйте сложное правило в схему, если оно требует чтения сообщения и обращения к данным заказа. В интерфейсе отдельно показывайте предложенный приоритет и подтверждённый приоритет.

Проверьте лимиты там, где приложение читает результат, даже если пользователь видит только короткую форму. Причина на 5 000 символов может раздуть очередь или привести к обрезке в базе. Ограничьте размер тела и длину полей по договору. Для ответов из собственного HTTP-адаптера проверьте, как декодер обрабатывает повтор ключа: объект с двумя номерами заказа нельзя безопасно интерпретировать по случайно выбранному значению. Учебный код выше предполагает канонический JSON от адаптера; для произвольного внешнего тела нужен отдельный контроль разбора.

Что проверять при смене модели

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

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

Как менять контракт

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

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

Когда можно обойтись без модели

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

Типичные ошибки

  1. Парсите текст вместо контракта. Лишняя фраза ломает интерфейс. Проверьте сценарий с Markdown и используйте поддерживаемую схему вывода.
  2. Принимаете чужой номер. Форма правильная, но черновик относится к заказу 43. Сверьте с доверенной карточкой и указанными правами.
  3. Считаете усечение отказом модели. Приложение показывает одинаковое сообщение для разных причин. Запишите статус ответа адаптера и воспроизведите обрыв по лимиту отдельно.
  4. Выпускаете схему без миграции. Старый запрос завершился, а новое приложение не знает значение поля. Протестируйте один отклик, который пришёл после переключения версии.
  5. Приравниваете валидность к качеству. Объект прошёл проверку, а сотрудник меняет категорию вручную. Измерьте долю таких исправлений и разберите их по типам обращения.

Что спрашивают на собеседовании

Проведите заказ 42 через все стадии и назовите код результата на каждой ошибке.

  1. Чем JSON mode отличается от вывода по схеме? JSON задаёт читаемый синтаксис, а схема требует нужных полей и типов. Я всё равно проверю, что номер относится к активной карточке.
  2. Как обработать отказ или обрыв? Я сохраню отдельный статус от адаптера и не передам частичный JSON в интерфейс как готовый результат. Для обрыва проверю причину и лимит перед повтором.
  3. Что проверять после схемы? Я сверю значения с правами и правилами приложения. Например, высокий приоритет должен подходить под текущую политику.
  4. Как менять структуру? Я версионирую схему и преобразование результата во внутренний тип. Проверю старый ответ, который пришёл после обновления клиента.
  5. Когда использовать tool calling? Когда модели нужно запросить действие у приложения, например чтение статуса. Для предложения полей черновика достаточно вывода по схеме.

Потренироваться в спокойной обстановке

Все задачи