API do EmbeddingGemma 2: implantação local e casos de uso multimodais

Quem pesquisa por uma API do EmbeddingGemma 2 precisa entender uma diferença importante: a API de embeddings hospedada pelo Google usa o modelo Gemini Embedding 2, enquanto o EmbeddingGemma 2 é um modelo aberto pensado principalmente para inferência local e em dispositivos de borda. Isso o torna interessante para buscas multimodais privadas, mas também significa que você terá de escolher e operar a própria camada de serviço.

O EmbeddingGemma 2 está disponível como uma API do Google?

O EmbeddingGemma 2 foi lançado oficialmente, mas a documentação atual da API Gemini gerenciada pelo Google cita gemini-embedding-2, e não embeddinggemma-2. O model card do EmbeddingGemma 2 e o guia para desenvolvedores do Google descrevem um modelo baixável, usado com bibliotecas locais como o Sentence Transformers.

Um endpoint local /v1/embeddings é disponibilizado pelo runtime que você implantar, não pelo Google Cloud. Se a sua intenção era usar o serviço gerenciado, a documentação do Gemini Embedding 2 mostra o SDK em nuvem e os formatos das requisições; use gemini-embedding-2, não embeddinggemma-2.

from google import genai

client = genai.Client()
result = client.models.embed_content(
    model="gemini-embedding-2",
    contents="A private semantic search service",
)
print(result.embeddings)

A chamada gerenciada usa a API hospedada pelo Google. Já o modelo local fica sujeito às credenciais e aos limites definidos pelo runtime que você escolher.

O que há de fato no modelo local

O EmbeddingGemma 2 é um gerador multimodal de embeddings com 740 milhões de parâmetros. A arquitetura separa um núcleo de texto com 270 milhões de parâmetros dos codificadores opcionais de visão e áudio, permitindo carregar apenas as modalidades necessárias em cada implantação. Google e DeepMind posicionam o modelo para buscas de texto, código, imagens, vídeos e áudio — não para geração de texto.

O model card descreve um espaço vetorial compartilhado para comparações entre modalidades. A marca de 740 milhões de parâmetros se refere ao modelo completo; o guia para desenvolvedores do Google mostra o uso seletivo dos codificadores. Na prática, memória e processamento podem ser menores em fluxos apenas de texto que não carregam visão e áudio.

Escolha o caminho de serviço conforme o destino da implantação

Sentence Transformers para uma aplicação em Python

Em um serviço Python, o caminho oficialmente documentado usa o checkpoint google/embeddinggemma-2 por meio do Sentence Transformers. Essa opção oferece controle direto sobre lotes, alocação no dispositivo, prompts, normalização e truncamento dos vetores.

Um fluxo de recuperação deve usar instruções separadas para consultas e documentos. Os exemplos do Google usam um prefixo de busca na consulta e um formato de documento como title: none | text: .... O caminho mais seguro é chamar model.encode com o nome do prompt correspondente, em vez de gerar os embeddings dos dois lados com uma chamada genérica.

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("google/embeddinggemma-2")

query_vector = model.encode(
    "How do I rotate an API key?",
    prompt_name="query",
    normalize_embeddings=True,
)
document_vectors = model.encode(
    [
        "title: API keys | text: Rotate keys from the security settings page.",
        "title: Billing | text: Download invoices from the billing page.",
    ],
    prompt_name="document",
    normalize_embeddings=True,
)

Escolha esse caminho quando precisar de controle no nível do Python. Se vários serviços precisarem de um contrato estável, prefira um runtime que ofereça o modelo por HTTP.

Ollama para um endpoint REST local rápido

A página do EmbeddingGemma 2 no Ollama oferece uma API local simples em http://localhost:11434/api/embed:

ollama pull embeddinggemma-2

curl http://localhost:11434/api/embed \\
  -d '{
    "model": "embeddinggemma-2",
    "input": "A private semantic search service"
  }'

O Ollama lista tags como 270m, 440m, 570m e 740m; os tamanhos visíveis dos pacotes vão de aproximadamente 378 MB a 1,3 GB. Trate essas opções como variantes de modelo empacotadas separadamente, não como rótulos intercambiáveis do checkpoint completo de 740 milhões de parâmetros. Antes de definir um contrato para produção, confirme a tag instalada e as modalidades de entrada compatíveis: a descrição da família é multimodal, mas as listagens visíveis das variantes não documentam todas as modalidades com o mesmo nível de clareza.

Você também precisará manter consistentes os prefixos das tarefas, o modelo, as dimensões e reconstruir o índice sempre que trocar de modelo.

