Como migrar do Gemini 3.8 Flash para o Hydrogen preservando o contexto

Migre do Gemini 3.8 Flash para o Hydrogen com raciocínio explícito, recuperação do cache, histórico de ferramentas e verificações de regressão e rollback.

Ilustração plana de um desvio ferroviário com uma peça laranja, representando a mudança de rota sem perder a conexão.

Para migrar do Gemini 3.8 Flash para o Gemini 4 Hydrogen, preserve o contrato da API e o contexto da aplicação, altere o ID do modelo, escolha explicitamente o nível de raciocínio e repita as verificações por tarefa antes de direcionar trabalho de produção. Trocar apenas o nome do modelo não recupera documentos associados a uma referência de cache incompatível nem comprova que uma conversa armazenada no servidor possa continuar com outro modelo.

Este guia trata de uma aplicação que já funciona. Para obter a primeira chave e enviar a primeira requisição, veja o guia da API do Hydrogen. Aqui vamos criar uma requisição pequena antes e depois da mudança, verificar a preservação do histórico e definir aceitação e rollback. Preservar o contexto significa executar as verificações e reconstruções necessárias; não é uma garantia de respostas idênticas dos dois modelos.

A documentação foi verificada em 14 de novembro de 2026. O kit disponível para download passou em 21 testes offline de auditoria de requisições e em uma verificação separada da serialização real do google-genai==3.3.0, usando transporte HTTP simulado. Não chamamos os modelos, não validamos uma conversa real entre modelos, não medimos qualidade e não comparamos faturas. Os critérios de regressão abaixo são uma proposta para sua aplicação, não resultados de benchmark medidos.

Identifique o que realmente muda

Leia as orientações de migração do Hydrogen junto com a documentação de lançamento do Gemini 3.8. Uma restrição repetida no novo checklist não é necessariamente uma incompatibilidade recém-introduzida. A documentação do Google vinculada neste guia está em inglês.

ÁreaComportamento anterior do Gemini 3.8 FlashDecisão para o Hydrogen
ID do modelo no Googlegemini-3.8-flashUsar gemini-4-hydrogen e confirmar separadamente o acesso da conta
Raciocínio padrãomediumO padrão passa a high; definir explicitamente para uma comparação controlada
Níveis disponíveislow, medium, highAdiciona xhigh; minimal já não era aceito no 3.8
Orçamento de contextoLimites de entrada e saída separadosEntrada, raciocínio e saída compartilham 1.048.576 tokens
Cache explícitoAuditar a dependência da requisição em um recurso de cacheNão suportado no Hydrogen; reconstruir o conteúdo antes de remover a referência
AmostragemJá descontinuada nas orientações de migração do 3.8Valores personalizados dentro da faixa são ignorados; fora dela ainda podem gerar erro 400 de validação
Saída longaA aplicação pode esperar uma única respostaAcima de 65.536 tokens por etapa síncrona, projetar execução em segundo plano ou continuação pelo cliente

Configurar medium no Hydrogen controla uma variável de configuração. Isso não estabelece raciocínio interno, latência ou qualidade equivalentes. Um teto maior de saída também não significa que uma entrada quase cheia deixe o mesmo espaço para a resposta. Calcule raciocínio e resposta dentro da janela compartilhada e mantenha os limites de saída e gasto da aplicação.

Documentação em inglês do Google com o checklist de migração do Gemini 3.8 Flash e notas sobre contexto, raciocínio, cache e amostragem.

Captura real da documentação de migração do Google em inglês. Ela registra a orientação da fonte, não uma migração bem-sucedida da API nem um teste de desempenho da Ofox.

Para os mecanismos de saída, consulte a documentação de long decode. Um limite por etapa é uma fronteira de projeto do controlador, não uma prova de que todo limite de saída maior solicitado seja inválido.

Preserve a configuração original e o mesmo protocolo

Antes de trocar o modelo, salve uma configuração original versionada e um conjunto pequeno de tarefas reproduzíveis. Registre modelo, endpoint, versão do SDK, instruções de sistema, montagem da entrada, ferramentas, esquema de resposta, limite de saída, armazenamento, política de repetição e campos de roteamento do provedor. Documentos originais e entradas cuja retenção é permitida devem ficar no armazenamento protegido habitual. Logs públicos de depuração não são um arquivo de migração.

Distinga três formatos de requisição:

