Migrar para os modelos mais recentes do Gemini

Este guia explica como atualizar seu aplicativo para a versão mais recente do Gemini. Este guia pressupõe que seu aplicativo já usa uma versão mais antiga do Gemini. Para saber como começar a usar o Gemini na Gemini Enterprise Agent Platform, consulte Começar a usar a Gemini Enterprise Agent Platform.

Este guia não aborda como mudar seu aplicativo do SDK da Vertex AI para o SDK de IA Generativa do Google atual. Para mais informações, consulte nosso guia de migração do SDK da Vertex AI.

Quais mudanças devo esperar?

A atualização da maioria dos aplicativos de IA generativa para a versão mais recente do Gemini requer poucas mudanças no código ou no comando. No entanto, alguns aplicativos podem exigir ajustes de comandos. É difícil prever essas mudanças sem antes testar os comandos com a nova versão. Recomendamos fazer testes completos antes de migrar totalmente. Para dicas sobre como criar comandos eficazes, consulte nossas orientações sobre estratégia de comandos. Use nossa lista de verificação de integridade de comandos para encontrar e corrigir problemas de comandos.

Atualização do relatório de contagem de tokens

É possível que você observe um aumento esperado nas contagens de tokens informadas, já que nossa infraestrutura atualizada agora captura com precisão todos os componentes de solicitação, incluindo metadados complexos, como esquemas de resposta e chamadas de função, que antes eram subcontados pelo sistema legado.

Você só precisa fazer grandes mudanças no código para determinadas alterações interruptivas ou para usar novos recursos do Gemini.

Para qual modelo do Gemini devo migrar?

O modelo do Gemini que você usa depende das necessidades do seu aplicativo:

Recurso	3.1 Pro	3.5 Flash Lite	3.5 Flash	3.6 Flash	3.7 Flash	3.8 Flash	4 Argon
Etapa do lançamento	Visualizar	GA	Disponibilidade geral	Disponibilidade geral	Disponibilidade geral	Disponibilidade geral	GA
Modalidades de entrada	Texto, Imagem, Áudio, Vídeo	Texto, Imagem, Áudio, Vídeo	Texto, Imagem, Áudio, Vídeo	Texto, Imagem, Áudio, Vídeo	Texto, Imagem, Áudio, Vídeo	Texto, Imagem, Áudio, Vídeo	Texto, Imagem, Áudio, Vídeo
Modalidades de saída	Texto	Texto	Texto	Texto	Texto	Texto	Texto
Janela de contexto, limite total de tokens	1.048.576	1.048.576	1.048.576	1.048.576	1.048.576	1.048.576	1.048.576
Tamanho do contexto de saída	65.536	65.536	65.536	65.536	65.536	65.536	1.048.576
Embasamento com a Pesquisa Google
Chamadas de função
Execução de código
Armazenamento em cache de contexto implícito
Armazenamento em cache de contexto explícito
Inferência em lote
API Gemini Live
Ajustes detalhados
Latência
Data de desativação		21 de julho de 2027 ou depois	19 de maio de 2027 ou posterior	19 de novembro de 2026	28 de janeiro de 2027	2 de setembro de 2027 ou depois	13 de outubro de 2027 ou depois

Antes de começar a migração

Antes de iniciar o processo de migração, considere o seguinte:

• Segurança das informações (InfoSec), governança e aprovações regulatórias
• Disponibilidade por local
• Diferenças de preços com base na modalidade e na tokenização
• Comprar ou alterar pedidos de Capacidade de Processamento Provisionada
• Ajuste supervisionado
• Teste de regressão

Como migrar para a versão mais recente

As seções a seguir descrevem as etapas para migrar para a versão mais recente do Gemini. Para garantir os melhores resultados, siga estas etapas na ordem.

1. Requisitos de avaliação e teste do modelo de documento

1. Prepare-se para repetir as avaliações relevantes que você realizou quando criou o aplicativo, além de todas as avaliações realizadas desde então.
2. Se as avaliações atuais não cobrirem ou medirem totalmente todas as tarefas que o aplicativo realiza, projete e prepare mais avaliações. Use nosso manual de avaliação e nossas receitas de avaliação para começar.
3. Se o aplicativo envolve RAG, uso de ferramentas, Agentic Workflows complexos ou encadeamento de comandos, verifique se os dados de avaliação atuais permitem avaliar cada componente de forma independente. Se não, reúna exemplos de entrada e saída para cada componente.
4. Se o aplicativo for crítico ou parte de um sistema maior em tempo real voltado ao usuário, inclua a avaliação on-line.

