JSON Mode

JSON Mode — режим API LLM, гарантирующий, что ответ будет **валидным JSON**, но без контроля конкретной схемы. Появился в OpenAI в 2023-м как первый шаг к структурированным ответам. Проще, чем Structured Output (не нужно описывать схему), но и слабее: модель может вернуть любой JSON, не обязательно с нужными полями. Часто шаг по дороге к более строгому контролю.

Коротко

Коротко. JSON Mode — режим OpenAI API, гарантирующий, что ответ будет валидным JSON: никаких комментариев до/после, всегда парсится через json.loads(). Но схему не контролирует — какие поля и типы в JSON, зависит только от промпта. Это «упрощённая» версия Structured Output. Полезен для quick prototypes, переходных решений; для прода обычно лучше переходить на Structured Output (с гарантией схемы).

Что это такое

Программист пишет скрипт для генерации идей постов в блог. Хочет получать список идей в JSON.

Без JSON Mode:

Сгенерируй 5 идей постов в JSON-формате.

Иногда GPT-3.5 возвращает:

Конечно! Вот 5 идей:
```json
{
  "ideas": [...]
}

Надеюсь, поможет!

Лишний текст до и после JSON. Парсер падает.

**С JSON Mode:**
```python
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Возвращай только JSON."},
        {"role": "user", "content": "Сгенерируй 5 идей постов..."}
    ]
)

Гарантировано: ответ — валидный JSON. Никакого лишнего текста. Можно сразу json.loads(response).

JSON Mode появился в OpenAI Dev Day 2023 как первая попытка дать разработчикам гарантию формата. К 2024-му появился более строгий Structured Output с контролем схемы. К 2026-му JSON Mode остался как «облегчённая» опция: проще, но менее надёжно.

Как это работает

Технически JSON Mode — это легковесный Structured Output:

1. Грамматика общего JSON. Модель сэмплирует только токены, ведущие к валидному JSON (любой структуры).
2. Никаких ограничений на поля. В отличие от Structured Output, JSON Mode не знает о вашей схеме. Поля и типы выбирает модель.
3. Защита от обрыва. Модель не выдаст начало JSON без закрытия — если генерация заканчивается, последний } всегда добавится.

В коде:

# OpenAI
response_format={"type": "json_object"}

# Анаlogy в Anthropic — нет прямого эквивалента,
# используют Tool Use или просто промпт «only JSON»

# Gemini
generation_config={"response_mime_type": "application/json"}

Сравнение с Structured Output:

	JSON Mode	Structured Output
Гарантия валидного JSON	✓	✓
Гарантия схемы	✗	✓
Нужно ли описывать структуру	Нет	Да
Поддержка моделей	GPT-3.5+, GPT-4	GPT-4o (08.2024+)
Сложность настройки	Минимальная	Средняя (схема)
Когда использовать	Прототип, исследование	Прод

Пример на практике

Дизайнер делает прототип AI-ассистента для генерации описаний к фотографиям. Сначала тестирует через JSON Mode — быстрая проверка идеи:

SYSTEM = """Ты — фотограф-копирайтер. Возвращай JSON с полями:
- caption: подпись (1 предложение)
- hashtags: 5–7 хэштегов
- mood: одно слово (атмосфера фото)
"""

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": SYSTEM},
        {"role": "user", "content": "Закат над морем, силуэт парусника"}
    ]
)
data = json.loads(resp.choices[0].message.content)
print(data["caption"])  # обычно работает

Работает. JSON всегда валидный. Иногда модель возвращает caption как description, иногда mood как atmosphere. Не критично для прототипа.

Когда продукт идёт в прод: переписывает на Structured Output с явной схемой через Pydantic. Никаких сюрпризов с именами полей.

В Anthropic Claude нет прямого аналога JSON Mode, но через Tool Use достигается тот же результат: определяете «инструмент» с любой input-схемой, модель должна его «вызвать».

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

• JSON Mode и Structured Output — JSON Mode гарантирует формат, не схему. Structured Output — и формат, и схему.
• JSON Mode и обычный промпт «верни JSON» — обычный промпт не гарантирует ничего. JSON Mode гарантирует валидность парсинга.
• JSON Mode и Function Calling — Function Calling это вызов функций с строгой схемой. JSON Mode — только формат ответа.
• JSON Mode и YAML/XML Mode — таких режимов в OpenAI нет, только JSON. Для других форматов — обычный промпт + парсинг.
• JSON Mode и Streaming — JSON Mode работает с streaming. SDK даёт partial-JSON по мере генерации.

Частые ошибки и заблуждения

• «JSON Mode гарантирует схему». Нет. Модель может вернуть {"random_field": "..."} вместо ожидаемого {"caption": "..."}. Только формат, не содержание.
• «JSON Mode работает без слова "JSON" в промпте». Не работает. OpenAI явно требует упоминание слова «JSON» в system или user сообщении.
• «JSON Mode медленнее обычной генерации». Незаметно. Накладные расходы на проверку грамматики JSON минимальны.
• «JSON Mode не нужен, если просить JSON в промпте». Нужен. Промпт даёт ~95% правильного формата. JSON Mode — 100%. Для production это важно.
• «JSON Mode — это устаревший Structured Output». Не устаревший. Это разные инструменты. JSON Mode проще для quick-tasks, SO — для строгих требований.

Связанные термины

• Structured Output — следующий шаг с гарантией схемы.
• Function Calling / Tool Calling — построены поверх схема-контроля.
• JSON Schema — стандарт описания структуры (используется в SO, не в JSON Mode).
• Pydantic — Python-инструмент для типизации.
• API — главное место применения JSON Mode.
• Streaming — JSON Mode совместим с потоковой генерацией.

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

В каких моделях работает JSON Mode? OpenAI: GPT-4 Turbo, GPT-4o, GPT-3.5 Turbo (с 1106). Gemini: 1.5+. Claude — нет прямого аналога, есть Tool Use.

Почему OpenAI требует слово «JSON» в промпте? Защита от случайного включения и сигнал модели, что вы действительно ждёте JSON. Без слова — ошибка валидации запроса.

Можно ли использовать с function calling? Можно одновременно. Function calling сам по себе уже даёт строгий JSON. JSON Mode — про формат финального ответа.

Что если модель не сможет уместить JSON в max_tokens? Модель закроет JSON последним }, даже если это означает обрыв содержания. Лучше задавать достаточный max_tokens.

JSON Mode дороже? Нет. Стоимость как у обычной генерации, токены считаются одинаково.

Что лучше: JSON Mode или Structured Output? Для production — Structured Output (гарантия схемы). Для прототипа или редкой задачи — JSON Mode проще (не нужно описывать схему).

Главное

JSON Mode — это «облегчённая версия» Structured Output: гарантирует, что ответ будет валидным JSON, но не контролирует, какие именно поля внутри. Полезен для прототипов и исследовательских задач, где важно быстро получить парсимый ответ. Для production-сценариев лучше переходить на Structured Output с явной схемой через Pydantic. Главное условие: слово «JSON» должно быть в промпте, иначе OpenAI вернёт ошибку. К 2026-му JSON Mode часто используется как промежуточный шаг — пока не определился с финальной схемой, потом переход на SO. Не путать с обычным промптом «верни JSON»: JSON Mode даёт гарантию формата, обычный промпт — просьбу.