BroadRouter
Начать

JSON mode или json_schema: надёжный структурированный вывод LLM

Команда BroadNet Inference · 4 мин чтения · Опубликовано

JSON mode (response_format json_object) гарантирует только валидный JSON. Структурированный вывод (response_format json_schema) гарантирует ещё и ваши поля и типы — там, где провайдер это обеспечивает. В обоих случаях проверяйте finish_reason, разбирайте ответ и валидируйте его по схеме, например модели Pydantic. Если валидация не прошла, отправьте ошибку обратно и запросите ответ снова, со строгим лимитом попыток.

Вашему коду нужны данные, а модели пишут текст. Структурированный вывод закрывает этот разрыв, но «модель возвращает JSON» означает три разные вещи в зависимости от того, как вы просите. В этой статье мы сравниваем варианты на OpenAI-совместимых открытых моделях, показываем, как запросить каждый, и даём цикл валидации и исправления, который можно сразу взять в продакшен.

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

Способ Запрос Что гарантируется
Только промпт «Ответь в JSON с полями…» Ничего; обычно JSON, иногда с лишним текстом
JSON mode response_format: {"type": "json_object"} Валидный JSON любой структуры
Структурированный вывод response_format: {"type": "json_schema", ...} JSON по вашей схеме, если это обеспечивается

Руководство OpenAI по Structured Outputs говорит прямо: “While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence.” (перевод: «Хотя оба режима гарантируют валидный JSON, соответствие схеме гарантирует только Structured Outputs».) OpenAI рекомендует по возможности использовать структурированный вывод вместо JSON mode.

У провайдеров открытых моделей гарантия зависит от того, как это реализовано на сервере. Многие используют ограниченное декодирование (constrained decoding), которое блокирует токены, нарушающие схему. Некоторые принимают поле, но не обеспечивают его соблюдение. Поэтому код ниже валидирует ответ в любом случае.

Как запросить json_schema?

import os
from openai import OpenAI
from pydantic import BaseModel, Field

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Invoice(BaseModel):
    vendor: str
    currency: str = Field(pattern="^[A-Z]{3}$")
    total: float
    line_items: list[float]

schema = Invoice.model_json_schema()
schema["additionalProperties"] = False

response_format = {"type": "json_schema",
                   "json_schema": {"name": "invoice", "strict": True, "schema": schema}}

Pydantic генерирует JSON Schema из вашего класса, поэтому схема и валидатор никогда не расходятся. Если вы не пользуетесь Pydantic, генератор JSON Schema построит схему для строгого режима по образцу объекта. Для строгого режима OpenAI требует additionalProperties: false и чтобы каждое свойство было указано как обязательное.

Какой режим поддерживает ваш провайдер?

Прежде чем строить на модели что-то серьёзное, один раз прогоните этот тест:

  1. Отправьте json_schema с промптом, который провоцирует добавить лишнее поле («добавь ещё короткий комментарий»).
  2. Если запрос возвращает ошибку, провайдер не принимает json_schema. Попробуйте json_object.
  3. Если в ответе есть лишнее поле, схема не соблюдается принудительно. Считайте, что это JSON mode.
  4. Если json_object тоже даёт ошибку, используйте инструкцию в промпте плюс валидацию.

В документации BroadNet Inference структурированный вывод указан для GLM 5.3 и Qwen3.8 27B (сравнение бок о бок), но параметр запроса не назван. Прогоните тест выше на модели, которую выпускаете в продакшен.

Как валидировать и исправлять плохой ответ?

import json
from pydantic import ValidationError

def extract(text: str, model="broadnet/glm-5.3", attempts=3) -> Invoice:
    messages = [
        {"role": "system", "content": "Extract the invoice. Reply with JSON only."},
        {"role": "user", "content": text},
    ]
    for attempt in range(attempts):
        r = client.chat.completions.create(model=model, messages=messages,
                                           response_format=response_format,
                                           max_tokens=4000)
        choice = r.choices[0]
        if choice.finish_reason == "length":
            raise RuntimeError("Cut off: raise max_tokens")  # retrying won't help
        if getattr(choice.message, "refusal", None):
            raise RuntimeError(f"Refused: {choice.message.refusal}")
        raw = choice.message.content or ""
        try:
            inv = Invoice.model_validate_json(raw)
            if abs(sum(inv.line_items) - inv.total) > 0.01:
                raise ValueError("total must equal the sum of line_items")
            return inv
        except (ValidationError, ValueError) as e:
            messages += [
                {"role": "assistant", "content": raw},
                {"role": "user", "content": f"That JSON is invalid: {e}. Return corrected JSON only."},
            ]
    raise RuntimeError(f"No valid JSON after {attempts} attempts")

