Обновление API Gemini 3.6 Flash: как безопасно перейти с Gemini 3.5 Flash

Разработчики, использующие Gemini 3.5 Flash в кодовых помощниках, мультимодальных приложениях и AI Agent, часто начинают обновление с простой замены строки model. Это опасный короткий путь: изменение поведения мышления, инструментов, формата ответа и стоимости может проявиться только на реальных сценариях. В этом руководстве по обновлению API Gemini 3.6 Flash вы получите чек-лист миграции, таблицу совместимости, последовательность тестов, схему серого запуска и план отката к прежней модели.

Сначала вывод: не переключайте продакшен одной заменой модели

На 23 июля 2026 года в официальной документации указано, что Gemini 3.6 Flash доступна как стабильная модель с идентификатором gemini-3.6-flash. Для неё заявлены контекстное окно до 1 000 000 токенов, максимум вывода 64 000 токенов, режим мышления по умолчанию medium и поддержка встроенных инструментов, включая Computer Use. В официальной таблице также указана стоимость 1,50 доллара за 1 миллион входных токенов и 7,50 доллара за 1 миллион выходных токенов. Перед релизом всё равно проверьте текущие значения: тарифы, лимиты и доступность API могут измениться. (ai.google.dev)

Практический вывод такой:

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

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

Какие проекты стоит обновлять в первую очередь

Переход с Gemini 3.5 Flash на Gemini 3.6 Flash имеет смысл не для каждого проекта одновременно. Сначала определите, где новая модель может дать измеримый результат, а где риск изменений выше потенциальной пользы.

1. Кодовые помощники. Если модель должна анализировать несколько файлов, строить план исправления и предлагать патч, проверяйте не только качество текста, но и количество итераций до рабочего результата.
2. Быстрые агентные циклы. В AI Agent важны задержка, число вызовов инструментов, корректное завершение задачи и отсутствие повторных действий.
3. Мультимодальные приложения. Обработка скриншотов, PDF, видео и аудио требует отдельной матрицы тестов: одинаковое имя модели не гарантирует одинаковое поведение на каждом типе данных.
4. Автоматизация интерфейса. Если используется Computer Use, любая ошибка в координатах, выборе элемента или подтверждении действия должна считаться критичной.
5. Потоковые и массовые задачи. Для классификации, извлечения JSON и суммаризации важнее стабильность схемы и цена полной операции, а не впечатление от одного ответа.

Если приложение решает простые задачи и работает без проблем, сначала проведите ограниченный эксперимент. Если же Gemini 3.5 Flash регулярно делает лишние шаги, плохо работает с длинным контекстом или требует много ручной проверки, миграцию стоит поставить выше в очереди.

Что проверить до миграции Gemini 3.5 Flash на 3.6

Перед изменением кода соберите карту всех мест, где старая модель упоминается явно или косвенно. Поиск только по строке gemini-3.5-flash часто пропускает конфигурацию CI/CD, тестовые переменные и резервные маршруты.

Проверьте следующие элементы:

• модельный идентификатор в исходном коде;
• переменные окружения и секреты;
• конфигурацию серверless-функций и фоновых задач;
• версию пакета google-genai или используемого SDK;
• тип API — generateContent или Interactions API;
• потоковый и обычный режимы ответа;
• параметры мышления;
• вызовы функций и формат FunctionResponse;
• JSON Schema и структурированный вывод;
• обработку изображений, PDF, видео и аудио;
• лимиты повторов, тайм-ауты и обработку ошибок;
• разрешения Computer Use;
• региональную доступность и квоты проекта.

В официальной документации для новых моделей отдельно отмечены изменения конфигурации: устаревшие параметры temperature, top_p и top_k рекомендуется убрать, а прежний thinking_budget заменить на thinking_level. Поэтому совместимость API Gemini 3.6 Flash нужно оценивать не по факту успешного HTTP-ответа, а по полному поведению запроса. (ai.google.dev)

Как изменить Gemini 3.6 Flash модельный идентификатор

Начинайте с минимального изменения и не смешивайте его с обновлением бизнес-логики. Сначала добавьте новую модель в конфигурацию, затем проведите отдельный smoke-тест.

Шаг 1. Вынесите модель в переменную окружения

export GEMINI_MODEL_PRIMARY="gemini-3.6-flash"
export GEMINI_MODEL_FALLBACK="gemini-3.5-flash"

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

Шаг 2. Проверьте модель через список доступных моделей

