JSON Mode

JSON Mode ограничивает ответ языковой модели синтаксисом JSON. Это удобнее обычной просьбы «верни JSON», но режим не задаёт обязательные поля, типы и смысл значений. Приложение всё равно проверяет завершение ответа, разбирает JSON, валидирует данные и обрабатывает отказ или сетевую ошибку.

Коротко

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

Зачем нужен отдельный режим

Обычная языковая модель генерирует текст. Даже после просьбы «ответь только JSON» она иногда добавляет пояснение, Markdown-кодовый блок или синтаксическую ошибку.

JSON Mode ограничивает допустимый вывод и делает машинный разбор стабильнее. Но JSON как формат очень свободен. Все варианты ниже синтаксически корректны:

{"priority": 3}

{"priority": "high"}

[]

Если приложение ждёт integer и обязательное поле priority, одной валидности JSON недостаточно.

Что режим контролирует

JSON Mode обычно помогает с такими вещами:

• кавычками и скобками;
• отсутствием текста вокруг объекта;
• корректным экранированием строк;
• форматом, который принимает стандартный JSON-parser.

Он не проверяет:

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

Точная семантика режима зависит от API, поэтому его ограничения сверяют с документацией провайдера.

Надёжный цикл обработки

запрос к модели
      ↓
проверка статуса завершения
      ↓
JSON.parse / json.loads
      ↓
валидация полей и типов
      ↓
проверка бизнес-правил
      ↓
использование или контролируемый повтор

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

Пример проверки

import json

def parse_priority(raw: str) -> dict:
    data = json.loads(raw)

    if not isinstance(data, dict):
        raise ValueError("ожидался JSON object")

    if data.get("priority") not in {"low", "medium", "high"}:
        raise ValueError("неизвестный priority")

    if not isinstance(data.get("summary"), str):
        raise ValueError("summary должен быть строкой")

    return data

Даже такой код проверяет только форму. Если summary содержит выдуманный факт, JSON-parser этого не заметит.

JSON Mode и Structured Output

Свойство	JSON Mode	Structured Output
Синтаксис JSON	Ограничивается режимом	Ограничивается режимом
Заданная схема	Нет	Да
Обязательные поля и типы	Проверяет приложение	Часть требований задаёт схема
Истинность значений	Не гарантируется	Не гарантируется
Обработка обрыва и отказа	Нужна	Нужна

Structured Output удобнее для стабильного контракта. JSON Mode остаётся полезен, когда структура простая, гибкая или заранее неизвестна.

Когда JSON Mode уместен

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

Если JSON напрямую запускает оплату, удаление, выдачу прав или другую опасную операцию, одной синтаксической валидности мало. Нужны строгая схема, allowlist действий и отдельная авторизация.

Как формулировать запрос

В промпте полезно явно назвать:

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

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

Частые ошибки

• Считать валидный JSON правильным ответом. Синтаксис не подтверждает смысл.
• Не проверять finish status. Оборванный или отклонённый запрос требует отдельной обработки.
• Доверять типам из промпта. Без схемы модель может вернуть другой тип.
• Повторять запрос бесконечно. Нужны предел повторов и понятная ошибка.
• Выполнять имя инструмента из ответа без allowlist. Строка модели не является разрешением.
• Сохранять сырой ответ как проверенные данные. Сначала parser, затем schema и бизнес-валидация.

С чем часто путают

• JSON в Markdown — обычный текстовый ответ с кодовым блоком.
• JSON Mode — ограничение синтаксиса без контракта полей.
• Structured Output — генерация по поддерживаемой схеме.
• Function Calling — запрос на вызов инструмента с аргументами; платформа может применять схему к ним отдельно.
• JSON Schema — язык описания структуры, который можно использовать и вне LLM.

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

Можно ли обойтись одной просьбой «ответь JSON»? Иногда да, но это менее надёжно. Режим нужен именно для машинного pipeline, где лишняя строка или незакрытая скобка превращается в ошибку.

Нужно ли всё равно вызывать JSON-parser? Да. Ответ приходит как набор байтов или строка, и приложение должно превратить его в структуру данных.

Что делать, если поле отсутствует? Не придумывать его молча. В зависимости от задачи можно вернуть контролируемую ошибку, запросить повтор или использовать явно заданное значение по умолчанию.

JSON Mode защищает от prompt injection? Нет. Вредоносный текст может оказаться внутри корректного поля. Доверие к содержимому и полномочия инструмента контролируются отдельно.

Главное

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