Reasoning effort: low / medium / high / xhigh — гайд по выбору

Параметр reasoning_effort есть у всех моделей GPT-5 через Codex Key. Он не меняет тарифный коэффициент, но напрямую влияет на длину ответа, качество и latency. Разбираем, когда какой уровень включать.

TL;DR

Уровень	Задачи	Avg output tokens	Avg latency	Качество
low	Классификация, короткий ответ, чат	80-200	0.5-1.5s	Базовое
medium (default)	Генерация кода, обычный chat, summarization	300-800	1.5-4s	Хорошее
high	Multi-step reasoning, сложный код, ревью	800-2500	4-12s	Высокое
xhigh	Исследования, доказательства, deep analysis	2000-8000	12-40s	Максимум

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

reasoning_effort управляет внутренней цепочкой рассуждений модели. На high и xhigh модель тратит больше токенов на "thinking" (часть из них видимая, часть нет, в зависимости от модели), прежде чем выдать финальный ответ.

Важно: вы платите за все токены reasoning, включая невидимые. На xhigh запрос может потребить в 5-10 раз больше токенов, чем low.

low — когда

• Классификация: "это спам / не спам?", "intent: search / buy / help?"
• Структурированный extract: имя, email, дата из текста
• Короткий чат-ответ: "перефразируй вежливее", "переведи строку"
• Routing: определи, в какой подсистеме обработать запрос

resp = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "intent: 'хочу вернуть деньги'"}],
    extra_body={"reasoning_effort": "low"},
    max_tokens=50,
)

На таких задачах low даёт качество в пределах 1-2% от medium, но в 3-5 раз дешевле.

medium — когда

Default. Используйте, если не знаете, какой уровень подходит.

• Генерация функций, тестов, миграций
• Обычный chat с пользователем
• Code-completion (но в IDE обычно используется low)
• Summarization документа
• RAG-ответы по контексту

high — когда

Включайте, если на medium модель не справляется:

• Multi-file рефакторинг
• Архитектурные решения с trade-off анализом
• SQL-планирование с join'ами и подзапросами
• Code-review с поиском edge-cases
• Сложный debugging

resp = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "найди race condition в этом коде: ..."}],
    extra_body={"reasoning_effort": "high"},
)

В нашей практике переход с medium на high даёт +10-25% точности на reasoning-задачах, ценой +50-100% токенов в ответе.

xhigh — когда

Редко. Реально полезен только для:

• Исследовательские задачи: вывести доказательство, спроектировать алгоритм с нуля
• Анализ длинных документов с поиском неочевидных связей
• Decompilation, reverse engineering, security analysis
• Multi-step планирование с глубиной 10+ шагов

Для большинства продакшен-сценариев xhigh — overkill. Если вы не видите ощутимого качественного скачка относительно high, оставайтесь на high.

Комбинация с моделью

reasoning_effort мультиплицирует эффект выбора модели:

Модель × Effort	Когда
gpt-5.4 + low	Дешёвый router, classifier
gpt-5.4 + medium	Default для 80% задач
gpt-5.4 + high	Когда нужно качество, но gpt-5.5 дорого
gpt-5.5 + medium	Сложные задачи без перерасхода
gpt-5.5 + high	Hardcore reasoning, ревью архитектуры
gpt-5.5 + xhigh	Только исследования

Реальные замеры на одной задаче

Задача: "найди и исправь утечку памяти в Go-сервисе на 800 строк".

Конфигурация	Output tokens	Latency	Корректность
gpt-5.4 + low	180	1.1s	22%
gpt-5.4 + medium	520	3.4s	58%
gpt-5.4 + high	1240	8.7s	74%
gpt-5.5 + medium	680	6.2s	79%
gpt-5.5 + high	1850	14.3s	91%
gpt-5.5 + xhigh	4200	31.2s	93%

Видно: скачок high → xhigh даёт +2% точности при ×2.3 росте токенов. Не стоит.

Дешёвый паттерн: эскалация

def solve(task: str) -> str:
    for effort in ("low", "medium", "high"):
        resp = client.chat.completions.create(
            model="gpt-5.4",
            messages=[...],
            extra_body={"reasoning_effort": effort},
        )
        if validate(resp):    # ваша eval-функция
            return resp.choices[0].message.content
    # last resort
    resp = client.chat.completions.create(model="gpt-5.5", ...)
    return resp.choices[0].message.content

Этот паттерн снижает средний счёт в 2-3 раза vs всегда high.

Итог

• low для рутины и роутинга
• medium для дефолта
• high когда medium явно недотягивает
• xhigh только для исследований

Замеряйте через свои evals. Не верьте интуиции — reasoning_effort часто переоценивают.