2. Fazer upgrades de código e executar testes

Para fazer upgrade do código, é preciso fazer três mudanças principais:

• Fazer upgrade para o SDK de IA Generativa do Google
• Mudar as configurações do Gemini Chamadas
• Corrigir mudanças interruptivas no código

As seções a seguir detalham essas mudanças.

Fazer upgrade para o SDK de IA generativa do Google

Se o aplicativo do Gemini 1.x usa o SDK da Vertex AI, mude para o SDK de IA generativa do Google. Consulte nosso guia de migração do SDK da Vertex AI para mais detalhes, incluindo exemplos de código para fazer chamadas semelhantes com o SDK de IA Generativa do Google. As versões do SDK da Vertex AI lançadas após junho de 2026 não serão compatíveis com o Gemini, e os novos recursos do Gemini estarão disponíveis apenas no SDK de IA Generativa do Google.

Recomendamos atualizar para a versão 2.0.0 ou mais recente do SDK do google-genai para aproveitar todos os novos recursos do Gemini 3.5 Flash e de modelos mais recentes.

Se você não conhece o SDK de IA generativa do Google, consulte o notebook Introdução à IA generativa do Google usando o SDK de IA generativa do Google.

Mudar as chamadas do Gemini

Atualize seu código de previsão para usar um dos modelos do Gemini mais recentes. No mínimo, isso significa mudar o nome do endpoint do modelo.

As mudanças exatas no código variam de acordo com a forma como você criou o aplicativo, especialmente se você usou o SDK de IA generativa do Google ou o SDK da Vertex AI.

Depois de fazer mudanças no código, execute testes de regressão de código e outros testes de software para garantir que o código funcione conforme o esperado. Essa etapa verifica se o código funciona, mas não a qualidade das respostas do modelo.

Corrigir mudanças de código que causam falhas

• Recuperação dinâmica: mude para o embasamento com a Pesquisa Google. Esse recurso requer o SDK de IA generativa do Google e não é compatível com o SDK da Vertex AI.
• Filtros de conteúdo: observe as configurações padrão do filtro de conteúdo. Mude o código se ele depender de um padrão que foi alterado.
• Parâmetro de amostragem de token Top-K: os modelos após gemini-1.0-pro-vision não permitem mudar o parâmetro Top-K.
• Raciocínio: o Gemini 3 Pro e os modelos mais recentes usam o parâmetro thinking_level em vez de thinking_budget. Para mais informações, consulte Controlar o pensamento do modelo.
• Assinaturas de pensamento: para os modelos Gemini 3 Pro e mais recentes, se uma assinatura de pensamento for esperada em uma rodada, mas não for fornecida, o modelo vai retornar um erro em vez de um aviso. Consulte Assinaturas de raciocínio.
• Resolução e tokenização de mídia: o Gemini 3 Pro e os modelos mais recentes usam um comprimento de sequência variável para a tokenização de mídia em vez de Pan and Scan, além de terem novas resoluções padrão e custos de token para imagens, PDFs e vídeos. Consulte Compreensão de imagens e Compreensão de vídeos.
• Metadados de uso: para o Gemini 3 Pro e modelos mais recentes, as contagens de tokens de PDF em usage_metadata são informadas na modalidade IMAGE em vez de DOCUMENT.
• Segmentação de imagens: não é compatível com o Gemini 3 Pro e modelos mais recentes.
• Respostas de funções multimodais: para o Gemini 3 Pro e modelos mais recentes, é possível incluir dados de imagem e PDF nas respostas de funções. Consulte Respostas de funções multimodais.
• Processamento de PDF: para o Gemini 3 Pro e modelos mais recentes, o OCR não é usado por padrão ao processar PDFs digitalizados.

Nesta etapa, concentre-se apenas nas mudanças de código. Talvez seja necessário fazer outras mudanças mais tarde, mas aguarde até iniciar a avaliação. Depois das avaliações, considere estes ajustes com base nos resultados:

