Migre para os modelos do Gemini mais recentes

Este guia explica como atualizar a sua aplicação para a versão mais recente do Gemini. Este guia pressupõe que a sua aplicação já usa uma versão mais antiga do Gemini. Para saber como começar a usar o Gemini no Vertex AI, consulte o início rápido da API Gemini no Vertex AI.

Este guia não aborda como mudar a sua aplicação do SDK Vertex AI para o SDK Google Gen AI atual. Para obter essas informações, consulte o nosso guia de migração do SDK Vertex AI.

Que alterações devo esperar?

A atualização da maioria das aplicações de IA generativa para a versão mais recente do Gemini requer poucas alterações ao código ou aos comandos. No entanto, algumas aplicações podem requerer ajustes de comandos. É difícil prever estas alterações sem testar primeiro os seus comandos com a nova versão. Recomendamos que faça testes exaustivos antes de migrar totalmente. Para ver sugestões sobre como criar comandos eficazes, consulte as nossas orientações de estratégia de comandos. Use a nossa lista de verificação do estado dos comandos para ajudar a encontrar e corrigir problemas de comandos.

Só precisa de fazer alterações significativas ao código para determinadas alterações destrutivas ou para usar novas capacidades do Gemini.

Para que modelo do Gemini devo migrar?

O modelo do Gemini que usa depende das necessidades da sua aplicação. A tabela seguinte compara os modelos Gemini 1.5 mais antigos com os modelos Gemini mais recentes:

Funcionalidade 1.5 Pro 1.5 Flash 2.0 Flash 2.0 Flash-Lite 2.5 Pro 2.5 Flash 2.5 Flash-Lite 3 Pro
Fase de lançamento Descontinuado Descontinuado Disponível de forma geral Disponível de forma geral Disponível de forma geral Disponível de forma geral Disponível de forma geral Pré-visualização
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
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
Modalidades de saída
Texto
Texto
Texto
Texto
Texto
Texto
Texto
Texto
Capacidade de resposta, limite total de tokens 2,097,152 1 048 576 1 048 576 1 048 576 1 048 576 1 048 576 1 048 576 1 048 576
Comprimento do contexto de saída 8192 (predefinição) 8192 (predefinição) 8192 (predefinição) 8192 (predefinição) 65 535 (predefinição) 65 535 (predefinição) 65 535 (predefinição) 65 536
Fundamentação com a Pesquisa Google
Chamada de funções
Execução de código
Colocação em cache de contexto implícito
Colocação em cache de contexto explícito
Previsão em lote
API Live*
Ajuste preciso
Latência
SDK recomendado SDK Vertex AI SDK Vertex AI SDK Gen AI SDK Gen AI SDK Gen AI SDK Gen AI SDK Gen AI SDK Gen AI
Unidades de preços Personagem Personagem Símbolo Símbolo Símbolo Símbolo Símbolo Símbolo
Data de descontinuação 24 de setembro de 2025 24 de setembro de 2025 5 de fevereiro de 2026 25 de fevereiro de 2026 17 de junho de 2026 17 de junho de 2026 22 de julho de 2026

* A API Live está disponível como oferta de pré-visualização como parte do gemini-live-2.5-flash e do gemini-live-2.5-flash-preview-native-audio.

Antes de começar a migrar

Antes de iniciar o processo de migração, deve considerar o seguinte:

InfoSec, gestão e aprovações regulamentares

Obtenha aprovações das suas equipas de segurança das informações (InfoSec), de risco e de conformidade antecipadamente. Abranger quaisquer regras específicas de risco e conformidade, especialmente em setores regulamentados, como os cuidados de saúde e as finanças.

Disponibilidade da localização

Os modelos da Google e de parceiros, bem como as funcionalidades de IA generativa na Vertex AI, estão disponíveis através de endpoints regionais específicos e de um endpoint global. Os pontos finais globais abrangem todo o mundo e oferecem uma disponibilidade e uma fiabilidade melhoradas em comparação com regiões únicas.

A disponibilidade de pontos finais regionais varia consoante o modelo. Para ver detalhes sobre cada modelo, consulte o nosso guia de localizações.

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

Os preços variam entre cada modelo do Gemini. A nossa página de preços apresenta os custos para todas as modalidades (texto, código, imagens, voz, etc.) por modelo.

Ajuste supervisionado

