Migrar seu aplicativo para o Gemini 2 com a API Gemini na Vertex AI

Para uma migração perfeita do Gemini 2, recomendamos que você resolva as seguintes questões antes de iniciar o processo de migração.

• Atenção à desativação de modelos: confira os prazos de disponibilidade e compatibilidade da versão do modelo para modelos mais antigos do Gemini e conclua a migração antes que o modelo que você está usando seja desativado.
• Aprovações de governança, InfoSec e regulamentares: solicite de forma proativa as aprovações necessárias para o Gemini 2 às partes interessadas de segurança da informação (InfoSec), risco e compliance. Cubra as restrições de compliance e risco específicas do domínio, especialmente em setores altamente regulamentados, como saúde e serviços financeiros. Os controles de segurança do Gemini são diferentes entre os modelos do Gemini 2.
• Disponibilidade de local: consulte a documentação Disponibilidade de modelos de IA generativa e de parceiros no Google Cloud e verifique se o modelo Gemini 2 escolhido está disponível nas regiões necessárias. Caso contrário, considere mudar para o endpoint global.
• Diferenças de preços com base na modalidade e na tokenização: confira os preços do Gemini 2 para todas as modalidades (texto, código, imagens, fala) no seu app. Para mais informações, consulte a página de preços da IA generativa. A entrada e a saída de texto do Gemini 2 são cobradas por token, enquanto a entrada e a saída de texto do Gemini 1 são cobradas por caractere.
• Capacidade de processamento provisionada: se necessário, compre mais capacidade de processamento provisionada para o Gemini 2 ou altere os pedidos de capacidade de processamento provisionada.
• Ajuste de detalhes supervisionado: se o aplicativo do Gemini usar o ajuste de detalhes supervisionado, envie um novo job de ajuste com o Gemini 2. Recomendamos que você comece com os hiperparâmetros de ajuste padrão em vez de reutilizar os valores usados nas versões anteriores do Gemini. O serviço de ajuste foi otimizado para o Gemini 2. Portanto, a reutilização de valores de hiperparâmetros anteriores pode não gerar os melhores resultados.
• Teste de regressão: há três tipos principais de teste de regressão envolvidos no upgrade para os modelos do Gemini 2:
  • Testes de regressão de código: testes de regressão de uma perspectiva de engenharia de software e DevOps. Esse tipo de teste de regressão é sempre necessário.
  • Testes de regressão de desempenho do modelo: testes de regressão de uma perspectiva de ciência de dados ou aprendizado de máquina. Isso significa garantir que o novo modelo Gemini 2 ofereça saídas de qualidade pelo menos tão alta quanto as do modelo de produção atual. Os testes de regressão de desempenho do modelo são apenas avaliações feitas como parte de uma mudança no sistema ou no modelo subjacente. O teste de regressão de desempenho do modelo se divide em:
    • Teste de desempenho do modelo off-line: avaliação da qualidade das saídas do modelo em um ambiente de experimentação dedicado com base em várias métricas de qualidade da saída do modelo.
    • Teste de desempenho de modelo on-line: avaliação da 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.
  • Teste de carga: avaliar como o aplicativo lida com grandes volumes de solicitações de inferência. Esse tipo de teste de regressão é necessário para aplicativos que exigem throughput provisionado.

1. Prepare-se para repetir as avaliações relevantes desde que você criou o aplicativo pela primeira vez, além de todas as avaliações relevantes que você fez desde então.
2. Se você achar que as avaliações atuais não abrangem ou medem adequadamente a amplitude das tarefas que o aplicativo executa, projete e prepare outras avaliações.
3. Se a sua proposta envolve RAG, uso de ferramentas, fluxos de trabalho de agentes complexos 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 tiver um impacto muito grande ou fizer parte de um sistema maior voltado ao usuário em tempo real, inclua a avaliação on-line.

Se o aplicativo Gemini 1.x usar o SDK da Vertex AI, considere fazer upgrade para o SDK da IA generativa. Os novos recursos do Gemini 2 só estão disponíveis no SDK da IA generativa. No entanto, não é necessário mudar para o SDK da IA generativa se o app exigir apenas recursos disponíveis no SDK da Vertex AI.

Se você não conhece o SDK da IA generativa, consulte o notebook Como começar a usar a IA generativa do Google com o SDK da IA generativa.

pip install --upgrade google-genai

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai
from google.genai.types import HttpOptions

client = genai.Client(http_options=HttpOptions(api_version="v1"))
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="How does AI work?",
)
print(response.text)

# Example response:
# Okay, let's break down how AI works. It's a broad field, so I'll focus on the ...
# Here's a simplified overview:
# ...

 pip install --upgrade --quiet google-cloud-aiplatform 

 
import vertexai
from vertexai.generative_models import GenerativeModel

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

model = GenerativeModel("gemini-2.0-flash-001")

response = model.generate_content(
    "What's a good name for a flower shop that specializes in selling bouquets of dried flowers?"
)

print(response.text)
# Example response:
# **Emphasizing the Dried Aspect:**
# * Everlasting Blooms
# * Dried & Delightful
# * The Petal Preserve
# ...

Mudar as chamadas do Gemini

Mude o código de previsão para usar o Gemini 2. Isso significa, no mínimo, mudar o nome do endpoint específico do modelo para um modelo do Gemini 2 em que você carrega o modelo.

A mudança exata do código vai variar de acordo com a forma como você implementou o aplicativo originalmente, especialmente se você usou o SDK da IA generativa ou o SDK da Vertex AI.