• Se você estiver migrando da recuperação dinâmica, talvez seja necessário ajustar as instruções do sistema para controlar quando a Pesquisa Google é usada (por exemplo, "Only generate queries for the Google Search tool if the user asks about sports. Don't generate queries for any other topic."). No entanto, aguarde até avaliar antes de mudar os comandos.
• Se você usou o parâmetro Top-K, ajuste outros parâmetros de amostragem de token, como Top-P, para receber resultados semelhantes.

3. Executar avaliações off-line

Repita as avaliações que você realizou quando desenvolveu e lançou o aplicativo pela primeira vez, todas as avaliações off-line feitas desde então e todas as avaliações adicionais identificadas na etapa 1. Se você ainda achar que a avaliação não abrange totalmente o escopo do aplicativo, faça outras avaliações.

Se você não tiver uma maneira automatizada de executar avaliações off-line, use o serviço de avaliação de IA generativa.

Se o aplicativo usa ajuste, faça uma avaliação off-line antes de ajustar o modelo novamente com a versão mais recente do Gemini. Os modelos mais recentes oferecem uma qualidade de saída melhor, o que pode significar que seu aplicativo não precisa mais de um modelo ajustado.

4. Avaliar os resultados da avaliação e ajustar os comandos e hiperparâmetros

Se a avaliação off-line mostrar que o aplicativo está com um desempenho menos eficaz, melhore-o até que o desempenho corresponda ao modelo mais antigo. Para isso:

• Refinar os comandos de forma iterativa para melhorar o desempenho ("Hill Climbing"). Se você não conhece o hill climbing, consulte o treinamento on-line sobre hill climbing do Vertex Gemini. O otimizador de comandos da Gemini Enterprise Agent Platform (notebook de exemplo) também pode ajudar.
• Se o aplicativo for afetado pelas alterações interruptivas de recuperação dinâmica e Top-K, tente ajustar o comando e os parâmetros de amostragem de tokens.

5. Executar testes de carga

Se o aplicativo precisar de uma determinada capacidade mínima, faça testes de carga para garantir que a versão mais recente do aplicativo atenda aos requisitos de capacidade.

O teste de carga precisa ocorrer antes da avaliação on-line, porque ela envolve a exposição do modelo ao tráfego em tempo real. Use as ferramentas e a instrumentação de teste de carga que você já tem para esta etapa.

Se o aplicativo já atende às necessidades de capacidade de processamento, use a Capacidade de Processamento Provisionada. Você vai precisar de uma Capacidade de Processamento Provisionada extra de curto prazo para cobrir os testes de carga enquanto seu pedido atual de Capacidade de Processamento Provisionada lida com o tráfego de produção.

6. (Opcional) Executar avaliações on-line

Passe para a avaliação on-line somente se a avaliação off-line mostrar uma alta qualidade de saída do Gemini e se o aplicativo exigir uma avaliação on-line.

A avaliação on-line é um tipo específico de teste on-line. Tente usar as ferramentas e os métodos atuais da sua organização para avaliação on-line. Exemplo:

• Se a organização realiza testes A/B regularmente, faça um para comparar a versão atual do aplicativo com a versão mais recente do Gemini.
• Se a organização usa regularmente implantações canário, use-as com os modelos mais recentes e meça as mudanças no comportamento do usuário.

Também é possível fazer uma avaliação on-line adicionando novos recursos de feedback e medição ao aplicativo. Aplicativos diferentes precisam de métodos de feedback diferentes. Exemplo:

• Adicionar botões de gostei e não gostei ao lado das saídas do modelo e comparar as taxas entre um modelo mais antigo e os modelos mais recentes do Gemini.
• Mostrar aos usuários os resultados do modelo mais antigo e dos modelos mais recentes lado a lado e pedir que escolham o favorito.
• Monitorar com que frequência os usuários substituem ou ajustam manualmente as saídas do modelo antigo em comparação com os modelos mais recentes.

Esses métodos de feedback geralmente exigem a execução da versão mais recente do Gemini com a versão atual. Essa implantação paralela às vezes é chamada de "modo de sombra" ou "implantação azul-verde".

Se os resultados da avaliação on-line forem muito diferentes dos resultados da avaliação off-line, sua avaliação off-line não está capturando aspectos importantes do ambiente em tempo real ou da experiência do usuário. Aplique as descobertas da avaliação on-line para criar uma nova avaliação off-line que cubra a lacuna e volte para a etapa 3.