Cliente existenteFronteira a preservarNão inserir diretamente
Google Interactionsinput, generation_config, etapas e IDs de interaçãoEstrutura GenerateContent com contents
Google GenerateContentcontents, partes de conteúdo, declarações de ferramentas e configuração do SDKprevious_interaction_id do Interactions no lugar do histórico do protocolo
Cliente Ofox compatível com OpenAIMensagens, roteamento e respostas documentadosRequisição nativa do Google Interactions sem adaptação

O exemplo completo abaixo usa Google Interactions. O teste separado de serialização do kit usa GenerateContent, pois verifica partes de conteúdo do modelo e respostas de ferramentas. São testes independentes; executar um não converte o outro protocolo.

Na aplicação Ofox, verifique primeiro a rota atual: Gemini Generate Content ou Chat Completions compatível com OpenAI. Use as instruções de chave e autenticação da Ofox correspondentes. Chaves do Google e da Ofox não são intercambiáveis. A documentação de uma rota nativa Gemini não comprova suporte a todos os recursos do Google Interactions ou ao cache específico de cada modelo.

Separe também clientes prontos de ferramentas e aplicações próprias. Se Cline ou OpenCode montar a requisição, siga o guia de configuração do Hydrogen em ferramentas de código e examine o que o cliente realmente envia. Não suponha que ele envie o JSON desta página.

Crie uma requisição pequena e explícita antes e depois

Escolha uma tarefa cuja resposta possa ser verificada sem outro modelo. O exemplo original contém dois estados de registros; apenas B está bloqueado. Salve este objeto completo em 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
    }
  }
}

Crie hydrogen-request.json, mantendo entrada, esquema e limite de saída, mas trocando o modelo e declarando o raciocínio:

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))

Os dois JSONs completos estão no kit. O limite de 8.192 tokens é uma configuração deste teste controlado, não uma recomendação universal para produção. Mesmo um JSON final curto pode falhar se o raciocínio consumir o orçamento. Verifique conclusão e truncamento; não eleve automaticamente o limite de produção ao máximo para esconder um problema.

O formato segue o contrato atual de saída estruturada do Google: texto com MIME application/json e esquema. O esquema restringe a forma, mas não prova que o registro certo foi escolhido.

Depois de configurar a chave do seu projeto Google em GEMINI_API_KEY pelo método habitual de gestão de segredos, você pode executar opcionalmente a requisição real abaixo. Ela contata o Google e pode consumir cota ou uso pago. Não a executamos para este artigo.

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

Repita o comando com source-request.json e outro arquivo de saída para obter a referência do modelo original. Mantenha conta, entrada, esquema e condições comparáveis. Primeiro examine status da interação, erros e resultados incompletos. Somente uma resposta concluída com a saída esperada deve chegar ao parser da aplicação. Analise o texto JSON e exija exatamente {"blocked_ids":["B"]}, sem outras chaves ou IDs. HTTP 200, JSON válido e resposta correta são três verificações distintas.

Em caso de timeout, preserve os identificadores disponíveis da requisição ou interação e examine o estado do serviço antes de repetir. Timeout no cliente não comprova que o servidor parou de trabalhar.

Execute o kit offline e entenda seus limites

Baixe o kit de migração do Hydrogen, extraia e entre no diretório hydrogen-migration-kit. O README do kit está em inglês. Use Python 3.11 ou mais recente para o conjunto completo. O auditor de requisições precisa apenas da biblioteca padrão:

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

O resultado esperado é 21 testes aprovados. O auditor não reescreve o arquivo: devolve uma cópia inalterada com bloqueios e itens de revisão. Código de saída 2 indica bloqueios; 0 significa apenas que essa auditoria limitada não encontrou um bloqueio, não que o rollout está aprovado. O exemplo de destino ainda exige avaliação da aplicação e revisão do limite de saída intencionalmente reduzido.

O alvo é uma requisição inicial completa do Interactions. São verificados formatos de outro protocolo, entrada ausente, dependências de cache explícito, níveis de raciocínio inválidos, limites de saída incorretos e conflitos entre armazenamento e execução em segundo plano. Mudanças escondidas por padrões também são sinalizadas. O auditor não recupera documentos, não inspeciona histórico do servidor, não confirma permissões da conta nem valida todos os campos possíveis do serviço.

A saída contém a cópia integral da requisição. Comece pelo exemplo sem dados sensíveis e evite prompts confidenciais em logs compartilhados de terminal. A chave de API não deve estar no JSON.

