3 способа решения ошибки конфликта thinking_budget и thinking_level в Gemini API

При вызове моделей Gemini 3.0 Pro Preview или gemini-3-flash-preview столкнулись с ошибкой thinking_budget and thinking_level are not supported together? Это проблема совместимости, возникшая из-за обновления параметров в разных версиях Google Gemini API. В этой статье мы разберем первопричину с точки зрения эволюции дизайна API и научимся правильно задавать конфигурацию.

Главная ценность: Прочитав этот текст, вы поймете, как правильно настраивать параметры режима мышления (thinking mode) для моделей Gemini 2.5 и 3.0, избежите типичных ошибок при вызове API и научитесь оптимизировать производительность и затраты на инференс.

Ключевые моменты эволюции параметров Gemini API

Основные различия в параметрах режима мышления Gemini

Главная причина, по которой Google ввела параметр thinking_level в Gemini 3.0 — это упрощение жизни разработчикам. В Gemini 2.5 параметр thinking_budget требовал от нас довольно точного расчета количества токенов на «размышления». В Gemini 3.0 эта сложность скрыта за четырьмя понятными уровнями, что значительно снижает порог входа.

Такое изменение отражает подход Google к развитию API: небольшая потеря гибкости ради удобства и единообразия между разными моделями. Для большинства задач абстракции thinking_level вполне достаточно. К thinking_budget стоит возвращаться только если вам нужна экстремальная оптимизация затрат или специфический контроль лимитов токенов.

💡 Технический совет: На практике мы рекомендуем тестировать вызовы через платформу APIYI (apiyi.com). Она предоставляет единый интерфейс для работы с моделями Gemini 2.5 Flash, Gemini 3.0 Pro и Gemini 3.0 Flash, что позволяет быстро проверить, как разные настройки режима мышления влияют на результат и стоимость в реальных условиях.

Основная причина ошибки: стратегия прямой совместимости параметров

Разбор сообщения об ошибке API

{
  "status_code": 400,
  "error": {
    "message": "Unable to submit request because thinking_budget and thinking_level are not supported together.",
    "type": "upstream_error",
    "code": 400
  }
}

Суть ошибки проста: thinking_budget и thinking_level не могут использоваться одновременно. Google ввел новые параметры в Gemini 3.0, но не стал сразу удалять старые, а применил стратегию взаимоисключения:

• Модели Gemini 2.5: принимают только thinking_budget, игнорируя thinking_level.
• Модели Gemini 3.0: отдают приоритет thinking_level, но принимают thinking_budget для обратной совместимости. Однако передавать оба параметра сразу запрещено.
• Условие возникновения ошибки: в API-запросе одновременно присутствуют параметры thinking_budget и thinking_level.

Почему возникает эта ошибка?

Разработчики обычно сталкиваются с этой проблемой в трех случаях:

🎯 Совет: При смене версии модели Gemini рекомендуем сначала протестировать совместимость параметров на платформе APIYI (apiyi.com). Платформа поддерживает быстрое переключение между моделями серий Gemini 2.5 и 3.0, что позволяет легко сравнить качество ответов и задержку при разных настройках режима мышления, избегая конфликтов в продакшене.

3 решения: выбор правильных параметров в зависимости от версии модели

Вариант 1: Конфигурация для Gemini 2.5 (используем thinking_budget)

Подходящие модели: gemini-2.5-flash, gemini-2.5-pro и др.

Описание параметров:

• thinking_budget: 0 — полностью отключить режим мышления (минимальная задержка и стоимость).
• thinking_budget: -1 — динамический режим: модель сама решает, сколько думать, исходя из сложности промпта.
• thinking_budget: <положительное число> — точное ограничение количества токенов на размышление.

Краткий пример

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

response = client.chat.completions.create(
    model="gemini-2.5-flash-preview-04-17",
    messages=[{"role": "user", "content": "Объясни принцип квантовой запутанности"}],
    extra_body={
        "thinking_budget": -1  # Динамический режим мышления
    }
)
print(response.choices[0].message.content)

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

response = client.chat.completions.create(
    model="gemini-2.5-flash-preview-04-17",
    messages=[{"role": "user", "content": "Объясни принцип квантовой запутанности"}],
    extra_body={
        "thinking_budget": -1,  # Динамический режим
        "include_thoughts": True  # Включить возврат цепочки рассуждений
    }
)

# Извлекаем процесс размышления (если включено)
for part in response.choices[0].message.content:
    if hasattr(part, 'thought') and part.thought:
        print(f"Процесс размышления: {part.text}")

# Извлекаем итоговый ответ
final_answer = response.choices[0].message.content
print(f"Итоговый ответ: {final_answer}")