Os modelos Gemini mais recentes oferecem uma melhor qualidade de saída. Isto pode significar que a sua aplicação já não precisa de um modelo otimizado. Se a sua aplicação usar o ajuste fino supervisionado com um modelo Gemini mais antigo, teste primeiro a aplicação com o modelo mais recente sem ajuste fino e avalie os resultados.

Se optar por usar o ajuste fino supervisionado, não pode mover o seu modelo ajustado existente das versões mais antigas do Gemini. Tem de executar uma nova tarefa de ajuste para a nova versão do Gemini.

Quando ajustar um novo modelo do Gemini, comece pelas definições de ajuste predefinidas. Não volte a usar valores de hiperparâmetros de versões anteriores do Gemini, porque o serviço de ajuste é otimizado para as versões mais recentes. É pouco provável que a reutilização de definições antigas produza resultados ideais.

Testes de regressão

Quando atualizar para a versão mais recente do Gemini, precisa 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 da engenharia de software e das operações de programadores (DevOps). Este tipo de testes de regressão é sempre necessário.

  2. Testes de regressão do desempenho do modelo: testes de regressão de uma perspetiva de ciência de dados ou aprendizagem automática. Isto significa garantir que a nova versão do modelo Gemini oferece resultados que, pelo menos, mantêm o mesmo nível de qualidade que a versão anterior.

    Os testes de regressão do desempenho do modelo são avaliações de modelos feitas quando um sistema ou o respetivo modelo subjacente muda. Estes incluem:

    • Testes de desempenho offline: testes que afirmam a qualidade dos resultados do modelo num ambiente de experimentação dedicado com base em várias métricas de qualidade dos resultados do modelo.
    • Testes de desempenho do modelo online: testes que afirmam a qualidade dos resultados do modelo numa implementação online em direto com base no feedback do utilizador implícito ou explícito.
  3. Testes de carga: estes testes verificam o desempenho da aplicação quando processa muitos pedidos em simultâneo. Os testes de carga são obrigatórios para aplicações que usam Provisioned Throughput.

Como migrar para a versão mais recente

As secções seguintes descrevem os passos para migrar para a versão mais recente do Gemini. Para obter os melhores resultados, conclua estes passos por ordem.

1. Documente os requisitos de avaliação e testes de modelos

  1. Prepare-se para repetir todas as avaliações relevantes que realizou quando criou a aplicação pela primeira vez, bem como todas as avaliações realizadas desde então.
  2. Se as suas avaliações atuais não abrangem nem medem totalmente todas as tarefas que a sua aplicação executa, crie e prepare mais avaliações. Pode usar o nosso manual de avaliação e as nossas receitas de avaliação para começar.
  3. Se a sua aplicação envolver RAG, utilização de ferramentas, fluxos de trabalho de agentes complexos ou cadeias de comandos, certifique-se de que os seus dados de avaliação existentes permitem avaliar cada componente de forma independente. Caso contrário, recolha exemplos de entrada/saída para cada componente.
  4. Se a sua aplicação for crítica ou fizer parte de um sistema em tempo real orientado para o utilizador mais amplo, inclua a avaliação online.

2. Faça atualizações de código e execute testes

A atualização do código requer três alterações principais:

As secções seguintes abordam estas alterações mais detalhadamente.

Atualize para o SDK Google Gen AI

Se a sua aplicação Gemini 1.x usar o SDK da Vertex AI, mude para o SDK de IA gen. Consulte o nosso guia de migração do SDK Vertex AI para ver detalhes, incluindo exemplos de código para fazer chamadas semelhantes com o SDK Gen AI. As versões do SDK Vertex AI após junho de 2026 não vão suportar o Gemini, e as novas funcionalidades do Gemini só estão disponíveis no SDK de IA gen.

Se for um utilizador recente do SDK de IA gen, consulte o bloco de notas Introdução à IA generativa da Google com o SDK de IA gen.

Altere as suas chamadas do Gemini

Atualize o seu código de previsão para usar um dos modelos do Gemini mais recentes. No mínimo, isto significa alterar o nome do ponto final do modelo.

As alterações exatas ao código variam consoante a forma como criou a sua aplicação, especialmente se usou o SDK de IA gen ou o SDK de IA Vertex.

Depois de fazer alterações ao código, execute testes de regressão de código e outros testes de software para garantir que o código funciona como esperado. Este passo verifica se o código funciona, mas não a qualidade das respostas do modelo.

