Как перейти с Gemini 3.8 Flash на Hydrogen и сохранить контекст

Миграция с Gemini 3.8 Flash на Hydrogen: явный уровень рассуждений, восстановление кеша, история инструментов, регрессионные проверки и откат.

Плоская иллюстрация железнодорожной стрелки с оранжевым элементом: смена маршрута с сохранением соединения.

Для перехода с Gemini 3.8 Flash на Gemini 4 Hydrogen сохраните контракт API и контекст приложения, замените ID модели, явно задайте уровень рассуждений и повторите проверки результатов задач до переключения рабочего трафика. Одна замена имени модели не восстанавливает документы за неподдерживаемой ссылкой на кеш и не доказывает, что сохранённый на сервере диалог можно продолжить другой моделью.

Это руководство для уже работающего приложения. Получение первого ключа и начальный запрос описаны в руководстве по API Hydrogen. Здесь мы подготовим небольшой запрос до и после перехода, проверим сохранение истории и определим приёмку и откат. Сохранение контекста означает необходимые проверки и восстановление данных, а не гарантию одинаковых ответов двух моделей.

Документация проверена 14 ноября 2026 года. Документы Google, на которые мы ссылаемся, — на английском. Набор для скачивания прошёл 21 автономный тест аудита запросов и отдельную проверку реальной сериализации google-genai==3.3.0 через имитацию HTTP-транспорта. Мы не вызывали модели, не проверяли реальное продолжение диалога между моделями, не измеряли качество и не сравнивали счета. Критерии ниже — план проверок вашего приложения, а не опубликованные результаты бенчмарка.

Отделите реальные изменения от прежних ограничений

Читайте инструкции по переходу на Hydrogen вместе с документацией выпуска Gemini 3.8. Повторение ограничения в новом списке не означает, что оно появилось только сейчас.

ОбластьПрежнее поведение Gemini 3.8 FlashРешение при переходе на Hydrogen
ID модели в Googlegemini-3.8-flashУказать gemini-4-hydrogen и отдельно проверить доступ целевого аккаунта
Уровень рассуждений по умолчаниюmediumТеперь high; для контролируемого сравнения задайте уровень явно
Доступные уровниlow, medium, highДобавлен xhigh; minimal не поддерживался уже в 3.8
Бюджет контекстаЛимиты входа и выхода раздельныеВход, рассуждения и выход делят окно в 1 048 576 токенов
Явное кешированиеПроверьте зависимость запроса от ресурса кешаHydrogen его не поддерживает; восстановите содержимое до удаления ссылки
Параметры семплированияУже объявлены устаревающими в руководстве 3.8Значения внутри допустимого диапазона игнорируются; выход за границы всё ещё может вызвать ошибку 400
Длинный ответПриложение может ожидать один ответСвыше 65 536 токенов на один синхронный этап нужны фоновый режим или продолжение на клиенте

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

Английская документация Google: список перехода с Gemini 3.8 Flash с пояснениями о контексте, рассуждениях, кеше и семплировании.

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

Механизм длинного вывода описан в документации Google по long decode. Лимит одного этапа — граница, которую должен учитывать контроллер, а не доказательство недопустимости любого большего значения выходного лимита.

Зафиксируйте исходную конфигурацию и сохраните протокол

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

Различайте три формы запросов:

Текущий клиентЧто сохранятьЧто нельзя подставлять напрямую
Google Interactionsinput, generation_config, шаги и ID взаимодействийОболочку GenerateContent с contents
Google GenerateContentcontents, части содержимого, объявления инструментов, конфигурацию SDKprevious_interaction_id из Interactions вместо истории этого протокола
OpenAI-совместимый клиент OfoxДокументированные сообщения, маршрутизацию моделей и ответыНативный запрос Google Interactions без преобразования

Полный пример далее использует Google Interactions. Отдельный тест сериализации в комплекте использует GenerateContent, поскольку проверяет части ответа модели и результаты инструментов. Это независимые проверки: запуск одной не преобразует другой протокол.

В приложении Ofox сначала уточните используемый маршрут: Gemini Generate Content либо OpenAI-совместимый Chat Completions. Следуйте соответствующим инструкциям по ключам и аутентификации Ofox. Ключи Google и Ofox не взаимозаменяемы. Наличие нативного маршрута Gemini в документации Ofox не подтверждает поддержку всех функций Google Interactions или кеширования конкретной модели.

Отделяйте миграцию приложения от настройки готового инструмента. Если запрос строит Cline или OpenCode, используйте руководство по подключению Hydrogen к инструментам разработки и изучите фактический запрос клиента. Не считайте, что он отправляет именно JSON из этой статьи.

