Migrar de Gemma 2 para Gemma 3: armadilhas e verificações

#O que muda realmente entre Gemma 2 e Gemma 3

Três mudanças estruturais afetam uma aplicação existente: o contexto máximo, a estrutura das mensagens enviadas ao modelo e a presença de uma entrada de imagem. Uma simples troca de nome de modelo no seu código (gemma2 por gemma3) não basta para garantir um comportamento idêntico, mesmo que o formato de saída continue sendo texto.

Gemma 2 existia apenas com 9 e 27 bilhões de parâmetros. Gemma 3 adiciona um 1B e um 4B, e redefine o contexto de cada tamanho: não é apenas 'maior', é uma arquitetura diferente internamente. Se sua escolha de tamanho do modelo estava baseada nas restrições de Gemma 2, merece ser reconsiderada em vez de repetida idêntica.

#Tamanhos e contexto: o verdadeiro salto

Gemma 2 tem um contexto fixo de 8.192 tokens, independentemente do tamanho do modelo. Gemma 3 expande esse contexto para 32.768 tokens para o modelo de 1B e para 131.072 tokens para os modelos de 4B, 12B e 27B: um fator de 16 para modelos médios e grandes. Essa é a informação mais útil para dimensionar um uso RAG ou um histórico de conversa longo, mas esse contexto anunciado é um limite do modelo, não a memória realmente alocada pelo seu runtime: Ollama e os servidores de inferência limitam frequentemente o contexto por padrão a um valor muito mais baixo (geralmente 4.096 ou 8.192 tokens) até que você o aumente explicitamente.

#Template de chat: a armadilha mais frequente

A causa mais comum de respostas de qualidade inferior após uma migração não é a qualidade do modelo, mas um template de chat mal aplicado. Cada família de modelos espera uma formatação precisa dos turnos de conversa (marcadores de início/fim de turno, posição do prompt de sistema). Se seu aplicativo constrói o prompt final por conta própria, em vez de deixar o runtime aplicar o template do modelo, um template que continua configurado para o Gemma 2 produz respostas truncadas, fora do assunto ou cuja geração continua após o ponto de término esperado.

1. 01
   Identificar quem constrói o prompt

   Verificar se o próprio código monta o texto enviado ao modelo ou se passa pela API de chat do runtime (Ollama /api/chat, servidor llama.cpp), que aplica automaticamente o template correto.
2. 02
   Comparar os templates

   Recuperar o arquivo de template embutido no modelo Gemma 3 usado (GGUF ou Hugging Face) e compará-lo ao do Gemma 2 usado até agora, em vez de supor que são idênticos.
3. 03
   Executar novamente um conjunto de prompts de referência

   Executar os mesmos 10 a 20 prompts de teste no Gemma 2 e depois no Gemma 3 com o novo template, e comparar o comprimento, a relevância e se a geração termina corretamente.

O papel de sistema ilustra bem esse engano. O Google indica, ao apresentar Gemma 4, que esta nova família "usa papéis padrão system, assistant e user, diferentemente de Gemma 3": uma confirmação oficial de que Gemma 3 (como Gemma 2) não trata exatamente o prompt de sistema como os runtimes que expõem um papel system nativo. Concretamente, um código que envia uma mensagem de papel system separada, baseando-se nas convenções de outras famílias de modelos, deve verificar, em Gemma 3 especificamente, como seu runtime trata essa mensagem, em vez de assumir que ela está isolada.

#Multimodalidade: 4B, 12B e 27B aceitam imagens

Ao contrário do Gemma 2, que trabalha exclusivamente com texto, os modelos Gemma 3 4B, 12B e 27B incorporam um codificador de imagens SigLIP que processa imagens redimensionadas para 896×896 pixels; apenas o 1B continua restrito a texto. Na prática, se seu aplicativo migrar para um 12B ou um 27B, ele herdará a capacidade de receber imagens, mesmo que não a utilize: isso altera o formato de API esperado por alguns runtimes (campo de imagem além do texto) e pode aumentar levemente a memória necessária para o carregamento, mesmo sem nenhuma imagem enviada.

Essa mudança para o multimodal tem uma consequência prática frequentemente esquecida na migração: um pipeline que validava rigorosamente o formato das mensagens de entrada (esquema JSON, tipagem estrita) pode rejeitar ou interpretar incorretamente um campo de imagem ausente ou vazio se o cliente da API do novo modelo o adicionar por padrão. Por outro lado, um pipeline que já filtrava entradas não textuais antes da chamada ao modelo não precisa mudar nada: a capacidade de imagem do Gemma 3 permanece inativa enquanto nenhuma imagem for transmitida; ela nunca é imposta.

#Quantização QAT: uso de memória dividido por um fator de 3 a 4

O Google publica checkpoints do Gemma 3 treinados levando em conta a quantização (QAT), além das versões Q4_0 clássicas para Ollama, llama.cpp e MLX. A vantagem: uma perda de qualidade bem menor do que a causada por uma quantização aplicada posteriormente a um modelo não preparado para isso.

