Implantação local do EmbeddingGemma 2: guia de riscos da migração

Implantar o EmbeddingGemma 2 localmente não significa, por si só, ter um substituto imediato para um serviço de embeddings existente. O runtime pode mudar com pouco trabalho na aplicação, mas alterar o contrato da representação geralmente exige reconstruir os vetores. O plano mais seguro é separar três decisões: como o modelo será executado, se os vetores atuais continuam compatíveis e se a recuperação multimodal atende ao seu corpus.

A decisão de migração em uma página

Use o EmbeddingGemma 2 quando precisar de embeddings locais de texto, código, imagem, vídeo ou áudio dentro da mesma família de modelos e puder fazer um backfill controlado. Não troque primeiro o encoder de consultas em produção para só depois “alcançar” os documentos: o modelo de embeddings faz parte do schema do índice, mesmo quando a dimensão do vetor parece familiar.

O model card do Google informa 61,36 no MTEB multilingual v2, 78,68 no MTEB code v1, 67,84 de NDCG@5 na recuperação de documentos visuais, 50,67 de Hit@1 na recuperação de vídeos e 69,54 de MRR@10 na recuperação de áudio em 768 dimensões. Esses números são referências úteis, mas não substituem os testes com suas próprias consultas.

O que muda — e o que não muda — ao migrar para o EmbeddingGemma 2

O EmbeddingGemma 2 mapeia texto, código, imagens, vídeo e áudio para um espaço compartilhado de 768 dimensões. O checkpoint é modular: o guia oficial para desenvolvedores descreve uma configuração de 270 milhões de parâmetros somente para texto, uma configuração de 440 milhões para texto e visão, uma de 570 milhões para texto e áudio e a configuração completa de 740 milhões. Desativar um encoder reduz os pesos carregados e o pico de memória; isso, por si só, não cria um novo espaço semântico.

Essa distinção é importante durante a migração. Uma consulta de texto produzida com a configuração de 270 milhões pode ser comparada com um embedding de documento do EmbeddingGemma 2 gerado com a configuração completa, porque o Google documenta essas configurações como compartilhando um espaço vetorial compatível. Isso não significa que um vetor antigo do EmbeddingGemma 1, Qwen, Nomic ou de um provedor de API possa ser consultado com segurança pelo EmbeddingGemma 2 apenas porque também tem 768 coordenadas.

A formatação da tarefa também faz parte do contrato. Para recuperação assimétrica, o EmbeddingGemma 2 espera uma instrução de consulta como task: search result | query: ... e um formato de documento como title: ... | text: .... A recuperação de código tem sua própria instrução de tarefa. Se o pipeline antigo usava outros prefixos, chunking, normalização ou campos incorporados, registre essas alterações como uma nova versão da representação e valide tudo como uma migração.

Suporte de runtime: escolha o caminho local mais enxuto

Comece pelo Sentence Transformers para garantir a correção

O model card oficial documenta o google/embeddinggemma-2 com Sentence Transformers e Transformers. Instale os extras multimodais quando precisar de suporte a mídia:

pip install -U "sentence-transformers[image,audio,video]" transformers

Esse é o melhor caminho de referência para uma migração, porque nomes de prompts, truncamento, normalização e comportamento das entradas multimodais seguem os exemplos oficiais. Ele não é necessariamente o caminho de menor latência para servir o modelo, mas fornece uma linha de base confiável antes da otimização.

Um teste mínimo somente de texto pode ser assim:

from sentence_transformers import SentenceTransformer

model = SentenceTransformer(
    "google/embeddinggemma-2",
    config_kwargs={"vision_config": None, "audio_config": None},
)
query = model.encode(
    "embedding model migration",
    prompt_name="SearchQuery",
    truncate_dim=256,
    normalize_embeddings=True,
)
document = model.encode(
    "Rebuild vectors when the embedding representation changes.",
    prompt_name="Document",
    truncate_dim=256,
    normalize_embeddings=True,
)
print(model.similarity(query, document).item())

Execute esse teste antes de introduzir um servidor, quantização ou banco de dados vetorial. Ele verifica se o checkpoint, os prompts de tarefa, a dimensão e o caminho de normalização funcionam em conjunto.

Use runtimes do ecossistema somente depois de conferir a paridade de recursos

O guia para desenvolvedores do Google lista vLLM, Hugging Face Transformers, Sentence Transformers, SGLang, MLX, Ollama, LM Studio e LiteRT como ferramentas compatíveis de desenvolvimento ou implantação. Trate essa lista como um sinal de disponibilidade, não como prova de que todos os runtimes expõem a mesma combinação de texto, imagem, vídeo, áudio, interleaving, prefixos de tarefa, truncamento e batching.