Важно: Поддержка моделей Gemini 2.5 прекратится 3 марта 2026 года. Рекомендуем заранее запланировать переход на серию Gemini 3.0. На платформе APIYI (apiyi.com) вы можете быстро сравнить качество ответов до и после миграции.

Вариант 2: Конфигурация для Gemini 3.0 (используем thinking_level)

Подходящие модели: gemini-3.0-flash-preview, gemini-3.0-pro-preview.

Описание параметров:

• thinking_level: "minimal" — минимальное мышление, почти нулевой бюджет. Требует передачи подписей размышлений (Thought Signatures).
• thinking_level: "low" — низкая интенсивность, подходит для простых инструкций и чатов.
• thinking_level: "medium" — средняя интенсивность, оптимально для общих логических задач (поддерживается только в Gemini 3.0 Flash).
• thinking_level: "high" — высокая интенсивность, максимальная глубина рассуждений для сложных вопросов (значение по умолчанию).

Краткий пример

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

response = client.chat.completions.create(
    model="gemini-3.0-flash-preview",
    messages=[{"role": "user", "content": "Проанализируй временную сложность этого кода"}],
    extra_body={
        "thinking_level": "medium"  # Средняя интенсивность мышления
    }
)
print(response.choices[0].message.content)

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

# Первый этап диалога
response_1 = client.chat.completions.create(
    model="gemini-3.0-flash-preview",
    messages=[{"role": "user", "content": "Спроектируй алгоритм LRU-кэша"}],
    extra_body={
        "thinking_level": "high",
        "include_thoughts": True
    }
)

# Извлекаем подписи размышлений (Gemini 3.0 возвращает их автоматически)
thought_signatures = []
for part in response_1.choices[0].message.content:
    if hasattr(part, 'thought_signature'):
        thought_signatures.append(part.thought_signature)

# Второй этап диалога: передаем подписи для сохранения логической цепочки
response_2 = client.chat.completions.create(
    model="gemini-3.0-flash-preview",
    messages=[
        {"role": "user", "content": "Спроектируй алгоритм LRU-кэша"},
        {"role": "assistant", "content": response_1.choices[0].message.content, "thought_signatures": thought_signatures},
        {"role": "user", "content": "Оптимизируй пространственную сложность этого алгоритма"}
    ],
    extra_body={
        "thinking_level": "high"
    }
)
print(response_2.choices[0].message.content)

💰 Оптимизация затрат: Для проектов с ограниченным бюджетом отлично подходит Gemini 3.0 Flash API через платформу APIYI (apiyi.com). Платформа предлагает гибкую тарификацию и выгодные цены, что удобно как для команд, так и для индивидуальных разработчиков. Использование thinking_level: "low" поможет дополнительно снизить расходы.

Вариант 3: Стратегия адаптации при динамическом переключении моделей

Когда использовать: Если ваш код должен поддерживать и Gemini 2.5, и Gemini 3.0 одновременно.

Функция умной адаптации параметров

def get_thinking_config(model_name: str, complexity: str = "medium") -> dict:
    """
    Автоматически выбирает правильный параметр режима мышления в зависимости от модели.

    Args:
        model_name: Имя модели Gemini
        complexity: Сложность мышления ("minimal", "low", "medium", "high", "dynamic")

    Returns:
        Словарь параметров для extra_body
    """
    # Список моделей Gemini 3.0
    gemini_3_models = [
        "gemini-3.0-flash-preview",
        "gemini-3.0-pro-preview",
        "gemini-3-flash",
        "gemini-3-pro"
    ]

    # Список моделей Gemini 2.5
    gemini_2_5_models = [
        "gemini-2.5-flash-preview-04-17",
        "gemini-2.5-flash-lite",
        "gemini-2-flash",
        "gemini-2-flash-lite"
    ]

    # Проверяем версию модели
    if any(m in model_name for m in gemini_3_models):
        # Gemini 3.0 использует thinking_level
        level_map = {
            "minimal": "minimal",
            "low": "low",
            "medium": "medium",
            "high": "high",
            "dynamic": "high"  # По умолчанию высокая интенсивность
        }
        return {"thinking_level": level_map.get(complexity, "medium")}

    elif any(m in model_name for m in gemini_2_5_models):
        # Gemini 2.5 использует thinking_budget
        budget_map = {
            "minimal": 0,
            "low": 512,
            "medium": 2048,
            "high": 8192,
            "dynamic": -1
        }
        return {"thinking_budget": budget_map.get(complexity, -1)}

    else:
        # Для неизвестных моделей используем параметры Gemini 3.0 по умолчанию
        return {"thinking_level": "medium"}

# Пример использования
import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

model = "gemini-3.0-flash-preview"  # Можно менять динамически
thinking_config = get_thinking_config(model, complexity="high")

response = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "Ваш вопрос"}],
    extra_body=thinking_config
)

🚀 Быстрый старт: Рекомендуем использовать платформу APIYI (apiyi.com) для быстрого прототипирования. Платформа предоставляет готовые интерфейсы Gemini API, не требует сложной настройки и позволяет интегрировать модель за 5 минут, переключая параметры мышления одним кликом для сравнения результатов.

Подробный разбор механизма сигнатур мышления (Thought Signatures) в Gemini 3.0

Что такое сигнатуры мышления?

Введенные в Gemini 3.0 сигнатуры мышления (Thought Signatures) — это зашифрованное представление внутреннего процесса рассуждения модели. Если вы включаете параметр include_thoughts: true, модель возвращает в ответе зашифрованную сигнатуру процесса мышления. Вы можете передавать эти сигнатуры в последующих сообщениях, чтобы модель сохраняла последовательность своей цепочки рассуждений.

Основные особенности:

• Зашифрованное представление: Содержимое сигнатуры нечитаемо, его может расшифровать только сама модель.
• Сохранение цепочки рассуждений: Передавая сигнатуру в многоэтапных диалогах, вы позволяете модели продолжать рассуждение на основе своих предыдущих мыслей.
• Принудительный возврат: Gemini 3.0 по умолчанию возвращает сигнатуру мышления, даже если вы её не запрашивали.

Практические сценарии использования сигнатур мышления

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

# Раунд 1: просим модель спроектировать алгоритм
response_1 = client.chat.completions.create(
    model="gemini-3.0-pro-preview",
    messages=[{"role": "user", "content": "设计一个分布式限流算法"}],
    extra_body={
        "thinking_level": "high",
        "include_thoughts": True
    }
)

# Извлекаем сигнатуру мышления
signatures = []
for part in response_1.choices[0].message.content:
    if hasattr(part, 'thought_signature'):
        signatures.append(part.thought_signature)

# Раунд 2: продолжаем оптимизацию на основе предыдущих рассуждений
response_2 = client.chat.completions.create(
    model="gemini-3.0-pro-preview",
    messages=[
        {"role": "user", "content": "设计一个分布式限流算法"},
        {
            "role": "assistant",
            "content": response_1.choices[0].message.content,
            "thought_signatures": signatures  # Передаем сигнатуру мышления
        },
        {"role": "user", "content": "如何处理分布式时钟不一致问题?"}
    ],
    extra_body={"thinking_level": "high"}
)

💡 Лучшая практика: В сценариях, требующих многоэтапных сложных рассуждений (проектирование систем, оптимизация алгоритмов, код-ревью), рекомендуем протестировать разницу в результатах с передачей сигнатур на платформе APIYI apiyi.com. Платформа полностью поддерживает механизм сигнатур Gemini 3.0, что позволяет легко проверить качество рассуждений при разных конфигурациях.

Часто задаваемые вопросы

# Передаем только thinking_level и смотрим на ответ
response = client.chat.completions.create(
    model="your-model-name",
    messages=[{"role": "user", "content": "test"}],
    extra_body={"thinking_level": "low"}
)
# Если возвращается ошибка 400 с пометкой, что thinking_level не поддерживается — это Gemini 2.5

Итоги

Основные причины ошибок с параметрами thinking_budget и thinking_level в Gemini API:

1. Взаимоисключающие параметры: Gemini 2.5 использует thinking_budget, а Gemini 3.0 — thinking_level. Передавать их одновременно нельзя.
2. Идентификация модели: Версия определяется по названию. Для серии 2.5 используйте thinking_budget, для серии 3.0 — thinking_level.
3. Динамическая адаптация: Используйте функции-адаптеры, которые автоматически выбирают нужный параметр в зависимости от имени модели, чтобы избежать жесткого кодирования (hardcoding).
4. Подписи размышлений (Thinking Signatures): В Gemini 3.0 появился механизм сигнатур. В сложных сценариях с несколькими итерациями диалога (multi-turn) нужно передавать эти подписи, чтобы сохранять цепочку рассуждений.
5. Рекомендации по миграции: Поддержка Gemini 2.5 прекратится 3 марта 2026 года. Советуем как можно скорее переходить на серию 3.0.

Рекомендуем использовать APIYI (apiyi.com) для быстрой проверки различных конфигураций режима размышлений. Платформа поддерживает всю линейку моделей Gemini, предоставляет унифицированный интерфейс и гибкую систему тарификации, что отлично подходит как для быстрого тестирования, так и для развертывания в продакшене.

Автор: Техническая команда APIYI | Если у вас возникли вопросы, заходите на APIYI (apiyi.com) за новыми решениями по интеграции моделей ИИ.