Миграция Gemini 2.5: что проверить до смены маршрута API 1 декабря

1. Две даты и два направления замены

В журнале Gemini API от 2 ноября 2026 года сказано, что Gemini 2.5 Pro и 2.5 Flash объявлены устаревшими и больше не выбираются в Google AI Studio. Изменение API назначено на 1 декабря: запросы к gemini-2.5-pro будут направляться в gemini-3.8-flash, а к gemini-2.5-flash — в gemini-3.5-flash-lite, с оплатой по тарифам целевой модели.

На дату проверки, 4 ноября, доступ к этим старым моделям через API ограничен пользователями, которые активно применяли их раньше. Отдельная модель gemini-2.5-flash-lite под эту отмену не подпадает. Успешный запрос по старому имени сегодня не доказывает сохранение поведения после назначенной даты. Точного часа переключения и часового пояса в прочитанном объявлении нет.

Эти положения относятся к Gemini Developer API и AI Studio. Они не устанавливают одинаковый график для пользовательского приложения Gemini, прав по подписке или всех развертываний Vertex AI. До выбора замены укажите в каждой задаче конкретный сервис и ответственного за проект.

Google: журнал Gemini API от 2 ноября · Google: устаревание, доступ и график маршрутизации

2. Опишите контракт до замены имени модели

Проверьте конфигурацию приложения, фоновые обработчики, блокноты, пакетные задания и псевдонимы собственного шлюза. Переменная может содержать pro, а шлюз или исполнитель — выбирать другую модель. Сохраняйте заданную модель и идентификатор, раскрываемый ответом: одного HTTP 200 недостаточно, чтобы доказать проверку нужного маршрута.

Отделяйте миграцию модели от смены конечной точки. Google продолжает поддерживать GenerateContent, а для новых проектов рекомендует Interactions. Если одновременно поменять модель, SDK, интерфейс, инструкции и протокол инструментов, причину провала воспроизведения будет трудно установить. Сначала зафиксируйте воспроизводимую базу, затем меняйте по одной составляющей.

• Для каждой точки входа запишите endpoint, ID модели, версию SDK и инструкций, хеш схемы инструментов и параметры запроса по умолчанию.
• Установите владельца состояния: история SDK, части контента в приложении, сохраненные Interactions или воспроизведение шагов без состояния.
• Отделите чтение от отправки сообщений, изменения записей и платных действий; при воспроизведении имитируйте последствия.
• Назначьте ответственного, критерии приемки и разрешенный набор данных. Не переносите клиентские учетные данные и необезличенные разговоры в репозиторий миграции.

Google: состояние Interactions, настройки хода и хранение · Google: ключи API, проекты и учетные данные

3. Замените предположения матрицей совместимости

Актуальные руководства описывают не только новую модель, но и изменения запросов. Часть устаревших параметров сэмплирования игнорируется в описанном поколении и может вызывать ошибки в последующих. Это не означает, что все такие запросы уже завершаются ошибкой. Удаляйте поля осознанно и отдельно проверяйте поведение, которое раньше от них зависело.

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

Google: миграция на Gemini 3.8 Flash · Google: изменения Gemini 3.6 и 3.5 Flash-Lite

4. Явно задайте глубину рассуждений и проверьте ее

Gemini 3.8 Flash принимает low, medium и high; по умолчанию используется medium, а minimal не поддерживается. Не переносите настройку Flash-Lite без проверки. Маршрутизатор должен проверять пару «модель — уровень», а не добавлять одну конфигурацию всем моделям.

Ниже приведен невыполненный пример тела REST-запроса Interactions для синтетической задачи только на чтение. Адрес — POST https://generativelanguage.googleapis.com/v1beta/interactions, ключ должен храниться на сервере. Это иллюстрация формы запроса, а не рабочая конфигурация или замер. store=false несовместим с фоновым выполнением и последующим продолжением через previous_interaction_id; он не гарантирует отсутствие любого хранения у провайдера.

Сравните low и medium на одинаковых приемочных задачах, прежде чем повышать уровень. Ограничение вывода, тайм-аут и бюджет вызовов инструментов — отдельные механизмы. Короткий вывод может обрезать результат, поэтому им нельзя заменять настройку глубины рассуждений.

{
  "model": "gemini-3.8-flash",
  "store": false,
  "input": "Синтетический тест: перечисли повторяющиеся ID в [7, 3, 7]. Не вызывай внешние инструменты.",
  "generation_config": {
    "thinking_level": "low"
  }
}

Google: миграция на Gemini 3.8 Flash · Google: состояние Interactions, настройки хода и хранение · Google: эксперимент стоимости задачи от 3 ноября

5. Сохраняйте подписи на полном цикле инструментов

Подпись рассуждений — непрозрачное состояние протокола. Это не ответ, не исполняемая инструкция и не читаемая стенограмма рассуждений. В GenerateContent подпись может прикрепляться к частям контента. В Interactions нужное состояние передается шагами thought и определенными шагами встроенных инструментов. Восстановление истории только из видимого текста удаляет сведения, необходимые следующему ходу.

Для сохраненных Interactions сервер управляет этим состоянием через previous_interaction_id. При воспроизведении без состояния повторно передавайте полученные шаги thought без изменений, включая необходимые подписи встроенных инструментов. Различайте эти представления: не выдумывайте универсальное поле подписи, не переводите, не сокращайте и не восстанавливайте непрозрачное значение самостоятельно.

