Reasoning

Настройте интенсивность рассуждений для сложных задач и корректно читайте результаты, сводки и Usage.

Reasoning подходит для многоэтапного анализа, сложных ограничений, математических выводов, планирования кода и совместной работы с инструментами. Модели рассуждения обычно позволяют управлять интенсивностью рассуждений и могут возвращать сводку, Thinking Block или соответствующий Usage. Конкретный вид зависит от модели и протокола.

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

У рассуждения нет единого поля для всех протоколов

Chat, Responses, Anthropic Messages и Gemini по-разному представляют настройки рассуждения, доступные результаты и состояние диалога. Не переносите поля одного протокола напрямую в другой.

Когда использовать

Задача	Рекомендация
Планирование с несколькими ограничениями, сложный анализ	Выберите модель с поддержкой рассуждения и начните оценку с низкого или стандартного уровня интенсивности
Математика, код и логика	Проверяйте итоговый ответ: интенсивность рассуждений не гарантирует правильности результата
Рабочие процессы с инструментами	Сохраняйте требуемые протоколом вызовы, результаты и состояния, ограничьте число итераций
Краткое перефразирование, извлечение и классификация	Сначала проверьте обычную модель или низкую интенсивность рассуждений, избегая лишних затрат

Сначала проверьте доступные вашей учётной записи модели, протоколы и метки возможностей в каталоге моделей. Замените MODEL_ID моделью, доступной вашей учётной записи и поддерживающей нужные настройки рассуждения.

Настройка интенсивности рассуждений в Responses

Responses помещает настройки рассуждения в объект reasoning:

curl 'https://api.agtcloud.cn/v1/responses' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "input": "Сравните два варианта миграции базы данных и обоснуйте выбор.",
    "reasoning": {
      "effort": "medium",
      "summary": "auto"
    }
  }'

effort управляет интенсивностью рассуждений, а summary запрашивает разрешённую протоколом сводку рассуждения. Доступные значения и их применение зависят от модели. Полное определение см. в Responses Reference.

Представление рассуждения в разных протоколах

Chat запрашивает разные уровни интенсивности через reasoning_effort. Если ответ содержит токены рассуждения, они обычно учитываются в деталях завершения Usage. Итоговый ответ по-прежнему читается из Assistant Message.

{
  "model": "MODEL_ID",
  "messages": [
    {"role": "user", "content": "Проанализируйте основные риски этого плана развёртывания."}
  ],
  "reasoning_effort": "medium"
}

Значения примеров показывают только положение полей: не все модели принимают одинаковые уровни или бюджеты. См. справочники Chat Completions, Anthropic Messages и Gemini Generate Content.

Итоговый ответ и доступные сведения о рассуждении

Приложению обычно необходимо отдельно обрабатывать:

Итоговый ответ: содержимое, показываемое пользователю или передаваемое бизнес-процессу.
Сводку рассуждения или Thinking Block: читайте только то, что явно вернули протокол и модель; не считайте это полным внутренним ходом мысли модели.
Usage: учитывайте ввод, итоговый вывод и токены рассуждения; положение полей зависит от протокола.
Остановку или неполное состояние: определяйте, не прерван ли ответ из-за бюджета вывода, политики содержимого, отмены или ошибки.

Если нужен только итоговый вывод, доступное рассуждение сохранять необязательно. Перед его сохранением оцените конфиденциальность, объём журналирования и политику хранения данных.

Streaming и вызовы инструментов

Потоковый ответ может отдельно возвращать приращения рассуждения и итогового текста: используйте разные буферы.
До и после вызова инструмента могут появляться состояние протокола или Thinking Block; не сохраняйте только итоговый текст.
Выполнение инструментов по-прежнему требует проверки аргументов, прав и идемпотентности из Tool Calling.
При продолжении возвращайте только историю, требуемую целевым протоколом; не изменяйте подписи, ID вызовов и непрозрачное состояние.

Полная потоковая обработка описана в Streaming.

Планирование бюджета вывода

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

В рабочем приложении одновременно отслеживайте:

полноту итогового ответа;
причину остановки или неполного ответа;
Usage рассуждения и видимого вывода;
качество, задержку и стоимость при разных уровнях интенсивности;
завершение цикла инструментов в допустимом числе итераций и общем сроке.

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

Учётная запись поддерживает целевую модель, её интерфейс рассуждения и поля запроса проверены.
Приложение отправляет только поля рассуждения, принимаемые целевым протоколом.
Итоговый ответ, доступное рассуждение и Usage обрабатываются отдельно.
Streaming, диалог и вызовы инструментов сохраняют необходимое состояние протокола.
Недостаточный бюджет, отказ, тайм-аут и неполный ответ имеют явные ветви обработки.
Интенсивность рассуждений, сводка и доступный Thinking не описываются как гарантия правильности.

При ошибках см. Ошибки и диагностика. Перед сменой модели или протокола прочитайте Выбор протокола.