Para a verificação separada de serialização do SDK, crie um ambiente isolado:

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

No Windows PowerShell, ative com .venv\Scripts\Activate.ps1. A instalação baixa dependências; a verificação usa uma chave explicitamente fictícia e httpx.MockTransport, não lê credenciais do ambiente e não envia chamadas ao modelo.

O script serializa duas requisições GenerateContent pelo SDK instalado. Verifica a preservação dos mesmos três turnos de histórico, declarações de ferramentas e duas respostas de ferramentas. O turno do modelo contém duas chamadas paralelas; uma assinatura sintética permanece na primeira parte original e não é copiada para a segunda. O destino usa Hydrogen e MEDIUM explícito. Os corpos capturados ficam em sdk-wire-requests.json, ao lado do script.

Isso é evidência da serialização local. Resposta e assinatura sintéticas não comprovam aceitação pelo servidor, continuação entre modelos ou funcionamento do executor. A verificação ajuda a detectar perda acidental de histórico antes da avaliação real, mas não a substitui.

Recupere o cache e preserve o estado da conversa

Um ID de cache explícito é uma referência, não o documento. Excluir cached_content ou cachedContent pode simplificar a aparência da requisição enquanto remove silenciosamente material necessário. A documentação de cache do Google distingue reutilização implícita de recursos explícitos gerenciados. Cache implícito não reconstrói uma entrada que não foi enviada.

Para cada tarefa dependente de cache:

  1. Localize as instruções de sistema, documentos, referências de mídia e declarações de ferramentas originais usados pela aplicação na criação do cache. Se não puder recuperá-los, interrompa esse caso de migração; uma substituição vazia não é equivalente.
  2. Registre versões e ordem. Confirme se arquivos externos continuam acessíveis pela conta e rota de destino.
  3. Reconstrua uma requisição completa nos campos do protocolo atual. Preserve a distinção entre sistema e usuário e as ferramentas; não achate tudo em uma mensagem de usuário apenas para remover o ID.
  4. Recalcule o contexto recuperado dentro do orçamento compartilhado do Hydrogen, reservando espaço para raciocínio e resposta. Divida a tarefa se necessário.
  5. Faça uma pergunta que dependa de um fato conhecido no material restaurado. Verifique a resposta exata antes de retirar a rota antiga dependente de cache.

O estado da conversa exige decisão separada. No Interactions, previous_interaction_id referencia uma interação anterior armazenada. Usar store=false na requisição atual não impede por si só a leitura do estado previamente salvo, mas o novo resultado não fica armazenado para a próxima continuação. Execução em segundo plano é incompatível com store=false. A existência de um ID antigo não demonstra suporte entre modelos: teste a combinação de conta e modelos ou inicie uma conversa nova de teste com contexto explicitamente reconstruído.

Na continuação sem estado, retenha a sequência completa exigida, incluindo etapas de raciocínio e assinaturas de ferramentas integradas. Em GenerateContent, preserve todo o conteúdo do modelo e suas partes em ordem, seguido das respostas correspondentes das ferramentas. O texto visível de uma conversa não é um armazenamento suficiente do histórico.

Para erro de assinatura ausente, consulte o guia de falhas de thought signature do Gemini (em inglês) e as regras oficiais de assinatura. Cada assinatura deve permanecer na parte original. Não copie a mesma assinatura para chamadas paralelas nem invente uma substituta. A assinatura sintética do kit existe somente para detectar erros locais de serialização.

Verifique ferramentas, resultado e orçamento em conjunto

Uma requisição pode preservar todo o texto e ainda perder o comportamento da aplicação. Mantenha nomes de funções, esquemas de argumentos, permissões, associações entre chamadas e resultados e a ordem dos resultados. O guia de function calling do Google descreve o protocolo; o executor ainda precisa decidir quais operações são permitidas e se cada uma realmente funcionou.

Comece por um teste somente de leitura. Por exemplo, lookup_record retorna ready para A e blocked para B, e a resposta estruturada deve selecionar B. Registre IDs de chamadas, argumentos e resultados sem segredos. Se houver duas chamadas, devolva dois resultados correspondentes, não um resumo livre que perca a associação.