До запуска тестового набора запросите список моделей API и убедитесь, что нужный идентификатор присутствует в проекте. Официальный метод models.list предназначен именно для получения доступных моделей и их возможностей. Метод models.get позволяет проверить метаданные конкретной модели, включая лимиты и поддерживаемые действия. (ai.google.dev)

Пример проверки:

curl "https://generativelanguage.googleapis.com/v1beta/models?key=$GEMINI_API_KEY"

В рабочем приложении не полагайтесь на одну локальную проверку. Список может зависеть от проекта, разрешений, API-режима и региона.

Шаг 3. Выполните минимальный запрос

Проверьте четыре свойства:

• запрос с обычным текстом;
• корректное завершение ответа;
• наличие ожидаемого поля в SDK-объекте;
• отсутствие предупреждений о неподдерживаемых параметрах.

Шаг 4. Зафиксируйте исходные показатели

До миграции сохраните для Gemini 3.5 Flash:

• медианную и 95-й перцентиль задержки;
• долю ошибок;
• среднее число входных и выходных токенов;
• число вызовов инструментов;
• процент ответов, прошедших JSON Schema;
• долю задач, потребовавших ручной доработки.

Без базовой линии команда не сможет доказать, что обновление действительно улучшило систему.

Нужно ли менять режим мышления и промпты

Да, эту часть нельзя оставлять на конец. В официальных материалах для Gemini 3.5 Flash уже указывалось, что усилие мышления по умолчанию изменилось с high на medium, а контекст рассуждений между ходами может сохраняться. Для Gemini 3.6 Flash документация также указывает значение medium по умолчанию. Это может повлиять на длину ответа, число шагов планирования и расход токенов. (ai.google.dev)

Проведите следующие проверки:

1. Отправьте одинаковый набор из 30–50 реальных запросов обеим моделям.
2. Сравните не только итоговый текст, но и полезность промежуточного плана.
3. Проверьте, не стала ли модель объяснять очевидные действия слишком подробно.
4. Посмотрите, не увеличилось ли число вызовов функций.
5. Для быстрых задач протестируйте более низкий уровень мышления, если API и SDK это поддерживают.
6. Для сложных задач сравните качество при medium и повышенном уровне.
7. Уберите из системных инструкций формулировки, которые принуждают модель раскрывать чрезмерно подробную цепочку рассуждений.

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

Функции, структурированный вывод и Computer Use

Именно здесь чаще всего обнаруживается настоящая разница между «API отвечает» и «приложение работает». В официальном руководстве для миграции отмечено, что в ответах функций нужно добавлять id и соответствующее name для частей FunctionResponse. Также новые модели поддерживают Computer Use как нативный инструмент. (ai.google.dev)

Проверяйте каждую функцию по четырём уровням:

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

Gemini 3.6 Flash Agent тестирование

Для Gemini 3.6 Flash Agent тестирования составьте сценарий из нескольких шагов:

1. агент получает задачу и формирует план;
2. вызывает инструмент чтения;
3. анализирует результат;
4. вызывает инструмент изменения;
5. получает ошибку или неполный ответ;
6. корректирует план;
7. завершает задачу кратким отчётом.

Тест считается успешным только при выполнении всех этапов. Один хороший финальный ответ не компенсирует неправильный вызов инструмента или отсутствие контроля разрешений.

Мультимодальные входы: изображения, видео, аудио и PDF

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

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

У каждой проверки должны быть следующие поля:

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

Официальные рекомендации отдельно советуют повторно тестировать PDF и медиа, а при слишком большом контексте регулировать разрешение медиа. Для приложений, которым нужна сегментация изображений, нельзя автоматически считать Gemini 3.x заменой прежнего решения: в документации это ограничение указано отдельно. (ai.google.dev)

Как понять, окупается ли обновление

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

Используйте формулу:

стоимость задачи =
входные токены +
выходные токены +
повторные вызовы +
стоимость инструментов +
ручная проверка

По официальной таблице для Gemini 3.6 Flash указаны 1,50 доллара за 1 миллион входных токенов и 7,50 доллара за 1 миллион выходных токенов. Это полезная исходная точка, но фактическая стоимость проекта зависит от размера контекста и поведения агента. (ai.google.dev)

Сравните две версии по пяти показателям:

1. время до рабочего результата;
2. стоимость полной задачи, а не одного ответа;
3. доля вызовов, завершённых без повторов;
4. число ручных исправлений;
5. доля ответов, прошедших автоматическую проверку.

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