Se você usa a Capacidade de Processamento Provisionada, talvez seja necessário comprar mais capacidade de processamento provisionada de curto prazo para continuar atendendo aos requisitos de capacidade de processamento dos usuários na avaliação on-line.

7. Implantar para a produção

Depois que a avaliação mostrar que o modelo mais recente do Gemini tem um desempenho igual ou melhor que o de um modelo mais antigo, substitua a versão atual do aplicativo pela nova. Siga os procedimentos padrão da sua organização para o lançamento da produção.

Se você estiver usando a Capacidade de Processamento Provisionada, mude o pedido para o modelo do Gemini escolhido. Se você estiver lançando seu aplicativo de forma incremental, use a Capacidade de Processamento Provisionada de curto prazo para atender às necessidades de capacidade de processamento de dois modelos do Gemini diferentes.

Atualizações de parâmetros e práticas recomendadas no Gemini 3.x

As informações a seguir se aplicam a todos os modelos do Gemini 3.x, incluindo o Gemini 3.5 Flash. Eles foram introduzidos com o Gemini 3 e estão listados aqui como um lembrete.

Parâmetros de amostragem (descontinuados)

temperature, top_p e top_k não são mais recomendados para todos os modelos do Gemini 3.x. O modelo gerencia a própria amostragem para alcançar os melhores resultados. Remova esses parâmetros de todas as solicitações.

Para maximizar o determinismo, recomendamos definir uma instrução do sistema com regras explícitas para seu caso de uso específico.

thinking_budget (obsoleto)

O parâmetro numérico bruto thinking_budget não é mais recomendado em todos os modelos do Gemini 3.x e retorna um erro de validação HTTP 400 nos modelos do Gemini 4. Use o tipo enumerado de string thinking_level.

Chamada de função: correspondência de resposta estrita

A API ainda não gera erros, mas respostas incompatíveis fazem com que o modelo retorne respostas vazias com finish_reason: STOP na maioria dos casos. Siga sempre estas convenções:

• Incluir id: cada FunctionResponse precisa incluir o id do FunctionCall correspondente.
• Correspondência de name: o name na resposta precisa corresponder ao name na chamada.
• Contagens de correspondência: retorna exatamente um FunctionResponse para cada FunctionCall recebido.

Respostas de funções multimodais

Ao fornecer conteúdo multimodal (como imagens) em resposta a uma chamada de função, inclua o conteúdo dentro das partes da resposta da função, não fora delas. Isso evita comportamentos inesperados do modelo, como vazamento de pensamentos.

Instruções inline com resposta de função

Se você precisar fornecer instruções de plataforma com as respostas da função, adicione-as ao final do texto da resposta da função, separadas por duas novas linhas, em vez de partes separadas.

Redução de chamadas de ferramentas desnecessárias

Se você notar um uso excessivo de chamadas de ferramenta: 1. Reduza o nível de pensamento (medium, low ou minimal). 2. Adicione uma instrução do sistema para restringir o uso da ferramenta (por exemplo, "You have a limited action budget of <n> tool calls. Use them efficiently.").

Lista de verificação de migração

Use as listas de verificação a seguir como referência rápida ao migrar de versões anteriores do modelo:

Do pré-lançamento do Gemini 3.1 Pro para o Gemini 4 Argon

• Atualize o nome do modelo: gemini-3.1-pro-preview → gemini-4-argon (ou gemini-4-argon-cyber-permissive para cargas de trabalho de cibersegurança aprovadas pelo Fairwind) e faça upgrade para o SDK de IA generativa do Google mais recente (google-genai >= 2.30.1 para Python).
• Considere o limite unificado de 1.048.576 tokens para entrada e saída (em que a saída inclui raciocínio, chamadas de função e a resposta final) e o limite de 65.536 tokens para saída de uma única solicitação (32.768 tokens para chamadas HTTP diretas sem streaming). Para saídas de turno único de até 1.048.576 tokens, configure decodificações longas em GenerateContent (processadas automaticamente no SDK de IA Generativa do Google quando max_output_tokens é definido como maior que 65.536 ou usando continuation_token em loops personalizados).
• Substitua thinking_budget e thinking_level="MINIMAL" (ambos retornam um erro HTTP 400) por thinking_level definido como LOW, MEDIUM (padrão em gemini-4-argon) ou HIGH (padrão em gemini-4-argon-cyber-permissive).
• Remova as chamadas explícitas de cached_content. Coloque prefixos de comando estáticos (6.144 tokens ou mais) no início dos comandos para o armazenamento em cache implícito automático.
• Remova temperature, top_p, top_k, frequency_penalty, presence_penalty, candidate_count e as rodadas pré-preenchidas de model.
• Consulte Migrar do Gemini 3.1 Pro e o guia do desenvolvedor para o Gemini 4 Argon para mais detalhes.