• Воспроизведите как минимум запрос пользователя, вызов инструмента, его результат и итоговый ответ. Одно приветствие не проверяет непрерывность состояния.
• Отдельно проверьте потоковый и обычный режим. Сохраняйте полные события протокола, включая дельту подписи: появление текста не означает завершения хода.
• Добавьте отрицательные случаи с удаленным thought, обрезанной подписью и сериализатором, отбрасывающим неизвестные поля. Записывайте реальную ошибку, не предполагая единый HTTP-код для всех API.

Google: рассуждения, подписи и состояние потока

6. Сопоставляйте результаты и предотвращайте повторные действия

В Interactions объект function_result связывается с вызовом через call_id и имя функции. Адаптер должен выдавать ровно один соответствующий результат для каждого вызова, включая явный результат ошибки. Не связывайте параллельные ответы только по позиции в массиве: имя функции может совпадать, а аргументы — различаться.

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

В Interactions параметры tools, system_instruction и generation_config действуют только на текущую операцию, даже при связанной истории. Нужные правила и настройки следует передавать заново на каждом ходе. Сохраненная беседа не доказывает наследование прежних разрешений инструментов или уровня thinking.

Google: вызовы функций и сопоставление результатов · Google: состояние Interactions, настройки хода и хранение

7. Проверяйте контракт результата и каждую модальность

Структурированный вывод ограничивает форму, но не истинность значения. На клиенте проверяйте идентификаторы, даты, арифметику, допустимые перечисления и бизнес-связи. Поддерживается подмножество JSON Schema, поэтому нельзя полностью перекладывать ограничения длины и уникальности на управляемое декодирование.

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

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

Google: структурированный вывод и ограничения схем · Google: возможности Gemini 3.8 Flash · Google: возможности Gemini 3.5 Flash-Lite

8. Постройте проверки, отвергающие правдоподобный ответ

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

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

Google: рассуждения, подписи и состояние потока · Google: вызовы функций и сопоставление результатов · Google: структурированный вывод и ограничения схем

9. Включайте неудачные попытки в стоимость принятой задачи

Инженерная статья Google от 3 ноября рассматривает маршрутизацию по стоимости успешно выполненной задачи. Эксперимент с 50 запросами, одним запуском каждой конфигурации и ограниченной оценкой — опубликованный провайдером пример, а не наш замер, независимый рейтинг или гарантия для рабочей среды. Полезный принцип — сравнивать задачу целиком, а не только цену токена.

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

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

стоимость_принятой_задачи = все_сверенные_расходы / принятые_задачи

# Предлагаемый журнал приложения; это не поля Gemini API
case_id, model, endpoint, sdk_version, prompt_digest
thinking_level, state_mode, tool_schema_digest
accepted, failure_category, latency_ms, retry_count
reconciled_cost, rate_date, cache_condition, intended_effects

Google: тарифы Gemini Developer API · Google: эксперимент стоимости задачи от 3 ноября

10. Добавляйте маршрутизатор после сравнения с простой базой

Сначала сравните несколько постоянных режимов: Flash-Lite для всех подходящих задач, 3.8 Flash low и 3.8 Flash medium. Сохраните требования к качеству и одинаковый набор. Только после этого проверяйте маршрутизатор между поддерживаемыми комбинациями. Иначе сложная система покажется дешевой лишь из-за неудачно настроенной базы.

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

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

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

Google: состояние Interactions, настройки хода и хранение · Google: эксперимент стоимости задачи от 3 ноября

11. Подготовьте резерв, действующий после 1 декабря

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

После объявленного перенаправления возврат настройки к gemini-2.5-pro или gemini-2.5-flash не восстановит старую модель. Реальный резерв — явно выбранная, еще поддерживаемая конфигурация, уже прошедшая нужные случаи, либо утвержденная очередь к человеку. Сохраненный старый адаптер не означает сохраненную доступность модели у провайдера.

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

Google: журнал Gemini API от 2 ноября · Google: устаревание, доступ и график маршрутизации

12. Оставьте воспроизводимую запись о миграции

Включите дату проверки источников, затронутые маршруты, точные конфигурации, хеши примеров, правила оценки, ошибки и ответственного за резерв. Разделяйте измерения и планы. Документы для этой статьи проверены 4 ноября 2026 года; тело запроса, матрицы и процесс выпуска — невыполненные примеры. Право доступа конкретного аккаунта, квоты, задержка и экономия не проверялись.

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

Проверь миграцию Gemini 2.5 без платных вызовов API и изменений рабочей среды.
1. Опиши ID моделей, endpoint, SDK, инструкции и адаптеры инструментов.
2. Сопоставь каждому маршруту поддерживаемую модель и явный thinking level.
3. Найди предзаполнение model, удаленные параметры и отброшенное состояние.
4. Предложи синтетические случаи параллельных/последовательных инструментов, неполного потока и повторных эффектов.
5. Подготовь матрицу приемки, журнал расходов и план проверки резерва.
Отдельно обозначь проверенное в коде, подтвержденное датированными официальными документами, выводы и неизвестное.

Google: журнал Gemini API от 2 ноября · Google: миграция на Gemini 3.8 Flash · Google: изменения Gemini 3.6 и 3.5 Flash-Lite · Google: ключи API, проекты и учетные данные