Esses números são os divulgados pelo Google no lançamento dos checkpoints QAT; eles descrevem a memória necessária para carregar os pesos, não a memória total utilizada na geração (o contexto e o cache KV são adicionados). Uma medição feita em sua própria máquina continua o único meio de confirmar um valor para seu uso específico.

O método adotado pelo Google aplica aproximadamente 5.000 passos de treinamento consciente de quantização, usando as probabilidades do modelo não quantizado como alvo, o que reduz a queda de perplexidade em 54% em comparação com uma quantização aplicada após o treinamento em um modelo que não foi preparado para isso. Para aplicações migradas do Gemma 2, isso significa que um mesmo nível de quantização (por exemplo, Q4) em Gemma 3 gera, geralmente, um resultado mais próximo do modelo em precisão total do que o produzido por Gemma 2 quantizado de forma tradicional — um ganho que vem da preparação do modelo, e não de ajustes feitos pelo usuário.

#Migrar para Gemma 3 ou esperar Gemma 4?

O Gemma 4 já está disponível no Ollama no momento em que este guia é escrito, o que levanta uma questão importante para quem ainda está migrando do Gemma 2: vale a pena parar no Gemma 3 ou partir diretamente para a geração seguinte? A página do Gemma 4 no Ollama anuncia tamanhos diferentes dos do Gemma 3 (variantes E2B e E4B com um número reduzido de parâmetros efetivos, um modelo de 12B, uma variante MoE de 26B com 3,8 bilhões de parâmetros ativos e um modelo denso de 31B), com variantes voltadas para raciocínio, fluxos de trabalho com agentes e código — um escopo mais amplo do que a mera substituição do Gemma 2.

Para uma aplicação já em produção usando Gemma 2, este guia continua focado na migração para Gemma 3: as verificações de contexto, de template e de regressão descritas aqui se aplicam exatamente da mesma forma se o destino final for Gemma 4, mas a migração direta altera mais coisas (papéis de chat padrão, novos tamanhos, arquitetura MoE na variante 26B) do que uma migração Gemma 2 → Gemma 3. Um guia dedicado detalha a instalação e o desempenho do Gemma 4 em execução local.

#Checklist antes de migrar para produção

Versão do runtime

Verificar se Ollama, llama.cpp ou MLX suportam a versão desejada do Gemma 3 (suporte adicionado após o lançamento do modelo, nem sempre imediato em uma versão antiga do runtime).

Contexto realmente configurado

Não deixar ao acaso o valor de contexto do servidor: defini-lo explicitamente de acordo com suas necessidades reais, e não com o limite do modelo.

Formato de entrada de imagem

Se você migrar para 4B, 12B ou 27B, verificar se seu cliente de API não envia um formato de imagem incompatível com o novo endpoint.

Escolha da quantização

Comparar um GGUF Q4_K_M clássico e um checkpoint QAT oficial usando seus próprios prompts antes de definir uma escolha; ambos existem para Gemma 3.

Janela de rollback

Manter o modelo Gemma 2 e sua configuração disponíveis durante a fase de troca, até confirmar a ausência de regressão.

#Detectar uma regressão em seus prompts

Uma migração de modelo não se valida com base em uma impressão após duas ou três perguntas. Um conjunto de prompts de referência, representativo do uso real da aplicação, reproduzido exatamente no modelo antigo e no novo, é o único meio de detectar uma regressão silenciosa: resposta mais longa, mas menos precisa, perda de um formato de saída esperado (JSON, lista) ou desvio de tom. Manter essas saídas de referência também permite documentar a decisão de migração, em vez de se basear em uma impressão.

#Prever um rollback

O cenário mais seguro para uma aplicação em produção consiste em implantar o Gemma 3 em paralelo com o Gemma 2 (com um nome de modelo distinto no ambiente de execução), encaminhar parte do tráfego para a nova versão e desativar a antiga somente quando as métricas de qualidade nos seus prompts de referência forem pelo menos equivalentes. Isso consome um pouco de espaço em disco e de RAM durante a transição, mas evita uma interrupção do serviço se o novo template de chat ou o novo contexto produzir um comportamento inesperado em condições reais.

• Instalar o Gemma 3 localmente, passo a passo
• Entender os formatos GGUF e safetensors
• Comparar IA local e ChatGPT
• Gemma 4 localmente: instalação, VRAM e desempenho
• Escolher sua quantização (Q4, Q5, Q8, FP16)
• Quantizar o cache KV para economizar VRAM em contextos longos
• Fonte: apresentação oficial de Gemma 3 (Hugging Face)
• Fonte: checkpoints QAT Gemma 3 (Google Developers Blog)
• Fonte: apresentação oficial do Gemma 2 (Hugging Face)
• Fonte: página do Gemma 4 no Ollama