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.
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.
| Área | Comportamento anterior do Gemini 3.8 Flash | Decisão para o Hydrogen |
|---|---|---|
| ID do modelo no Google | gemini-3.8-flash | Usar gemini-4-hydrogen e confirmar separadamente o acesso da conta |
| Raciocínio padrão | medium | O padrão passa a high; definir explicitamente para uma comparação controlada |
| Níveis disponíveis | low, medium, high | Adiciona xhigh; minimal já não era aceito no 3.8 |
| Orçamento de contexto | Limites de entrada e saída separados | Entrada, raciocínio e saída compartilham 1.048.576 tokens |
| Cache explícito | Auditar a dependência da requisição em um recurso de cache | Não suportado no Hydrogen; reconstruir o conteúdo antes de remover a referência |
| Amostragem | Já descontinuada nas orientações de migração do 3.8 | Valores personalizados dentro da faixa são ignorados; fora dela ainda podem gerar erro 400 de validação |
| Saída longa | A aplicação pode esperar uma única resposta | Acima 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.

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 existente | Fronteira a preservar | Não inserir diretamente |
|---|---|---|
| Google Interactions | input, generation_config, etapas e IDs de interação | Estrutura GenerateContent com contents |
| Google GenerateContent | contents, partes de conteúdo, declarações de ferramentas e configuração do SDK | previous_interaction_id do Interactions no lugar do histórico do protocolo |
| Cliente Ofox compatível com OpenAI | Mensagens, roteamento e respostas documentados | Requisiçã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:
- 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.
- Registre versões e ordem. Confirme se arquivos externos continuam acessíveis pela conta e rota de destino.
- 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.
- 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.
- 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.
| Caso | Exemplo concreto | Critério de aprovação |
|---|---|---|
| Extração básica | A=ready; B=blocked | Resposta concluída contém apenas o ID bloqueado B após o parsing |
| Recuperação de cache | Documento contém release_owner=team_amber, mas a pergunta não | Após restaurar o documento completo, a resposta é team_amber |
| Continuidade do histórico | Primeiro turno atribui A a team_amber; o seguinte pergunta o responsável | O mecanismo de estado escolhido retorna o responsável correto |
| Ferramentas paralelas | Dois lookup_record para A e B | Associações preservadas, sem execução duplicada e resultado coerente |
| Truncamento controlado | Limite deliberadamente insuficiente em exemplo maior | Aplicação detecta saída incompleta e não a aprova |
| Configuração inválida | Amostragem fora da faixa ou conflito entre armazenamento e segundo plano | Erro segue o tratamento correto, sem repetição incondicional |
| Rollback com escrita | ID da operação registrado, resposta do cliente incerta | Operador 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.