Как выполнить серый запуск и сохранить API-откат

Не переводите весь трафик сразу. Используйте две модели и явный маршрутизатор:

если тестовый трафик:
    gemini-3.6-flash
иначе:
    gemini-3.5-flash

Рекомендуемая последовательность:

1. Запустите локальные smoke-тесты.
2. Проведите полный набор регрессии в изолированной среде.
3. Направьте на новую модель небольшую долю внутренних запросов.
4. Добавьте отдельные метрики для каждой модели.
5. Увеличивайте долю только при стабильных результатах.
6. Сохраните переключатель отката без повторной сборки приложения.
7. После релиза оставьте старый маршрут активным до завершения периода наблюдения.

Минимальные условия автоматического отката:

• рост доли ошибок;
• превышение установленного 95-го перцентиля задержки;
• нарушение JSON Schema;
• повторные опасные действия Computer Use;
• рост стоимости задачи;
• ухудшение оценки человеком.

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

Регрессионная проверка в удалённой среде Mac от SpinMac

Для команд, которым нужно одновременно держать старую и новую конфигурацию, удалённая среда Mac удобна как отдельный стенд: в ней можно закрепить версии SDK, инструменты разработчика, тестовые файлы и сценарии Agent, не затрагивая рабочую машину.

Практический процесс выглядит так:

1. Создайте отдельную рабочую среду под регрессионный стенд.
2. Зафиксируйте версии SDK и зависимостей в файле окружения.
3. Разделите ключи и переменные для Gemini 3.5 Flash и Gemini 3.6 Flash.
4. Загрузите обезличенные изображения, PDF, видео и аудио.
5. Запустите одинаковый набор тестов на обеих моделях.
6. Сохраните логи запросов, ответы, задержку и ошибки в едином формате.
7. Повторите провальные сценарии после исправления промпта или схемы.
8. Только после этого подготовьте серый запуск.

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

Важно: не переносите в тестовый стенд реальные секреты, персональные данные и производственные токены без отдельной политики доступа. Для Computer Use используйте тестовые аккаунты и ограниченные разрешения.

Самые частые ошибки при обновлении API

Ошибка 1 — заменить только модельный идентификатор.
Так можно получить успешный ответ, но сломать инструменты, JSON или обработку мультимодальных данных.

Ошибка 2 — оставить старые параметры семплирования.
Проверьте конфигурацию и уберите параметры, которые новая версия не рекомендует или не поддерживает.

Ошибка 3 — не проверить SDK.
Изменения API могут проявиться на уровне типов, названий полей и сериализации. Версию SDK нужно фиксировать и тестировать вместе с приложением.

Ошибка 4 — считать текстовый тест доказательством совместимости.
Кодовый помощник, PDF-парсер и Computer Use имеют разные точки отказа.

Ошибка 5 — не ограничить автоматические действия.
Инструменты, которые меняют файлы, отправляют формы или запускают команды, должны иметь подтверждение, журналирование и аварийный выключатель.

Ошибка 6 — оценивать только цену токенов.
Более длинный контекст, повторные вызовы и ручная проверка могут изменить итоговую экономику.

Ошибка 7 — отказаться от отката слишком рано.
Старая модель должна оставаться доступной до тех пор, пока новая не пройдёт реальные сценарии и период наблюдения.

Итог: когда переход оправдан

Если текущий проект на Gemini 3.5 Flash стабильно решает простые текстовые задачи, немедленная миграция не обязательна. Если же вам нужны более сложные агентные циклы, мультимодальное понимание, Computer Use или сокращение ручных итераций, Gemini 3.6 Flash стоит проверить уже сейчас — но через регрессионный набор, а не через замену одной строки.

Обычный локальный компьютер часто неудобен для такого сравнения: приходится прерывать рабочее окружение, вручную переключать SDK, хранить две конфигурации на одной машине и повторять мультимодальные тесты нестабильно. Долгосрочно это хуже выделенного Mac-стенда: меньше изоляции, выше риск конфликта зависимостей и сложнее сохранить воспроизводимые условия. Для параллельной проверки Gemini 3.5 Flash и Gemini 3.6 Flash аренда Mac через SpinMac может быть более практичным вариантом, особенно если вам нужно сохранить старое окружение, запускать AI Agent по расписанию и проводить длительные тесты изображений, PDF, видео и аудио.