Structured Output

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

Structured Output позволяет модели возвращать результат в заданной структуре, чтобы программа могла извлечь поля, записать их в базу данных или передать в следующий рабочий процесс. Типичные сценарии — классификация обращений, извлечение данных из форм, результаты модерации и аналитические отчёты фиксированной структуры.

Structured Output и Tool Calling решают разные задачи

Для структурированного ответа используйте Structured Output. Чтобы модель выбрала функцию и запросила её выполнение приложением, используйте Tool Calling. Schema может ограничивать и аргументы инструмента, но это часть цикла вызова инструмента.

Выберите подходящий формат вывода

Способ	Что он решает	Что ещё должен сделать клиент
Требование JSON в запросе	Базовое ограничение для моделей без специальных полей	Извлечь JSON, разобрать, проверить и повторить запрос при ошибке
JSON Object	Требует корректный объект JSON	Проверить поля, типы и бизнес-правила
JSON Schema	Задаёт целевую структуру в запросе	Учесть поддержку модели, отказ, усечение и ошибки валидации

Поддержка JSON Object, JSON Schema и строгого соблюдения зависит от модели и протокола. Ответ 200 сам по себе не доказывает, что заданная Schema была применена.

Небольшая и однозначная Schema

Следующая структура классифицирует вопрос клиента как обращение в поддержку:

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": ["billing", "technical", "account"]
    },
    "priority": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3
    },
    "summary": {
      "type": "string"
    }
  },
  "required": ["category", "priority", "summary"],
  "additionalProperties": false
}

Имена полей должны быть стабильными и понятными, а значения перечислений — соответствовать бизнес-коду. Не начинайте с глубокой вложенности, множества необязательных ветвей и труднообъяснимых регулярных ограничений.

Структурированный результат через Chat Completions

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "Мой API Key не работает. Помогите классифицировать проблему."
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "support_ticket",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "category": {
              "type": "string",
              "enum": ["billing", "technical", "account"]
            },
            "priority": {
              "type": "integer",
              "minimum": 1,
              "maximum": 3
            },
            "summary": {"type": "string"}
          },
          "required": ["category", "priority", "summary"],
          "additionalProperties": false
        }
      }
    }
  }'

strict — часть целевого формата, но его доступность зависит от модели. Полные поля см. в Chat Completions Reference.

Расположение полей в разных протоколах

Chat выбирает json_object или json_schema в response_format. При JSON Schema определение находится в response_format.json_schema.schema.

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "support_ticket",
      "schema": {"type": "object"}
    }
  }
}

Эти структуры нельзя напрямую переносить в другой протокол. Перед использованием см. Responses Reference и Gemini Generate Content Reference.

Проверка после разбора

type SupportTicket = {
  category: 'billing' | 'technical' | 'account';
  priority: number;
  summary: string;
};

function parseTicket(raw: string): SupportTicket {
  const value: unknown = JSON.parse(raw);

  if (
    typeof value !== 'object' ||
    value === null ||
    !('category' in value) ||
    !('priority' in value) ||
    !('summary' in value)
  ) {
    throw new Error('В структурированном результате отсутствуют обязательные поля');
  }

  return value as SupportTicket;
}

Пример показывает лишь минимальную проверку. В рабочем проекте используйте валидатор Schema, соответствующий модели бизнес-данных, и проверяйте перечисления, длину, числовые диапазоны и зависимости между полями.

Неполные и некорректные результаты

Ситуация	Действие
Возвращён обычный текст	Проверьте поддержку формата моделью, положение полей и изменения запроса со стороны SDK
JSON не разбирается	Сохраните обезличенный ответ и причину остановки, ограниченно повторите запрос по бизнес-политике
Нет обязательных полей	Считайте это ошибкой валидации; не скрывайте отсутствие важных данных значениями по умолчанию
Вывод усечён	Увеличьте бюджет вывода или упростите Schema; не достраивайте отсутствующий JSON догадками
Модель отказалась отвечать	Обработайте отказ отдельно, не считая его текст бизнес-объектом
Schema разбирается, но данные непригодны	Верните явную ошибку бизнес-валидации или передайте результат на ручную обработку

Проверка перед запуском

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

После выбора модели в каталоге моделей изучите полные поля в соответствующем API Reference. При ошибках запросов см. Ошибки и диагностика.