Corrija alterações de código que causam problemas

  • Obtenção dinâmica: mude para a utilização da fundamentação com a Pesquisa Google. Esta funcionalidade requer o SDK de IA gen e não é suportada pelo SDK da Vertex AI.
  • Filtros de conteúdo: tenha em atenção as definições do filtro de conteúdo predefinidas. Altere o código se este depender de uma predefinição que foi alterada.
  • Parâmetro de amostragem de tokens Top-K: Os modelos posteriores a gemini-1.0-pro-vision não suportam a alteração do parâmetro Top-K.
  • Pensamento: o Gemini 3 Pro e os modelos posteriores usam o parâmetro thinking_level em vez de thinking_budget. Para mais informações, consulte o artigo Controle o raciocínio do modelo.
  • Assinaturas de raciocínio: para o Gemini 3 Pro e modelos posteriores, se for esperada uma assinatura de raciocínio num turno, mas não for fornecida, o modelo devolve um erro em vez de um aviso. Consulte as Assinaturas de pensamento.
  • Resolução de multimédia e tokenização: os modelos Gemini 3 Pro e posteriores usam um comprimento de sequência variável para a tokenização de multimédia em vez de Pan and Scan, e têm novas resoluções predefinidas e custos de tokens para imagens, PDFs e vídeos. Consulte Compreensão de imagens e Compreensão de vídeos.
  • Metadados de utilização: para o Gemini 3 Pro e modelos posteriores, as contagens de tokens de PDF em usage_metadata são comunicadas na modalidade IMAGE, em vez de DOCUMENT.
  • Segmentação de imagens: a segmentação de imagens não é suportada pelo Gemini 3 Pro e modelos posteriores.
  • Respostas de funções multimodais: para os modelos Gemini 3 Pro e posteriores, pode incluir dados de imagens e PDFs nas respostas de funções. Consulte as respostas das funções multimodais.
  • Processamento de PDFs: para o Gemini 3 Pro e modelos posteriores, o OCR não é usado por predefinição quando processa PDFs digitalizados.

Neste passo, concentre-se apenas nas alterações ao código. Pode ter de fazer outras alterações mais tarde, mas aguarde até iniciar a avaliação. Após as avaliações, considere estes ajustes com base nos resultados da avaliação:

  • Se estiver a mudar da obtenção dinâmica, pode ter de 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 alterar os comandos.
  • Se usou o parâmetro Top-K, ajuste outros parâmetros de amostragem de tokens, como Top-P, para obter resultados semelhantes.

3. Execute avaliações offline

Repita as avaliações que realizou quando desenvolveu e lançou a sua aplicação pela primeira vez, quaisquer avaliações offline feitas desde então e quaisquer avaliações adicionais que identificou no passo 1. Se ainda considerar que a sua avaliação não abrange totalmente o âmbito da sua aplicação, faça mais avaliações.

Se não tiver uma forma automática de executar avaliações offline, considere usar o serviço de avaliação de IA gen.

Se a sua aplicação usar o ajuste fino, faça uma avaliação offline antes de reajustar o modelo com a versão mais recente do Gemini. Os modelos mais recentes oferecem uma qualidade de saída melhorada, o que pode significar que a sua aplicação já não precisa de um modelo otimizado.

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

Se a avaliação offline mostrar que a sua aplicação tem um desempenho menos eficaz, melhore-a até que o desempenho corresponda ao do modelo mais antigo. Para o fazer:

5. Execute testes de carga

Se a sua aplicação precisar de um determinado débito mínimo, faça testes de carga para garantir que a versão mais recente da sua aplicação cumpre os requisitos de débito.

Os testes de carga têm de ocorrer antes da avaliação online, porque a avaliação online envolve a exposição do modelo ao tráfego em direto. Use as ferramentas de teste de carga e a instrumentação existentes para este passo.

Se a sua aplicação já cumpre as necessidades de débito, considere usar o Débito aprovisionado. Precisa de débito processado adicional a curto prazo para cobrir os testes de carga enquanto a sua encomenda de débito processado atual processa o tráfego de produção.

6. (Opcional) Execute avaliações online

Mude para a avaliação online apenas se a avaliação offline mostrar uma elevada qualidade de saída do Gemini e a sua aplicação exigir uma avaliação online.