Depois de fazer as mudanças no código, realize testes de regressão e outros testes de software no código para garantir que ele seja executado. O objetivo desse teste é avaliar se o código funciona corretamente. Não é para avaliar a qualidade das respostas do modelo.

Resolver mudanças de código interruptivas

• Recuperação dinâmica: mude para o Embasamento com a Pesquisa Google. Esse recurso exige o uso do SDK da IA generativa. Ele 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 e 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 oferecem suporte à alteração do parâmetro Top-K.

Nesta etapa, concentre-se apenas nas mudanças no código. Talvez seja necessário fazer outras mudanças, mas aguarde até iniciar a avaliação e considere o seguinte ajuste com base nos resultados da avaliação:

• Se você estiver mudando da recuperação dinâmica, talvez seja necessário testar 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."), mas aguarde a avaliação antes de fazer mudanças no comando.
• Se você usou o parâmetro Top-K, ajuste outros parâmetros de amostragem de token, como Top-P, para obter resultados semelhantes.

Repita a avaliação que você fez quando desenvolveu e lançou o aplicativo, qualquer outra avaliação off-line que você fez após o lançamento e qualquer outra avaliação identificada na etapa 1. Se você achar que a avaliação não captura totalmente a amplitude e a profundidade do seu aplicativo, faça uma avaliação mais detalhada.

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

Se o aplicativo usa o ajuste fino, faça uma avaliação off-line antes de ajustar o modelo novamente com o Gemini 2. A qualidade de saída aprimorada do Gemini 2 pode significar que seu aplicativo não precisa mais de um modelo ajustado.

Se a avaliação off-line mostrar uma queda no desempenho com o Gemini 2, repita o processo no seu aplicativo da seguinte forma até que a performance do Gemini corresponda ao modelo mais antigo:

• Engenharia iterativa dos comandos para melhorar a performance ("Hill Climbing"). Se você é iniciante no treinamento de escalada, consulte o treinamento on-line de escalada do Vertex Gemini. O otimizador de comandos da Vertex AI (notebook de exemplo) também pode ajudar.
• Se o seu aplicativo já usa o ajuste fino, tente ajustar o Gemini 2.
• Se o app for afetado pela recuperação dinâmica e pelas mudanças de top-k, tente alterar o comando e os parâmetros de amostragem de token.

Se o aplicativo exigir uma taxa de transferência mínima, faça testes de carga para garantir que a versão Gemini 2 atenda aos requisitos de throughput.

O teste de carga precisa acontecer antes da avaliação on-line, porque ela exige a exposição do Gemini 2 ao tráfego de produção. Use a instrumentação de teste de carga atual para realizar esta etapa.

Se o aplicativo já atende aos requisitos de throughput, considere usar a capacidade de processamento provisionada. Você vai precisar de mais throughput provisionado de curto prazo para cobrir o teste de carga enquanto o pedido de throughput provisionado atual continua veiculando o tráfego de produção.

Só prossiga para a avaliação on-line se a avaliação off-line mostrar uma qualidade de saída adequada do Gemini e se o app exigir uma avaliação on-line.

A avaliação on-line é um caso especial de teste on-line. Tente usar as ferramentas e os procedimentos atuais da sua organização para a avaliação on-line. Exemplo:

• Se a sua organização realiza testes A/B regularmente, faça um teste A/B que avalie a implementação atual do seu aplicativo em comparação com a versão 2 do Gemini.
• Se a sua organização realiza implantações canário regularmente, faça isso com o Gemini 2 e meça as diferenças no comportamento do usuário.

A avaliação on-line também pode ser feita criando novos recursos de feedback e medição no seu aplicativo. Diferentes recursos de feedback e medição são adequados para diferentes aplicativos. Exemplo:

• Adicionar botões de polegar para cima e para baixo ao lado das saídas do modelo e comparar as taxas de polegar para cima e para baixo entre um modelo mais antigo e o Gemini 2.
• Mostre aos usuários o modelo mais antigo e as saídas do Gemini 2 lado a lado e peça para eles escolherem o favorito.
• Monitorar com que frequência os usuários substituem ou ajustam manualmente o modelo mais antigo em comparação com as saídas do Gemini 2.

Esses tipos de mecanismos de feedback geralmente exigem a execução de uma versão do Gemini 2 do aplicativo em paralelo à 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 significativamente diferentes dos resultados da avaliação off-line, a avaliação off-line não vai capturar os principais aspectos do ambiente ativo ou da experiência do usuário. Use os resultados da avaliação on-line para criar uma nova avaliação off-line que cubra a lacuna exposta pela avaliação on-line e volte para a etapa 3.

Se você usa a taxa de transferência provisionada, talvez seja necessário comprar mais taxa de transferência provisionada de curto prazo para continuar atendendo aos requisitos de taxa de transferência para usuários sujeitos a avaliação on-line.

Quando a avaliação mostrar que o Gemini 2 atende ou excede a performance de um modelo mais antigo, desative a versão atual do seu aplicativo em favor da versão do Gemini 2. Siga os procedimentos atuais da sua organização para o lançamento da produção.

Se você estiver usando a taxa de transferência provisionada, mude a ordem para o modelo Gemini 2 escolhido. Se você estiver lançando seu aplicativo de forma incremental, use a capacidade provisionada de curto prazo para atender aos requisitos de capacidade de dois modelos diferentes do Gemini.