Do pré-lançamento do Gemini 3 Flash

• Atualize o nome do modelo: gemini-3-flash-preview → gemini-3.5-flash.
• Conferir preços. O Gemini 3.5 Flash é mais caro que o Gemini 3 Flash Preview.
• Remova temperature, top_p e top_k da sua configuração.
• Substitua thinking_budget por thinking_level.
• Teste seus comandos. O esforço padrão mudou de high → medium.
• A preservação de raciocínio agora está ativada por padrão. O contexto de raciocínio é mantido entre os turnos.
• Reduza as chamadas de ferramentas desnecessárias ajustando o nível de reflexão ou adicionando instruções do sistema.
• Mitigar a bajulação: se o gemini-3.5-flash começar a mostrar sinais de bajulação, você pode tentar mitigar esse comportamento usando as instruções do sistema. Para isso, adicione o seguinte: - Keep your responses concise. - Provide a summary of your work when you end your turn. Ground your response in the work you did. Keep your tone professional and avoid overconfident language, bragging, or overclaiming success. - AVOID using superlatives such as "perfectly", "flawlessly", "100% correct", "Summary of Accomplishments" etc. to summarize your work for the user. Be humble. - AVOID over-the-top politeness or complimenting the user excessively. - Format your responses in github-style markdown.

Do Gemini 2.5

• Testar cargas de trabalho de PDF e documentos. O consumo de tokens para PDFs pode aumentar.
• Simplifique os comandos. Teste o thinking_level: "medium" ou o "high" com comandos mais simples em vez de comandos complexos com linha de raciocínio.
• Aproveite o uso combinado de ferramentas (pesquisa, contexto de URL, execução de código, funções).
• Mova o conteúdo multimodal para dentro das partes de resposta da função.
• Anexe instruções inline ao texto de resposta da função.

Como melhorar o desempenho do modelo

Ao migrar, aplique estas dicas para alcançar o desempenho ideal do modelo do Gemini escolhido:

• Para todos os modelos do Gemini 3, os parâmetros de amostragem (temperature, top_p e top_k) foram descontinuados. O modelo gerencia a própria amostragem para alcançar os melhores resultados. O Google recomenda remover esses parâmetros de todas as solicitações.
• Verifique suas instruções do sistema, comandos e exemplos de aprendizado few-shot para identificar inconsistências, contradições ou instruções e exemplos irrelevantes.
• Teste um modelo mais avançado. Por exemplo, se você avaliou um modelo Flash-Lite, teste um modelo Flash ou Pro.
• Revise os resultados da avaliação automatizada para garantir que eles correspondam ao julgamento humano, especialmente os resultados que usam um modelo de juiz. Verifique se as instruções do modelo de juiz são claras, consistentes e inequívocas.
• Para melhorar as instruções do modelo de juiz, teste-as com vários humanos trabalhando de forma isolada. Se os humanos interpretarem as instruções de maneira diferente e fornecerem julgamentos diferentes, as instruções do modelo de juiz não estarão claras.
• Ajustar o modelo.
• Examine as saídas de avaliação em busca de padrões que mostrem tipos específicos de falhas. Agrupar as falhas por modelo, tipo ou categoria fornece dados de avaliação mais direcionados, facilitando o ajuste dos comandos para corrigir esses erros.
• Avalie os diferentes componentes de IA generativa de forma independente.
• Tente ajustar os parâmetros de amostragem de tokens.

Como receber ajuda

Se você precisar de ajuda, o Cloud de Confiance by S3NS oferece pacotes de suporte para atender às suas necessidades, como cobertura 24 horas, suporte por telefone e acesso a um gerente de suporte técnico. Para mais informações, consulte Suporte doCloud de Confiance .

A seguir