Перейти к содержимому
TokIQ
Вывод

Надёжный JSON от LLM: схемы, валидация, повторные запросы

Чтобы LLM вернула корректный JSON, одной вежливой просьбы мало. Схемы, режимы структурированного вывода, валидация, повторы и типичные сбои.

TokIQ Editorial5 мин чтения
В этой статье
  1. Почему модели вообще ломают JSON?
  2. Шаг 1: точно опишите вывод в промпте
  3. Шаг 2: используйте функцию структурированного вывода в API
  4. Шаг 3: проверяйте всё, даже при принудительной схеме
  5. Шаг 4: повторяйте запрос с ошибкой, а не вслепую
  6. Куда поместить рассуждение в JSON-ответе?
  7. Типичные ошибки при проектировании схем вывода
  8. Хватит ли одного промпта?

Чтобы получить надёжный JSON от языковой модели, опишите структуру как JSON Schema, используйте у поставщика функцию структурированного вывода, если она есть, проверяйте каждый ответ в коде и при ошибке повторяйте запрос, передавая текст ошибки. Формулировка промпта довозит вас большую часть пути; последние проценты надёжности дают API и ваша собственная проверка.

Разница важна, потому что «большая часть пути» для кода - это мало. Если парсер падает на 2% ответов, то при большой нагрузке у кого-то каждые несколько минут ломается функция.

Почему модели вообще ломают JSON?

Прежде чем чинить, полезно понять, что именно идёт не так. Примерно в том порядке, в каком вы с этим столкнётесь:

  1. Ограждение markdown. Модель возвращает ```json ... ```, потому что чат-модели приучены красиво показывать код.
  2. Болтливые вступления. «Конечно! Вот запрошенный JSON:» и только потом объект.
  3. Неверные или выдуманные ключи. customerName вместо customer_name или лишнее поле notes, которого вы не просили.
  4. Неверные типы. "price": "19.99" строкой, "count": "three", один объект там, где нужен массив.
  5. Обрыв. Ответ упирается в лимит токенов и обрывается посреди объекта.
  6. Синтаксически верная чепуха. Идеальный JSON, неверное содержание: дата не в том формате, выдуманный номер телефона, null там, где значение прямо во входных данных.

Функции структурированного вывода в основном устраняют первые пять. Шестую не устраняет ничего, кроме хорошего промпта, опоры на источники и проверок.

Шаг 1: точно опишите вывод в промпте

Даже когда схема соблюдается принудительно, именно в промпте вы объясняете, что означает каждое поле. Схема скажет, что due_date - строка; только промпт может сказать, что это должна быть дата в формате ISO 8601 и что относительные даты нужно считать от даты отправки письма.

Слабый промпт:

Извлеки данные счёта из этого письма в виде JSON.

Промпт посильнее:

Извлеки данные счёта из письма ниже.

Верни один JSON-объект ровно с такими ключами:
- "vendor": строка, компания, выставившая счёт
- "invoice_number": строка, как написано (сохрани ведущие нули)
- "total": число, в валюте счёта, без знака валюты
- "currency": строка, код ISO 4217, например "USD" или "EUR"
- "due_date": строка в формате YYYY-MM-DD или null, если не указана

Если значения в письме нет, поставь null. Не угадывай.
Верни только JSON-объект, без markdown и без пояснений.

<email>
{{email_text}}
</email>

Здесь большую роль играют две детали. «Сохрани ведущие нули» не даст модели «из лучших побуждений» превратить 00417 в 417. А «поставь null, не угадывай» даёт модели законный выход. Без явной возможности написать null модель, которой нужно заполнить обязательное поле, придумает правдоподобное значение, а не оставит его пустым.

Шаг 2: используйте функцию структурированного вывода в API

Большинство крупных поставщиков теперь предлагают тот или иной способ ограничить вывод схемой. Названия и подробности различаются и со временем меняются, поэтому сверяйтесь с актуальной документацией, но основные варианты выглядят так:

  • OpenAI предлагает простой JSON mode, который гарантирует синтаксически корректный JSON, и Structured Outputs: вы передаёте JSON Schema со строгим режимом (strict), и вывод ограничивается так, чтобы ей соответствовать.
  • Google Gemini позволяет задать для ответа MIME-тип JSON и передать схему ответа.
  • Anthropic позволяет описать инструмент (tool) со схемой входных данных и заставить Claude его вызвать, что даёт аргументы в форме схемы; в документации также описана встроенная поддержка структурированного вывода.

Важное различие - JSON mode и принудительная схема. JSON mode лишь обещает, что текст разбирается парсером. Ключи при этом могут оказаться любыми. Принудительная схема (часто через constrained decoding, то есть ограничение того, какие токены модель вправе сгенерировать дальше) обещает форму.

Схема для примера со счётом:

{
  "type": "object",
  "properties": {
    "vendor": { "type": ["string", "null"] },
    "invoice_number": { "type": ["string", "null"] },
    "total": { "type": ["number", "null"] },
    "currency": { "type": ["string", "null"], "enum": ["USD", "EUR", "GBP", null] },
    "due_date": { "type": ["string", "null"], "description": "YYYY-MM-DD" }
  },
  "required": ["vendor", "invoice_number", "total", "currency", "due_date"],
  "additionalProperties": false
}