Trate a saída do modelo como dados propostos para validação. No exemplo, valide o esquema e confronte a resposta com os registros conhecidos. Em operações de escrita, confira o estado real do destino. “Salvo com sucesso” no texto gerado não prova uma escrita. Para execução em interface, o guia de Computer Use aborda o ciclo adicional de observar, aprovar, executar e verificar.

Falhas de orçamento podem parecer falhas de tarefa. Capture uso de entrada, saída, raciocínio quando informado, estado de conclusão e sinais de truncamento. Uso ausente é desconhecido, não zero. Se o total de saída do provedor já inclui raciocínio, não o some outra vez. Confira as unidades documentadas antes de calcular custos.

Para respostas longas, escolha explicitamente o controlador de continuação ou a rota em segundo plano e seus critérios de parada. Preserve o identificador de retomada, evite repetir efeitos já executados e limite o trabalho total entre etapas. Aumentar um único limite sem mudar o controlador não cria uma tarefa longa confiável.

Monte uma regressão com critérios independentes

Parta de casos reais da aplicação, sem segredos e com acesso adequado. Inclua sucessos e limites conhecidos de falha. A tabela é um projeto reproduzível de uma bateria pequena; não contém resultados medidos de modelos.

CasoExemplo concretoCritério de aprovação
Extração básicaA=ready; B=blockedResposta concluída contém apenas o ID bloqueado B após o parsing
Recuperação de cacheDocumento contém release_owner=team_amber, mas a pergunta nãoApós restaurar o documento completo, a resposta é team_amber
Continuidade do históricoPrimeiro turno atribui A a team_amber; o seguinte pergunta o responsávelO mecanismo de estado escolhido retorna o responsável correto
Ferramentas paralelasDois lookup_record para A e BAssociações preservadas, sem execução duplicada e resultado coerente
Truncamento controladoLimite deliberadamente insuficiente em exemplo maiorAplicação detecta saída incompleta e não a aprova
Configuração inválidaAmostragem fora da faixa ou conflito entre armazenamento e segundo planoErro segue o tratamento correto, sem repetição incondicional
Rollback com escritaID da operação registrado, resposta do cliente incertaOperador ou executor inspeciona o destino antes de repetir

Em cada execução, salve versão da configuração, ID do modelo, hash do prompt ou exemplo, versão do SDK, conta ou ambiente de roteamento, início e fim, status, resultado do validador e uso disponível. Respostas brutas sensíveis seguem a política normal de retenção. Compare condições equivalentes; não atribua uma melhora apenas ao modelo se também mudou prompt, esquema e executor.

Defina a aceitação antes de avaliar com custo ou consumo de cota. Validade do esquema e segurança dos efeitos podem exigir regras estritas. Precisão, latência e custo precisam de limites adequados à aplicação e uma amostra significativa. Este artigo não oferece uma porcentagem universal nem considera sete exemplos prova de confiabilidade em produção. Examine divergências individualmente, sobretudo respostas plausíveis que falhem em uma verificação determinística.

Amplie gradualmente e mantenha um rollback utilizável

Primeiro direcione um conjunto limitado de novas tarefas de leitura para o Hydrogen. Mantenha as configurações original e de destino selecionáveis separadamente, usando as mesmas versões aprovadas dos exemplos. Revise erros e respostas incompletas antes de ampliar o teste. Adicione tarefas de escrita somente após verificar executor, deduplicação e estado do destino.

Corrija requisições malformadas em vez de repeti-las sem mudança. Se faltar acesso, confira conta, rota e ID exatos. Para falhas transitórias, use repetições limitadas com backoff e retenha identificadores. Clientes Ofox devem seguir o tratamento documentado de erros e novas tentativas. O diagnóstico de erros da API Gemini 4 ajuda a separar acesso, formato e limite de taxa, mas os exemplos específicos usam Argon: não copie esses IDs como se fossem Hydrogen.

Rollback restaura a configuração original para novas tarefas elegíveis, não repete cegamente todas as interações em andamento. Pause novos efeitos, identifique operações incertas, inspecione o destino e só então decida retomar, compensar ou reiniciar. A rota antiga só funciona enquanto acesso e disponibilidade do modelo forem válidos; um arquivo salvo não contorna descontinuação ou perda de permissão.

A migração está pronta quando a aplicação demonstra, na rota real, recuperação de contexto, preservação do estado das ferramentas, validação correta, execução limitada e rollback ensaiado. Guarde evidências versionadas para distinguir este salto de modelo de futuras mudanças de prompt, SDK ou provedor.