Para cada runtime candidato, verifique cinco itens com uma requisição real: a revisão exata do checkpoint, as entradas das modalidades que você usa, as dimensões de saída, a normalização após o truncamento e o comportamento dos prefixos de consulta e documento. Um runtime que serve texto rapidamente, mas ignora seu fluxo de documentos visuais, não equivale ao modelo completo.

Um servidor nativo compacto é uma otimização, não o plano de migração

O repositório público embeddinggemma.c fornece um servidor especializado em C11/Metal para o EmbeddingGemma 300M, com variantes para CPU, Metal, CUDA, ROCm e Intel XPU. O README documenta um endpoint /v1/embeddings compatível com OpenAI, dimensões 768/512/256/128 e um download de modelo Q4_0 de 278 MB. O projeto relata uma comparação controlada em um Apple M5 Max contra o build b8981 do llama.cpp em 54 células, com uma vantagem de média geométrica de 1,25×; esses resultados são específicos de throughput do projeto, não uma comparação de qualidade nem uma prova de paridade multimodal com o checkpoint de 740 milhões de parâmetros.

A característica mais útil para a migração é o formato da API. Se a aplicação já usa embeddings no estilo OpenAI, um servidor local compatível com esse endpoint pode reduzir o trabalho de adaptação. Ainda assim, mantenha o resultado do Sentence Transformers como referência de correção até que o comportamento de modalidades e prefixos do servidor corresponda ao pipeline de produção.

Risco de reconstrução do índice: dimensão é apenas um dos eixos da migração

Gere novos embeddings quando a função de origem para vetor mudar

Considere uma reconstrução completa quando alterar a família do modelo, a versão do modelo, o prefixo da tarefa, a normalização, o chunking, a política de truncamento, os campos incorporados ou a semântica de similaridade. O guia de migração do Qdrant e a análise de migração de modelos da Nalar destacam o mesmo ponto operacional: os vetores de documentos e consultas precisam pertencer à mesma versão da representação. Dimensões iguais não comprovam compatibilidade semântica.

Não corte um vetor antigo de 768 dimensões e o trate como um vetor de 256 dimensões do EmbeddingGemma 2. As saídas Matryoshka do EmbeddingGemma 2 são treinadas para tamanhos de truncamento compatíveis e precisam ser renormalizadas depois do truncamento. O model card informa as seguintes pontuações oficiais de referência:

O model card oficial também informa 67,84 de NDCG@5 na recuperação de documentos visuais e 50,67 de Hit@1 na recuperação de vídeos em 768 dimensões; use esses números como linhas de base na largura completa, sem inventar valores para dimensões reduzidas. A conclusão segura é direcional: 256d fica muito mais próximo da qualidade completa do que 128d, e as pontuações multimodais caem de forma mais acentuada em 128d. Use o checkpoint oficial para regenerar cada vetor na dimensão escolhida, em vez de truncar vetores de outro modelo.

O espaço compartilhado do EmbeddingGemma 2 pode evitar trabalho desnecessário

Há uma exceção importante. Se o corpus existente já foi incorporado com o EmbeddingGemma 2 e você está apenas carregando um subconjunto diferente de seus encoders, o guia para desenvolvedores do Google afirma que as configurações compartilham um espaço vetorial. Uma consulta somente de texto pode encontrar um vetor de documento gerado pelo modelo completo. Nesse caso, talvez não seja necessário regenerar os vetores de texto existentes apenas porque o processo de serving agora carrega suporte a visão ou áudio.

Ainda será necessário gerar novos vetores para registros que contenham mídia. Um índice somente de texto não pode recuperar uma imagem, vídeo ou item de áudio que nunca foi incorporado. Portanto, adicionar recuperação multimodal é uma migração incremental do corpus, mesmo quando o checkpoint do modelo permanece igual.

Faça a virada usando blue-green ou named vectors

Para um sistema em produção, o padrão de migração do Qdrant é o modelo mais claro: crie uma nova collection, grave novos registros nas duas versões, faça o backfill a partir dos dados-fonte oficiais, compare Recall@10/MRR/nDCG@10, troque um alias e mantenha a collection antiga para rollback. O guia do Qdrant usa a versão 1.19.0, um exemplo com 512 dimensões e lotes de 100 pontos; esses valores são exemplos, não requisitos do EmbeddingGemma 2.

