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 o guia de início rápido da API Gemini na Gemini Enterprise Agent Platform.

Este guia não explica como mudar seu aplicativo do SDK do Agent Platform para o SDK de IA Generativa do Google atual. Para mais informações, consulte nosso guia de migração do SDK da plataforma de agentes.

O que devo esperar?

Para atualizar a maioria dos aplicativos de IA generativa para a versão mais recente do Gemini, são necessárias 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 testar primeiro seus 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.

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

Você pode notar 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 subestimados pelo sistema legado.

Você só precisa fazer mudanças importantes no código para determinadas mudanças destrutivas 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 2.5 Pro 2.5 Flash 2.5 Flash-Lite 3. Flash 3.1 Pro 3.1 Flash-Lite 3.5 Flash
Etapa do lançamento GA Disponibilidade geral GA Pré-lançamento Visualizar GA GA
Modalidades de entrada
Texto, Código, Imagens, Áudio, Vídeo
Texto, Código, Imagens, Áudio, Vídeo
Texto, Código, Imagens, Áudio, Vídeo
Texto, Código, Imagens, Áudio, Vídeo, PDF
Texto, Código, Imagens, Áudio, Vídeo, PDF
Texto, Código, Imagens, Áudio, Vídeo, PDF
Texto, Código, Imagens, Áudio, Vídeo, PDF
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.535 (padrão) 65.535 (padrão) 65.535 (padrão) 65.536 65.536 65.535 (padrão) 65.535 (padrão)
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
Previsão em lote
API Gemini Live
Ajuste de detalhes
Latência
SDK recomendado SDK de IA generativa SDK de IA generativa SDK de IA generativa SDK de IA generativa SDK de IA generativa SDK de IA generativa SDK de IA generativa
Unidades de preço Token Token Token Token Token Token Token
Data de desativação Não antes de 16 de outubro de 2026 Não antes de 16 de outubro de 2026 Não antes de 16 de outubro de 2026

Antes de começar a migração

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

Infosec, governança e aprovações regulatórias

Obtenha aprovações antecipadas das equipes de segurança da informação (InfoSec), risco e conformidade. Aborde regras específicas de risco e compliance, principalmente em setores regulamentados, como saúde e finanças.

Disponibilidade do local

Os modelos do Google e de parceiros e os recursos de IA generativa na Gemini Enterprise Agent Platform estão disponíveis em endpoints regionais e globais específicos. Os endpoints globais abrangem o mundo todo e oferecem melhor disponibilidade e confiabilidade em comparação com regiões únicas.

A disponibilidade de endpoints regionais varia de acordo com o modelo. Para mais detalhes sobre cada modelo, consulte nosso guia de locais.

Diferenças de preços com base na modalidade e na tokenização

Os preços variam de acordo com o modelo do Gemini. Nossa página de preços lista os custos de todas as modalidades (texto, código, imagens, fala etc.) por modelo.

Comprar ou mudar pedidos de capacidade de processamento provisionada

Se necessário, compre mais capacidade de processamento provisionada ou mude os pedidos de capacidade de processamento provisionada atuais.

Ajuste supervisionado

Os modelos mais recentes do Gemini oferecem melhor qualidade de saída. Isso pode significar que seu aplicativo não precisa mais de um modelo ajustado. Se o aplicativo usar ajuste supervisionado com um modelo mais antigo do Gemini, primeiro teste o aplicativo com o modelo mais recente sem ajuste e avalie os resultados.

Se você usar o ajuste supervisionado, não será possível mover o modelo ajustado das versões mais antigas do Gemini. Você precisa executar um novo job de ajuste para a nova versão do Gemini.

Ao ajustar um novo modelo do Gemini, comece com as configurações de ajuste padrão. Não reutilize valores de hiperparâmetros de versões anteriores do Gemini, porque o serviço de ajuste é otimizado para as versões mais recentes. É improvável que a reutilização de configurações antigas gere resultados ideais.

Teste de regressão

Ao fazer upgrade para a versão mais recente do Gemini, você vai precisar de três tipos principais de testes de regressão:

  1. Testes de regressão de código:testes de regressão do ponto de vista de engenharia de software e operações de desenvolvedor (DevOps). Esse tipo de teste de regressão é sempre necessário.

  2. Testes de regressão de performance do modelo:testes de regressão de uma perspectiva de ciência de dados ou aprendizado de máquina. Isso significa garantir que a nova versão do modelo do Gemini forneça resultados que pelo menos mantenham o mesmo nível de qualidade da versão anterior.

    Os testes de regressão de desempenho do modelo são avaliações feitas quando um sistema ou o modelo subjacente muda. Veja alguns exemplos:

    • Teste de desempenho off-line:testes que afirmam a qualidade das saídas do modelo em um ambiente de experimentação dedicado com base em várias métricas de qualidade de saída do modelo.
    • Teste de desempenho do modelo on-line:testes que afirmam a qualidade das saídas do modelo em uma implantação on-line ativa com base no feedback implícito ou explícito do usuário.
  3. Teste de carga:esses testes verificam como o aplicativo lida com muitas solicitações de uma só vez. O teste de carga é obrigatório para aplicativos que usam a capacidade de processamento provisionada.

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 ter os melhores resultados, siga estas etapas na ordem.