Подготовьте небольшой запрос до и после перехода

Выберите задачу с ответом, который можно проверить без другой модели. В исходном примере две записи; заблокирована только B. Сохраните полный объект в source-request.json:

{
  "model": "gemini-3.8-flash",
  "input": "Records: A=ready; B=blocked. Return the blocked record IDs only.",
  "generation_config": {
    "max_output_tokens": 8192
  },
  "response_format": {
    "type": "text",
    "mime_type": "application/json",
    "schema": {
      "type": "object",
      "properties": {
        "blocked_ids": {"type": "array", "items": {"type": "string"}}
      },
      "required": ["blocked_ids"],
      "additionalProperties": false
    }
  }
}

Создайте hydrogen-request.json, сохранив вход, схему и выходной лимит, но изменив модель и явно указав уровень рассуждений:

import json
from pathlib import Path

source = json.loads(Path("source-request.json").read_text())
target = json.loads(json.dumps(source))
target["model"] = "gemini-4-hydrogen"
target["generation_config"]["thinking_level"] = "medium"
Path("hydrogen-request.json").write_text(json.dumps(target, indent=2))

Оба полных JSON-файла входят в комплект. Лимит 8192 токена — настройка этого контролируемого примера, не универсальная рекомендация для production. Даже короткий итоговый JSON может не сформироваться, если рассуждения исчерпают бюджет. Проверяйте завершение и обрезку; не увеличивайте лимит рабочего приложения до максимума автоматически, чтобы скрыть сбой.

Формат соответствует текущему контракту структурированного вывода Google: текст с MIME-типом application/json и схемой. Схема ограничивает структуру, но не доказывает выбор правильной записи.

Настроив ключ собственного проекта Google в GEMINI_API_KEY обычным способом управления секретами, можно выполнить следующий необязательный реальный запрос. Он обращается к Google и может расходовать квоту или платный объём. В рамках статьи мы его не выполняли.

curl --fail-with-body --max-time 180 \
  'https://generativelanguage.googleapis.com/v1beta/interactions' \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @hydrogen-request.json \
  --output hydrogen-response.json

Для исходной точки сравнения повторите команду с source-request.json и другим выходным файлом. Аккаунт, вход, схема и условия выполнения должны быть сопоставимы. Сначала проверьте статус взаимодействия, ошибки и незавершённость. В парсер приложения должен попадать только завершённый ответ с ожидаемым выходом. Разберите JSON-текст и потребуйте точно {"blocked_ids":["B"]}, без лишних ключей и ID. HTTP 200, корректный JSON и правильный ответ на задачу — три отдельные проверки.

При тайм-ауте сохраните доступные ID запроса или взаимодействия и уточните состояние сервиса до повтора. Клиентский тайм-аут сам по себе не доказывает остановку обработки на сервере.

Запустите автономные проверки и учитывайте их границы

Скачайте комплект миграции Hydrogen, распакуйте и перейдите в каталог hydrogen-migration-kit. Для всех инструментов вместе используйте Python 3.11 или новее. Комментарии в коде и README написаны по-английски. Сам аудитор запроса требует только стандартную библиотеку:

python -m unittest test_audit.py -v
python migration_audit.py source-request.json
python migration_audit.py hydrogen-request.json

Ожидаемый результат — 21 успешный тест. Аудитор не переписывает файл: он возвращает неизменённую копию с блокирующими замечаниями и пунктами для проверки. Код выхода 2 означает блокирующие проблемы; 0 означает лишь отсутствие таких проблем в пределах этого аудита, а не разрешение на выпуск. Например, целевой пример всё ещё требует оценки приложения и проверки намеренно ограниченного выходного бюджета.

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

Вывод включает полную копию запроса. Начните с безопасного примера из комплекта и не отправляйте конфиденциальные промпты в общие терминальные журналы. API-ключ не должен находиться в JSON запроса.

Для отдельной проверки сериализации SDK создайте изолированное окружение:

python -m venv .venv
source .venv/bin/activate
python -m pip install 'google-genai==3.3.0' httpx
python sdk_wire_check.py

В Windows PowerShell используйте .venv\Scripts\Activate.ps1. Установка пакетов скачивает зависимости; сама проверка использует явно вымышленный ключ и httpx.MockTransport, не читает секреты из окружения и не отправляет запрос модели.

Скрипт сериализует два запроса GenerateContent через установленный SDK. Он проверяет сохранение одинаковых трёх ходов истории, объявлений инструментов и двух результатов вызовов. В ходе модели два параллельных вызова; синтетическая подпись остаётся на исходной первой части и не копируется во вторую. В целевом запросе заданы Hydrogen и явный MEDIUM. Захваченные тела доступны в sdk-wire-requests.json рядом со скриптом.