Um design com named vectors pode manter representações antigas e novas na mesma collection, mas somente se seu banco vetorial oferecer esse recurso e o fluxo de atualização gravar as duas versões de forma consistente. O guia de migração de vectorizer do Weaviate recomenda aliases de collection em produção, porque a collection antiga pode ser mantida para um rollback imediato e excluída depois da validação. A alternativa — adicionar um vetor à collection existente — pode aumentar permanentemente o armazenamento e é mais adequada para comparação do que para um estado final limpo.

Qualidade multimodal: valide os recortes que o modelo altera

O espaço compartilhado do EmbeddingGemma 2 só é valioso se o comportamento da recuperação combinar com seus dados. Um benchmark somente de texto pode confirmar que a migração não quebrou a busca textual e, ainda assim, deixar passar falhas em páginas de PDF, gráficos, legendas de imagens, frames de vídeo, clipes de áudio ou registros intercalados.

Comece com recortes rotulados separados:

1. Consulta de texto → trecho de texto.
2. Consulta de código → trecho de código.
3. Consulta de texto → imagem ou documento visual.
4. Consulta de texto → frame de vídeo ou segmento de áudio.
5. Consulta mista de texto e mídia → documento misto.
6. Consulta multilíngue → documento nos idiomas que você oferece.

Mantenha 768d ou 512d como primeira linha de base multimodal. O model card oficial atribui 280 tokens por imagem, 140 tokens por frame de vídeo e 25 tokens por segundo de áudio dentro de um contexto compartilhado de 8.192 tokens. As entradas mistas consomem o mesmo orçamento, portanto um registro com texto, imagens e vídeo terá menos espaço para cada componente do que uma entrada de modalidade única.

O model card também informa que 128d provoca uma queda de qualidade maior nas tarefas multimodais do que nas tarefas somente de texto. Isso torna 128d um candidato razoável para uma primeira triagem em um índice textual grande, mas não uma configuração padrão para um arquivo de mídia mista. Teste 256d com suas consultas reais de documentos visuais e de recuperação cross-modal antes de aceitar a economia de armazenamento.

Compare um pipeline unificado com EmbeddingGemma 2 ao pipeline atual separado de texto e imagem usando consultas idênticas; não deduza a qualidade multimodal apenas da arquitetura de espaço compartilhado do modelo.

Plano de implantação em etapas para um sistema RAG existente

1. Faça o inventário do contrato atual. Registre o ID do modelo, a revisão do checkpoint, os prefixos, o chunking, as dimensões, a métrica, a normalização, os campos de origem e todas as modalidades já indexadas.
2. Crie um conjunto de avaliação representativo. Inclua metas de Recall@k, MRR ou nDCG, além de recortes separados para texto, código, documentos visuais, áudio, vídeo, idioma e consultas longas.
3. Estabeleça a linha de base local. Passe o mesmo corpus primeiro pelo Sentence Transformers. Registre latência de geração dos embeddings, latência de busca, memória, tamanho do índice, falhas e distribuição das pontuações.
4. Crie um índice candidato versionado. Mantenha IDs de documentos estáveis e o texto/mídia de origem fora do banco vetorial, para que o backfill possa ser reproduzido.
5. Concilie as gravações durante o backfill. Use um snapshot da origem mais replay das alterações, ou grave registros novos e atualizados nas duas versões da representação.
6. Envie consultas de produção em modo shadow. Compare resultados ranqueados, taxas de resultados vazios, latência e relevância rotulada sem alterar as respostas visíveis para os usuários.
7. Faça a virada de forma atômica. Vincule o encoder de consultas do EmbeddingGemma 2 e o índice correspondente sob uma única versão ou alias. Nunca coloque o novo encoder de consultas para operar contra o índice antigo como etapa intermediária.
8. Mantenha o rollback disponível. Preserve o índice e o caminho de consultas antigos até que o tráfego representativo ultrapasse os limites de aceitação; depois, interrompa as gravações duplas e recupere o armazenamento.

Perguntas frequentes

O EmbeddingGemma 2 pode rodar somente em CPU?

Sim, com um runtime compatível com CPU. O model card recomenda float32 quando bfloat16 não estiver disponível, e a configuração somente de texto tem 270 milhões de parâmetros. O throughput em CPU depende do runtime, da precisão, do batching e do hardware; por isso, meça tudo no seu corpus em vez de aproveitar números de GPU.

A escolha do runtime é um equilíbrio entre correção de referência, paridade de recursos, eficiência de serving e o custo de validar uma nova versão da recuperação.