Рассуждение

Чтобы использовать рассуждение в Responses API, выберите в каталоге моделей вариант с признаком Рассуждение и путем /v1/responses, скопируйте его точный request_model_id и начните с запроса, содержащего только model и input. AI Gateway принимает такой запрос по адресу POST https://route.smartaipack.ru/v1/responses, учитывает токены рассуждения отдельно, если поставщик их передал, и показывает расход в кабинете.

Важно: признак поддержки не превращает разные модели в один и тот же программный контракт. Необязательные параметры, доступные уровни усилия, состав ответа и потоковые события определяет выбранный поставщик. Поэтому сначала проверьте модель, путь, цену и request_model_id в Моделях и на странице Тарифы, а затем испытайте минимальный запрос.

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

Базовый запрос не требует отдельного поля для рассуждения:

curl https://route.smartaipack.ru/v1/responses \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<REQUEST_MODEL_ID_ИЗ_КАТАЛОГА>",
    "input": "Сравни два варианта резервного копирования и дай рекомендацию с критериями выбора."
  }'

Не вставляйте настоящий ключ в пример, клиентский код или репозиторий. Значение model также не стоит брать из чужой статьи: откройте нужного поставщика в каталоге, убедитесь, что у него отмечены рассуждение и /v1/responses, затем скопируйте показанный request_model_id без ручного изменения.

Некоторые поставщики дополнительно принимают поле reasoning. Например, для варианта, чей собственный контракт явно поддерживает effort: "high", условное тело может выглядеть так:

{
  "model": "<REQUEST_MODEL_ID_ИЗ_КАТАЛОГА>",
  "input": "Найди противоречия в плане миграции и предложи порядок проверок.",
  "reasoning": {
    "effort": "high"
  }
}

Это не общий контракт AI Gateway и не гарантия для любого маршрута. Перед таким запросом сверьте документацию именно выбранного поставщика. Если подтверждения нет, вернитесь к model + input: шлюз проксирует запрос по опубликованному маршруту, но не переводит один вариант поля reasoning во все возможные форматы.

Уровни усилия

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

Названия вроде minimal, low, medium и high встречаются в контрактах отдельных поставщиков. AI Gateway не гарантирует, что каждый вариант модели принимает все эти значения или вообще использует поле effort. Проверяйте допустимый набор у поставщика, а не перебирайте значения в рабочем приложении.

Полезный порядок выбора:

1. Сформулируйте проверяемый результат: решение, таблицу критериев, краткое объяснение или список шагов.
2. Испытайте минимальный запрос без настройки усилия.
3. Если качество недостаточно и контракт поставщика это позволяет, добавьте поддерживаемый уровень.
4. Сравните не только ответ, но и задержку, токены и стоимость в Использовании и Аналитике.

Пример сложной задачи

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

curl https://route.smartaipack.ru/v1/responses \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<REQUEST_MODEL_ID_ИЗ_КАТАЛОГА>",
    "input": "Есть два плана переноса сервиса. План А: остановка на 20 минут и проверенная резервная копия. План Б: переключение без остановки, но восстановление еще не испытывали. Сравни риски, назови недостающие проверки и предложи безопасный порядок решения. Дай итог, краткое объяснение и проверяемые шаги."
  }'

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

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

Рассуждение в контексте диалога

Историей диалога управляет клиентское приложение. Оно сохраняет нужные сообщения и при следующем запросе передает контекст в форме, которую принимает выбранный поставщик. AI Gateway не обещает универсальное серверное хранение диалога, поддержку previous_response_id или автоматический перенос скрытых блоков рассуждения между запросами.

Для надежного многошагового сценария:

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

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

Потоковое рассуждение

Прокси AI Gateway сохраняет потоковую передачу ответа. Если выбранный поставщик поддерживает поток на /v1/responses, запрос может содержать stream: true:

curl -N https://route.smartaipack.ru/v1/responses \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<REQUEST_MODEL_ID_ИЗ_КАТАЛОГА>",
    "input": "Сравни три стратегии обработки очереди и дай итоговую рекомендацию.",
    "stream": true
  }'

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

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

Ответ с рассуждением

Форма обычного ответа также может различаться. Один поставщик возвращает текст в массиве результатов, другой добавляет сведения об использовании или отдельное резюме, третий не возвращает никаких видимых данных о рассуждении. AI Gateway не гарантирует поля encrypted_content, summary или единый объект usage для всех моделей.

Поэтому обработчик должен:

1. Проверить HTTP-статус и Content-Type.
2. Разобрать JSON или поток согласно контракту поставщика.
3. Найти итоговый текст без предположения, что он всегда лежит в одном поле.
4. Считать необязательные сведения о рассуждении действительно необязательными.
5. При ошибке сохранить время, путь и request_model_id, но не ключ и не чувствительный ввод.

Отдельный учёт AI Gateway не следует выводить из формы клиентского ответа. Если поставщик сообщил reasoning_tokens, система выделяет их в самостоятельную составляющую тарификации и аналитики. Проверяйте фактический вызов в Использовании, разбивку токенов в Аналитике и цену выбранного варианта на странице Тарифы.

Рекомендации

• Выбирайте конкретного поставщика в каталоге моделей, а не только общее имя модели.
• Проверяйте одновременно request_model_id, /v1/responses, признак рассуждения и цену.
• Начинайте с model + input; необязательные поля добавляйте по одному после сверки контракта.
• Формулируйте критерии ответа и просите краткое объяснение или проверяемые шаги вместо скрытой цепочки рассуждений.
• Повышайте усилие только для задач, где измеримое улучшение оправдывает задержку и стоимость.
• Для диалога храните необходимую историю на стороне клиента и сокращайте ее до полезного состояния.
• Для потока учитывайте события фактического поставщика и корректно обрабатывайте обрыв.
• После испытания сверяйте токены и списание в кабинете; при расхождении собирайте время, путь и идентификатор модели.

Следующие шаги

Если вы еще не отправляли запросы на этот путь, начните с обзора Responses API и базового использования. Затем выберите в Моделях вариант с нужными возможностями, выполните короткий испытательный запрос и проверьте его в Использовании и Аналитике.

Для следующих сценариев пригодятся руководства по вызову инструментов и обработке ошибок Responses API. Общие причины ошибок уже описаны в статье Ошибки API. Если фактический ответ или списание не совпадает с ожидаемым контрактом выбранного поставщика, обратитесь в поддержку, указав время запроса, путь и request_model_id, но не передавайте полный API-ключ.