Почему этот цикл работает:

  • Сначала проверяйте finish_reason. Ответ, который упёрся в max_tokens, — это обрезанный JSON. Повтор с тем же лимитом упадёт так же. Обе модели выше рассуждают перед ответом, а рассуждения засчитываются в лимит, так что оставляйте запас.
  • Обрабатывайте отказы отдельно. Руководство OpenAI отмечает, что отказ “does not necessarily follow the schema you have supplied” (перевод: «не обязательно соответствует заданной вами схеме»).
  • Отправляйте обратно точную ошибку. Слепой повтор часто возвращает ту же ошибку. Сообщение “line_items: field required” даёт модели конкретное, что исправить.
  • Проверяйте бизнес-правила в коде. Схема не может выразить, что итог должен равняться сумме позиций. Проверка выше — может.
  • Ограничивайте число попыток. Каждая попытка заново отправляет весь промпт как входные токены.

Какие возможности схемы создают проблемы?

Делайте схемы скучными:

  1. Плоское лучше вложенного. Для большинства задач извлечения хватает двух уровней.
  2. Enum вместо свободных строк для категорий.
  3. Никаких объектов с произвольными ключами. Поля свободной формы типа dict сводят смысл на нет.
  4. Короткие имена полей с описаниями. Описания в схеме направляют модель.
  5. Необязательные поля — как nullable. В строгом режиме указывайте каждое поле как обязательное и разрешайте null.

Руководство OpenAI отмечает, что некоторые возможности JSON Schema в строгом режиме не поддерживаются. У серверов открытых моделей свои ограничения. Если схему отклоняют, упростите её, прежде чем менять режим.

Как мониторить структурированный вывод в продакшене?

Цикл, который молча исправляет ответы, может скрывать проблему, которая каждый день стоит вам токенов. Логируйте три числа для каждого места вызова:

Метрика Что она показывает
Доля успеха с первой попытки Насколько хорошо сочетаются модель и схема; падение часто следует за сменой промпта или модели
Среднее число попыток на успех Стоимость исправлений в токенах
Окончательные неудачи Входные данные, с которыми ваш конвейер не справляется; разберите их вручную

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

Когда лучше использовать инструмент?

Используйте структурированный вывод для итогового ответа: извлечения, классификации, плана. Используйте вызов инструментов, когда модели нужно, чтобы ваш код что-то сделал, а она продолжила работу. Многие агенты используют и то и другое: инструменты внутри цикла, схему на последнем шаге. Пример «изображение → JSON» — в руководстве распознавание арабских счетов vision-моделью.

Какое место здесь занимает BroadNet Inference

BroadNet Inference указывает структурированный вывод для GLM 5.3 и Qwen3.8 27B в стандартном формате chat completions, поэтому код выше работает с OpenAI Python SDK без изменений. Qwen3.8 27B принимает и изображения, что удобно для извлечения данных из документов. Для DeepSeek V4.1 Flash и Gemma 4 VL 26B документация BroadNet структурированный вывод не указывает, поэтому там используйте инструкцию в промпте с валидацией. Цены за токены сравните на странице цен.

Вопросы и ответы

Чем JSON mode отличается от структурированного вывода?

JSON mode (response_format с типом json_object) гарантирует только то, что ответ разбирается как JSON. Структурированный вывод (тип json_schema) гарантирует ещё и заданные вами поля и типы — там, где провайдер это обеспечивает. OpenAI рекомендует по возможности использовать структурированный вывод, а не JSON mode.

Поддерживают ли открытые модели response_format json_schema?

Зависит от провайдера. Одни принимают json_schema, другие только json_object, третьи игнорируют это поле. Отправьте тестовый запрос со схемой и промптом, который провоцирует модель добавить лишнее поле, и проверьте ответ.

Нужно ли валидировать структурированный вывод?

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

Сколько раз повторять запрос при невалидном JSON?

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

Что использовать — структурированный вывод или вызов инструментов?

Структурированный вывод — когда итоговый ответ нужен в фиксированной форме. Вызов инструментов — когда модели нужно, чтобы ваш код что-то сделал, после чего она продолжит работу.

Открыть в MarkdownСпросить ChatGPTСпросить ClaudeСпросить Perplexity