Структурированный вывод

Структурированный вывод позволяет попросить модель вернуть ответ в заранее заданной JSON-схеме. Это полезно, когда вам нужен не свободный текст, а стабильный JSON, который можно безопасно разобрать в коде.

Когда это нужно

Структурированный вывод особенно полезен, если вы хотите:

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

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

Для этого в запрос передаётся response_format с типом json_schema. Внутри вы описываете схему объекта, который модель должна вернуть.

Пример:

{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "Какая сейчас погода в Лондоне?"
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "weather",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "Город или локация"
          },
          "temperature": {
            "type": "number",
            "description": "Температура в градусах Цельсия"
          },
          "conditions": {
            "type": "string",
            "description": "Краткое описание погоды"
          }
        },
        "required": ["location", "temperature", "conditions"],
        "additionalProperties": false
      }
    }
  }
}

Ожидаемый ответ:

{
  "location": "London",
  "temperature": 18,
  "conditions": "Partly cloudy with light drizzle"
}

Поддержка моделей

Структурированный вывод поддерживают не все модели. Перед использованием проверьте:

• supported_parameters
• наличие structured_outputs
• наличие response_format

Для этого используйте каталог моделей или alltokens.ru/models.

Полный пример

Ниже пример через обычный совместимый chat/completions API.

const response = await fetch('https://api.alltokens.ru/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-4o',
    messages: [
      {
        role: 'user',
        content: 'Какая сейчас погода в Лондоне?',
      },
    ],
    response_format: {
      type: 'json_schema',
      json_schema: {
        name: 'weather',
        strict: true,
        schema: {
          type: 'object',
          properties: {
            location: {
              type: 'string',
              description: 'Город или локация',
            },
            temperature: {
              type: 'number',
              description: 'Температура в градусах Цельсия',
            },
            conditions: {
              type: 'string',
              description: 'Краткое описание погоды',
            },
          },
          required: ['location', 'temperature', 'conditions'],
          additionalProperties: false,
        },
      },
    },
  }),
});

const data = await response.json();
const weatherInfo = data.choices[0].message.content;
console.log(weatherInfo);

Практические рекомендации

Делайте схему максимально конкретной

Чем точнее properties, required и additionalProperties, тем стабильнее результат.

Используйте strict: true

Так модель сильнее привязывается к схеме и реже отдаёт лишние поля.

Добавляйте description

Пояснения внутри JSON Schema помогают модели лучше понять смысл поля.

Потоковая выдача

Если модель поддерживает и stream, и структурированный вывод, можно использовать оба режима вместе:

{
  "stream": true,
  "response_format": {
    "type": "json_schema"
  }
}

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

Что может пойти не так

Модель не поддерживает structured outputs

В этом случае вы можете получить ошибку или обычный текстовый ответ вместо строгого соответствия схеме.

Схема слишком сложная

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

Ответ всё ещё приходит как строка

В OpenAI-совместимом chat/completions поле message.content по-прежнему может приходить как строка, даже если внутри неё JSON. Значит, дальше этот JSON нужно отдельно разбирать в приложении.

Когда это особенно полезно

• извлечение структурированных данных из текста
• генерация объектов для интерфейса
• нормализация пользовательского ввода
• формирование ответов для автоматической обработки без ручного парсинга текста

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