Обратите внимание на типы, допускающие null. В строгих режимах обычно все поля обязательны, поэтому «необязательное» приходится выражать как «обязательное, но может быть null». Также заметьте additionalProperties: false: он не пускает неожиданные поля. Строгие режимы обычно поддерживают лишь подмножество JSON Schema, поэтому прежде чем строить что-то сложное, проверьте, какие ключевые слова разрешены.

Если вы пишете на Python или TypeScript, опишите схему как модель Pydantic или схему Zod и получайте из неё JSON Schema. Тогда то же определение проверяет ответ, и они не разойдутся.

Шаг 3: проверяйте всё, даже при принудительной схеме

Принудительная схема гарантирует структуру. Она не гарантирует, что:

  • due_date - реальная дата (30 февраля - допустимая строка),
  • total совпадает с суммой позиций,
  • vendor вообще встречается в исходном письме,
  • модель не потеряла третью позицию из пяти.

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

Шаг 4: повторяйте запрос с ошибкой, а не вслепую

Когда проверка не прошла, не отправляйте тот же запрос снова в надежде на лучшее. Отправьте обратно ошибку:

Твой предыдущий ответ не прошёл проверку:
- "due_date": "3 марта" не соответствует формату YYYY-MM-DD
- "currency": "dollars" не входит в USD, EUR, GBP

Верни только исправленный JSON-объект.

Конкретные, названные ошибки модели исправляют хорошо. Ограничьте число повторов одним-двумя, журналируйте каждый сбой и раз в неделю просматривайте логи. Повторяющиеся сбои на одном и том же поле обычно значат, что промпт или схема неясны, а не что модель «капризничает». Такие библиотеки, как Instructor (Python), оборачивают этот цикл «проверить и повторить» за вас, но схема достаточно проста, чтобы написать её самостоятельно.

Если у поставщика нет принудительной схемы и ломается только синтаксис, большинство типичных случаев решает снисходительный парсер, который перед JSON.parse убирает обрамление и лишний текст. Считайте это запасным вариантом, а не стратегией.

Куда поместить рассуждение в JSON-ответе?

Если задача требует суждения (классификация с обоснованием, оценка риска), поставьте поле с рассуждением перед полем с решением:

{
  "evidence": "Клиент упоминает двойное списание по мартовскому счёту.",
  "category": "billing",
  "confidence": "high"
}

Модели генерируют поля по порядку. Решение, записанное первым, потом обосновывается, а не опирается на рассуждение. Подробнее об этом - в статье chain-of-thought: что это.

Обратная сторона: поля с рассуждением расходуют токены при каждом вызове. Для простого извлечения данных их лучше не добавлять.

Типичные ошибки при проектировании схем вывода

Глубокая вложенность без причины. Три уровня объектов там, где хватило бы плоского списка. Каждый уровень - ещё одно место, где модель может положить значение не туда.

Свободный текст там, где нужен enum. Если код ниже по цепочке ветвится по status, сделайте его enum. Иначе для одного и того же состояния придут «Pending», «pending», «In progress» и «awaiting review».

Неоднозначные названия полей. date у счёта может быть датой выставления, сроком оплаты или датой платежа. Назовите поле due_date и опишите его.

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

Забыли про пустой случай. Каким должен быть вывод, если письмо вообще не счёт? Добавьте булево поле is_invoice или разрешите пустой результат, иначе модель найдёт счёт в приглашении на обед.

Хватит ли одного промпта?

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

Лежащий в основе навык один и тот же: описать вывод так точно, чтобы заполнить его можно было только одним разумным способом. Эти решения отрабатывает тема «структурированный вывод», а если JSON, который вы создаёте, - вызов инструмента, а не итоговый ответ, то продолжение - в статье про вызов инструментов и ИИ-агентов. Об извлечении, опирающемся на исходные документы, читайте в статье что такое RAG.

Частые вопросы

Как заставить LLM вернуть валидный JSON?

Используйте функцию структурированного вывода у поставщика вместе с JSON Schema, если она есть: она ограничивает генерацию схемой. После этого всё равно проверяйте результат в коде и делайте повторный запрос или исправление, если проверка не прошла.

Чем JSON mode отличается от structured outputs?

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

Почему LLM оборачивает JSON в блоки кода markdown?

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

Нужно ли проверять JSON от LLM, даже если есть схема?

Да. Схема гарантирует форму, но не правдивость. JSON может быть абсолютно валидным и при этом содержать неверную дату, выдуманное значение или пустое поле там, где данные были.

  • #структурированный вывод
  • #JSON
  • #JSON schema
  • #валидация

Теперь потренируйтесь

TokIQ превращает промпт-инжиниринг в короткие тесты с объяснением каждого ответа.

Скоро вApp StoreДоступно вGoogle Play
Обучение4 мин чтения

Как подготовиться к AWS MLA-C02: план для ML Engineer

План подготовки к MLA-C02: часы в неделю, четыре домена и их веса, темы GenAI, новые со времён MLA-C01, бесплатные материалы AWS и что делать с бета-версией.

Пишите промпты лучше, по нескольку вопросов в день.

Короткие тесты о реальных решениях при составлении промптов, с объяснением к каждому ответу. Начать можно бесплатно на iPhone и Android.

Скоро вApp StoreДоступно вGoogle Play