Runtimes de borda para implantação em dispositivos

O Google AI Edge documenta o EmbeddingGemma V2 em seu guia do Universal Embedder, enquanto a documentação de modelos de embeddings do LiteRT-LM descreve um padrão local de serviço compatível com OpenAI, usando /v1/embeddings. Essa é a opção indicada quando operação offline e privacidade no dispositivo são mais importantes do que a conveniência de uma implantação convencional na nuvem.

Para um servidor em hardware comum, comece com Sentence Transformers ou Ollama. Migre para um runtime específico de borda quando operação offline, privacidade, tamanho de inicialização ou integração com o dispositivo forem requisitos prioritários.

Casos de uso multimodais que justificam um modelo maior

O EmbeddingGemma 2 se torna mais interessante quando o projeto precisa de um único espaço de busca para diferentes tipos de mídia.

Busca de código e recuperação para desenvolvedores

A tabela de avaliações publicada informa uma pontuação MTEB Code de 78,68 para o EmbeddingGemma 2, contra 68,76 do EmbeddingGemma 1 no benchmark de código citado. É um bom motivo para testá-lo em buscas por repositórios, recuperação de documentação de APIs e RAG voltado a código, mas o resultado não garante o mesmo desempenho na sua combinação de linguagens ou na sua base de código.

Quando o modelo maior não compensa a migração

Em um pipeline que recebe apenas texto comum de OCR, o suporte multimodal pode aumentar a complexidade sem melhorar a qualidade da recuperação. Um usuário do Paperless-ngx resumiu a troca desta forma:

“Não tenho certeza se o embeddinggemma-2 é melhor que o embeddinggemma comum para o OCR simples que o paperless-ngx envia ao modelo. Parece muito mais trabalho para obter os mesmos resultados.” — u/Great-Cow7256, Reddit

Isso não é um resultado de benchmark, mas traduz bem o teste que deve orientar a migração: compare a qualidade da recuperação no seu corpus real antes de reconstruir um índice de texto que já funciona.

Escolha da dimensão: 768d, 512d, 256d ou 128d

A documentação de embeddings do Google explica o truncamento no estilo Matryoshka para o EmbeddingGemma 2, permitindo escolher uma representação menor depois da codificação. Vetores menores reduzem o armazenamento do índice e o tamanho das transferências, mas a qualidade cai na configuração mais agressiva.

Esses números foram reproduzidos da tabela de avaliações publicada na página do modelo no Ollama. Para um novo índice multimodal, comece com 768d; use 512d ou 256d quando o armazenamento for uma preocupação; e escolha 128d somente depois de testar um workload com predominância de texto.

Não misture dimensões dentro do mesmo índice vetorial. Se um banco existente armazena vetores de 768 dimensões, a mudança para 256d exige gerar novamente os embeddings dos documentos indexados e reconstruir o índice. Os vetores das consultas precisam usar o mesmo modelo, os mesmos prompts, a mesma normalização e a mesma dimensão dos vetores dos documentos.

Tome a decisão pelo fluxo de trabalho, não pelo tamanho do modelo

Use o Gemini Embedding 2 para um endpoint gerenciado pelo Google. Prefira o Sentence Transformers quando precisar de controle no nível do Python, o Ollama para um serviço HTTP local rápido e o AI Edge/LiteRT-LM quando a implantação offline em dispositivos for importante.

Mantenha um modelo menor, específico para texto, quando o corpus for composto de OCR simples e o índice atual já atingir a meta de relevância. O EmbeddingGemma 2 pode simplificar uma arquitetura multimodal, mas não melhora automaticamente uma arquitetura baseada apenas em texto.

FAQ da API do EmbeddingGemma 2

O EmbeddingGemma 2 está disponível pela API Gemini?

A documentação da API Gemini gerenciada pelo Google identifica atualmente o gemini-embedding-2. O EmbeddingGemma 2 é documentado principalmente como um modelo aberto para inferência local, embora runtimes locais possam disponibilizar endpoints compatíveis com APIs.

O EmbeddingGemma 2 roda em CPU?

A inferência em CPU pode ser usada com runtimes locais que ofereçam explicitamente um backend para CPU; a documentação de embeddings do AI Edge é a referência relevante para o runtime. O desempenho ainda depende do hardware, da quantização, do tamanho do lote e da modalidade.

É preciso reconstruir os vetores existentes?

Em geral, sim, se você mudar o modelo de embeddings, a formatação das tarefas, a política de normalização ou a dimensão dos vetores. Mantenha o identificador do modelo, a dimensão e os metadados de pré-processamento junto ao índice para que a migração possa ser reproduzida.