Это свидетельство о локальной сериализации. Синтетические ответ и подпись не подтверждают принятие сервером, продолжение диалога другой моделью или работу исполнителя инструментов. Проверка полезна для обнаружения потерянной истории до реальной оценки, но не заменяет её.

Восстановите кеш и сохраните состояние диалога

ID явного кеша — ссылка, а не сам документ. Удаление cached_content или cachedContent может упростить вид запроса и незаметно убрать необходимые материалы. Документация Google о кешировании различает неявное повторное использование и управляемые явные ресурсы; неявный кеш не восстанавливает отсутствующий вход.

Для каждой задачи, зависящей от кеша:

  1. Найдите принадлежащие приложению исходные системные инструкции, документы, медиассылки и объявления инструментов, использованные при создании кеша. Если восстановить их нельзя, остановите этот случай миграции, а не считайте пустую замену эквивалентной.
  2. Зафиксируйте версии и порядок. Проверьте доступность внешних файлов целевому аккаунту и маршруту.
  3. Соберите полный запрос в полях своего протокола. Сохраните различие system/user и инструменты; не превращайте всё в одно сообщение пользователя только ради удаления ID кеша.
  4. Пересчитайте восстановленный контекст в общем окне Hydrogen, оставив место для рассуждений и ответа. При необходимости разделите задачу.
  5. Задайте вопрос, требующий известного факта из восстановленного материала. Проверьте точный ответ до отключения старого пути с кешем.

Состояние диалога требует отдельного решения. В Interactions сохранённое предыдущее взаимодействие доступно через previous_interaction_id. store=false в текущем запросе само по себе не запрещает чтение ранее сохранённого состояния, но новый результат не сохраняется для следующего продолжения. Фоновый режим несовместим с store=false. Наличие старого ID не доказывает поддержку продолжения между моделями: проверьте конкретный аккаунт и пару моделей либо начните новый пробный диалог с явно восстановленным контекстом.

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

При ошибке отсутствующей подписи используйте разбор ошибок thought signature в Gemini и официальные правила подписей. Подпись должна оставаться на исходной части. Не копируйте одну подпись в параллельные вызовы и не придумывайте замену. В комплекте синтетическая подпись нужна только для выявления ошибок сериализатора.

Проверяйте инструменты, результат и общий бюджет вместе

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

Сначала используйте read-only-пример. Пусть lookup_record возвращает ready для A и blocked для B; итоговый структурированный ответ должен выбрать B. Записывайте ID вызовов, аргументы и результаты без секретов. Если модель выдала два вызова, верните два соответствующих результата, а не общее свободное резюме, в котором потеряна связь.

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

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

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

Создайте регрессионный набор с независимыми критериями

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

СлучайКонкретный примерУсловие успеха
Базовое извлечениеA=ready; B=blockedЗавершённый ответ разбирается в единственный заблокированный ID B
Восстановление кешаВ документе есть release_owner=team_amber, но в вопросе факта нетПосле восстановления полного документа получен team_amber
Непрерывность историиПервый ход назначает A команде team_amber, следующий спрашивает владельцаВыбранный механизм состояния возвращает правильного владельца
Параллельные инструментыДва lookup_record для A и BСвязи сохранены, повторного исполнения нет, итог соответствует данным
Контролируемая обрезкаЗаведомо малый лимит для более крупного примераПриложение распознаёт незавершённость и не принимает результат
Неверная конфигурацияЗначение семплирования вне диапазона или несовместимые хранение/фонОшибка обработана нужной веткой, без бесконечного повтора
Откат с записьюID операции сохранён, ответ клиента неопределёнДо повтора исполнитель или оператор проверяет состояние назначения

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

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

Расширяйте трафик постепенно и сохраняйте рабочий откат

Сначала направьте в Hydrogen ограниченное число новых read-only-задач. Исходная и целевая конфигурации должны выбираться отдельно и использовать одинаковые утверждённые версии примеров. До расширения проверьте ошибки и незавершённые ответы. Задачи с записью добавляйте после проверки исполнителя, дедупликации и состояния назначения.

Неверный запрос исправляют, а не повторяют без изменений. При отсутствии доступа проверяйте точный аккаунт, маршрут и ID. Для временных сбоев используйте ограниченные повторы с задержкой и сохраняйте идентификаторы. Клиентам Ofox следует соблюдать документированную обработку ошибок и повторов. Диагностика ошибок API Gemini 4 помогает различать доступ, формат и лимиты, но её модельные примеры используют Argon: нельзя копировать эти ID как Hydrogen.

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

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