1. Requisitos de avaliação e teste de modelos de documentos

  1. Prepare-se para repetir as avaliações relevantes que você fez 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 seu aplicativo realiza, crie e prepare mais avaliações. Use nosso playbook de avaliação e nossas receitas de avaliação para começar.
  3. Se o aplicativo envolver RAG, uso de ferramentas, fluxos de trabalho complexos de agentes ou cadeias de comandos, verifique se os dados de avaliação atuais permitem avaliar cada componente de forma independente. Caso contrário, colete exemplos de entrada e saída para cada componente.
  4. Se o aplicativo for essencial ou fizer 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 seu código, são necessárias três mudanças principais:

As seções a seguir explicam essas mudanças em mais detalhes.

Fazer upgrade para o SDK de IA generativa do Google

Se o aplicativo Gemini 1.x usar o SDK da Vertex AI, mude para o SDK de IA generativa. 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 da IA generativa. As versões do SDK da Vertex AI lançadas após junho de 2026 não vão oferecer suporte ao Gemini, e os novos recursos do Gemini só estarão disponíveis no SDK da IA generativa.

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

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

Mudar suas ligações do Gemini

Atualize seu código de previsão para usar um dos modelos mais recentes do Gemini. 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, principalmente se usou o SDK da IA generativa 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. Esta etapa verifica se o código funciona, mas não a qualidade das respostas do modelo.

Corrigir mudanças de código incompatíveis

  • Recuperação dinâmica: comece a usar o Embasamento com a Pesquisa Google. Esse recurso exige o SDK da IA generativa e não é compatível com o SDK da Vertex AI.
  • Filtros de conteúdo: observe as configurações padrão de filtro de conteúdo. Mude seu 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 modelos mais recentes usam o parâmetro thinking_level em vez de thinking_budget. Para mais informações, consulte Controlar o raciocínio do modelo.
  • Assinaturas de pensamento: para o Gemini 3 Pro e modelos 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 pensamento.
  • Resolução de mídia e tokenização: o Gemini 3 Pro e modelos mais recentes usam um comprimento de sequência variável para tokenização de mídia em vez de Pan and Scan, e têm 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 imagem: A segmentação de imagem não é compatível com o Gemini 3 Pro e modelos mais recentes.
  • Respostas de função multimodais: para modelos do Gemini 3 Pro e mais recentes, é possível incluir dados de imagem e PDF nas respostas de função. Consulte Respostas de função multimodal.
  • 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 depois, mas aguarde até começar a avaliação. Após as avaliações, considere estes ajustes com base nos resultados:

  • Se você estiver mudando 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 ter resultados semelhantes.

3. Executar avaliações off-line

Repita as avaliações que você fez quando desenvolveu e lançou o aplicativo, as avaliações off-line realizadas desde então e as avaliações adicionais identificadas na etapa 1. Se você ainda achar que sua 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 usar ajuste refinado, faça uma avaliação off-line antes de ajustar novamente o modelo com a versão mais recente do Gemini. Os modelos mais recentes oferecem melhor qualidade de saída, o que pode significar que seu aplicativo não precisa mais de um modelo ajustado.

4. Avalie os resultados da avaliação e ajuste seus comandos e hiperparâmetros

Se a avaliação off-line mostrar que o aplicativo está com desempenho abaixo do esperado, melhore o aplicativo até que a performance dele corresponda à do modelo mais antigo. Para fazer isso:

5. Executar testes de carga

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

O teste de carga precisa ocorrer antes da avaliação on-line, porque ela envolve expor o modelo ao trânsito em tempo real. Use as ferramentas e a instrumentação de teste de carga atuais para esta etapa.

Se o aplicativo já atender às necessidades de capacidade de processamento, considere usar a capacidade de processamento provisionada. Você vai precisar de mais Capacidade de Processamento Provisionada de curto prazo para cobrir os testes de carga enquanto o pedido atual lida com o tráfego de produção.

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

Mude para a avaliação on-line somente se a off-line mostrar alta qualidade de saída do Gemini e seu aplicativo exigir 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 sua organização realiza testes A/B regularmente, faça um para comparar a versão atual do aplicativo com a mais recente do Gemini.
  • Se sua 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.