A avaliação online é um tipo específico de testes online. Tente usar as ferramentas e os métodos existentes da sua organização para a avaliação online. Por exemplo:

  • Se a sua organização realizar regularmente testes A/B, faça um para comparar a versão atual da sua aplicação com a versão mais recente do Gemini.
  • Se a sua organização usar regularmente implementações canárias, use-as com os modelos mais recentes e meça as alterações no comportamento do utilizador.

Também pode fazer a avaliação online adicionando novas funcionalidades de feedback e medição à sua aplicação. As diferentes aplicações precisam de diferentes métodos de feedback. Por exemplo:

  • Adicionar botões de gosto e não gosto junto aos resultados do modelo e comparar as taxas entre um modelo mais antigo e os modelos Gemini mais recentes.
  • Mostrar aos utilizadores resultados do modelo mais antigo e dos modelos mais recentes lado a lado e pedir-lhes que escolham o seu favorito.
  • Monitorizar a frequência com que os utilizadores substituem ou ajustam manualmente os resultados do modelo mais antigo em comparação com os modelos mais recentes.

Estes métodos de feedback requerem frequentemente a execução da versão mais recente do Gemini juntamente com a versão existente. Por vezes, esta implementação paralela é denominada "modo de sombra" ou "implementação azul-verde".

Se os resultados da avaliação online diferirem significativamente dos resultados da avaliação offline, a avaliação offline não está a captar aspetos importantes do ambiente em direto ou da experiência do utilizador. Aplique as conclusões da avaliação online para criar uma nova avaliação offline que cubra a lacuna e, em seguida, regresse ao passo 3.

Se usar o débito processado, pode ter de comprar débito processado de curto prazo adicional para continuar a cumprir os requisitos de débito processado para os utilizadores na avaliação online.

7. Implemente na produção

Assim que a avaliação mostrar que o modelo Gemini mais recente tem um desempenho igual ou superior ao de um modelo mais antigo, substitua a versão da aplicação existente pela nova versão. Siga os procedimentos padrão da sua organização para a implementação de produção.

Se estiver a usar o Provisioned Throughput, altere a ordem do Provisioned Throughput para o modelo Gemini escolhido. Se estiver a implementar a sua aplicação de forma incremental, use o débito processado a curto prazo para satisfazer as necessidades de débito processado de dois modelos do Gemini diferentes.

Melhorar o desempenho do modelo

À medida que migra, aplique estas dicas para alcançar o desempenho ideal com o modelo Gemini escolhido:

  • Para o Gemini 3 Pro e modelos posteriores, a Google recomenda vivamente que mantenha o parâmetro temperature no valor predefinido de 1.0. Embora os modelos anteriores beneficiassem frequentemente da otimização da temperatura para controlar a criatividade em comparação com o determinismo, as capacidades de raciocínio do Gemini 3 Pro e dos modelos posteriores estão otimizadas para a predefinição. Alterar a temperatura (definindo-a para menos de 1.0) pode levar a um comportamento inesperado, como repetições ou desempenho degradado, particularmente em tarefas matemáticas ou de raciocínio complexas.
  • Verifique as instruções do sistema, os comandos e os exemplos de aprendizagem com poucos exemplos quanto a inconsistências, contradições ou instruções e exemplos irrelevantes.
  • Teste um modelo mais avançado. Por exemplo, se avaliou o Gemini 2.0 Flash-Lite, experimente o Gemini 2.0 Flash.
  • Reveja os resultados da avaliação automática para garantir que correspondem ao julgamento humano, especialmente os resultados que usam um modelo de avaliador. Certifique-se de que 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 instruções com vários humanos a trabalhar isoladamente. Se os humanos interpretarem as instruções de forma diferente e fornecerem julgamentos diferentes, as instruções do modelo de juiz não são claras.
  • Ajuste o modelo.
  • Examine os resultados da avaliação para encontrar padrões que mostrem tipos específicos de falhas. O agrupamento de falhas por modelo, tipo ou categoria fornece dados de avaliação mais específicos, o que facilita o ajuste dos comandos para corrigir estes erros.
  • Certifique-se de que avalia os diferentes componentes de IA generativa de forma independente.
  • Experimente ajustar os parâmetros de amostragem de tokens.

Obter ajuda

Se precisar de assistência, Google Cloud oferece pacotes de apoio técnico para satisfazer as suas necessidades, como cobertura 24 horas por dia, 7 dias por semana, apoio técnico por telefone e acesso a um gestor de apoio técnico. Para mais informações, consulte Google Cloud Apoio técnico.

O que se segue?