Вашему коду нужны данные, а модели пишут текст. Структурированный вывод закрывает этот разрыв, но «модель возвращает 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 и чтобы каждое свойство было указано как обязательное.
Какой режим поддерживает ваш провайдер?
Прежде чем строить на модели что-то серьёзное, один раз прогоните этот тест:
- Отправьте
json_schemaс промптом, который провоцирует добавить лишнее поле («добавь ещё короткий комментарий»). - Если запрос возвращает ошибку, провайдер не принимает
json_schema. Попробуйтеjson_object. - Если в ответе есть лишнее поле, схема не соблюдается принудительно. Считайте, что это JSON mode.
- Если
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” даёт модели конкретное, что исправить.
- Проверяйте бизнес-правила в коде. Схема не может выразить, что итог должен равняться сумме позиций. Проверка выше — может.
- Ограничивайте число попыток. Каждая попытка заново отправляет весь промпт как входные токены.
Какие возможности схемы создают проблемы?
Делайте схемы скучными:
- Плоское лучше вложенного. Для большинства задач извлечения хватает двух уровней.
- Enum вместо свободных строк для категорий.
- Никаких объектов с произвольными ключами. Поля свободной формы типа
dictсводят смысл на нет. - Короткие имена полей с описаниями. Описания в схеме направляют модель.
- Необязательные поля — как 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 структурированный вывод не указывает, поэтому там используйте инструкцию в промпте с валидацией. Цены за токены сравните на странице цен.