Você também pode fazer uma avaliação on-line adicionando novos recursos de feedback e medição ao seu aplicativo. Aplicativos diferentes precisam de métodos de feedback diferentes. Exemplo:

  • Adicionando botões de "Gostei" e "Não gostei" ao lado das saídas do modelo e comparando as taxas entre um modelo mais antigo e os modelos mais recentes do Gemini.
  • Mostrar aos usuários saídas do modelo mais antigo e dos mais recentes lado a lado e pedir que escolham a favorita.
  • Rastrear a frequência com que os usuários substituem ou ajustam manualmente as saídas do modelo mais antigo em comparação com os mais recentes.

Esses métodos geralmente exigem que você execute a versão mais recente do Gemini ao lado da versão atual. Essa implantação paralela às vezes é chamada de "modo sombra" ou "implantação azul-verde".

Se os resultados da avaliação on-line forem muito diferentes dos resultados da avaliação off-line, isso significa que a avaliação off-line não está capturando aspectos importantes do ambiente ativo 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 à 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

Quando a avaliação mostrar que o modelo do Gemini mais recente tem um desempenho igual ou melhor que 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 o aplicativo de forma incremental, use a capacidade de processamento provisionada de curto prazo para atender às necessidades de dois modelos diferentes do Gemini.

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

Os itens a seguir se aplicam a todos os modelos do Gemini 3.x, incluindo o Gemini 3.5 Flash. Eles foram apresentados 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 ter resultados ideais. 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. Em vez disso, use o enum de string thinking_level.

Chamada de função: correspondência restrita de respostas

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:

  • Inclua id: cada FunctionResponse precisa incluir o id do FunctionCall correspondente.
  • Correspondência name: o name na resposta precisa corresponder ao name na chamada.
  • Contagem de correspondências: 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 de resposta da função, não fora delas. Isso evita comportamentos inesperados do modelo, como vazamento de pensamento.

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

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

Reduzir chamadas de ferramentas desnecessárias

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

Lista de verificação de migração

Do pré-lançamento do Gemini 3 Flash

  • Atualizar nome do modelo: gemini-3-flash-preview → gemini-3.5-flash.
  • Conferir preços. O Gemini 3.5 Flash é mais caro do que o Gemini 3 Flash Preview.
  • Remova temperature, top_p e top_k da sua configuração.
  • Substitua thinking_budget por thinking_level.
  • Adicione id e name correspondente a todas as partes FunctionResponse.
  • Teste seus comandos. O esforço padrão mudou de high para medium.
  • A preservação de ideias agora está ativada por padrão. O contexto de raciocínio é mantido entre os turnos.
  • Ajuste o nível de raciocínio ou adicione instruções do sistema para reduzir as chamadas de ferramentas desnecessárias.
  • No momento, o uso de computadores não está disponível no Gemini 3.5 Flash.
  • Reduza a adulação: se gemini-3.5-flash começar a mostrar sinais de adulação, tente reduzir esse comportamento com 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. Tente thinking_level: "medium" ou "high" com comandos mais simples em vez de comandos complexos de raciocínio em cadeia.
  • 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.
  • Adicione instruções inline ao texto da resposta da função.

Como melhorar o desempenho do modelo

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

  • Para todos os modelos 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 resultados ideais. 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 eficiente. Por exemplo, se você avaliou o Gemini 2.0 Flash-Lite, teste o Gemini 2.0 Flash.
  • Revise os resultados da avaliação automatizada para garantir que eles correspondam ao julgamento humano, especialmente os resultados que usam um modelo de avaliação. As instruções do modelo de avaliação precisam ser claras, consistentes e sem ambiguidade.
  • Para melhorar as instruções do modelo de avaliação, teste-as com várias pessoas trabalhando isoladamente. Se os humanos interpretarem as instruções de maneira diferente e fizerem julgamentos diferentes, as instruções do modelo de avaliação não estão claras.
  • Ajuste o modelo.
  • Examine as saídas de avaliação para encontrar padrões que mostrem tipos específicos de falhas. Agrupar falhas por modelo, tipo ou categoria fornece dados de avaliação mais direcionados, facilitando o ajuste dos comandos para corrigir esses erros.
  • Verifique se você está avaliando diferentes componentes de IA generativa de forma independente.
  • Teste ajustar os parâmetros de amostragem de token.

Como receber ajuda

Se você precisar de ajuda, o Google Cloud 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 doGoogle Cloud .

A seguir

Guia

Aprenda os conceitos básicos de como usar o SDK de IA Generativa do Google para enviar consultas aos modelos do Gemini com a Agent Platform.

Visão geral

Lista de modelos do Google disponíveis na plataforma de agentes, como Gemini, Gemma e Veo.

Visão geral

Lista de modelos desenvolvidos por parceiros do Google disponíveis na Plataforma de Agentes, como Claude e Mistral.

Visão geral

Visão geral de como usar modelos abertos, como Gemma, Llama, DeepSeek e outros, na Agent Platform.

Recurso

Perguntas frequentes sobre o uso do Gemini com a Plataforma de Agentes.