API di EmbeddingGemma 2: deployment locale e casi d’uso multimodali

Cercando una API di EmbeddingGemma 2 è fondamentale distinguere due prodotti: l’API di embedding ospitata da Google si chiama Gemini Embedding 2, mentre EmbeddingGemma 2 è un modello open pensato soprattutto per l’inferenza locale e sui dispositivi edge. È quindi una scelta interessante per la ricerca multimodale con dati privati, ma richiede di selezionare e gestire autonomamente il livello di serving.

EmbeddingGemma 2 è disponibile come API Google?

EmbeddingGemma 2 è stato rilasciato ufficialmente, ma la documentazione attuale delle API Gemini gestite da Google indica gemini-embedding-2, non embeddinggemma-2. La scheda del modello EmbeddingGemma 2 e la guida per sviluppatori di Google descrivono un modello scaricabile da usare con librerie locali come Sentence Transformers.

Un endpoint locale /v1/embeddings viene esposto dal runtime scelto per il deployment, non da Google Cloud. Se invece ti riferivi al servizio gestito, la documentazione di Gemini Embedding 2 mostra SDK cloud e formati delle richieste: usa gemini-embedding-2, non 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)

La chiamata gestita utilizza l’API ospitata da Google; il modello locale, invece, è soggetto alle credenziali e ai limiti imposti dal runtime che hai scelto di eseguire.

Cosa contiene davvero il modello locale

EmbeddingGemma 2 è un modello multimodale per embedding da 740 milioni di parametri. L’architettura separa un nucleo testuale da 270M da encoder opzionali per immagini e audio, così il deployment può caricare soltanto le modalità necessarie. Google e DeepMind lo presentano per la ricerca su testo, codice, immagini, video e audio, non per la generazione di testo.

La scheda del modello descrive uno spazio vettoriale condiviso per confrontare contenuti di modalità diverse. Il valore di 740M si riferisce al modello completo; la guida per sviluppatori di Google mostra che è possibile usare selettivamente gli encoder, riducendo memoria occupata e calcolo attivo nei percorsi di solo testo che escludono visione e audio.

Scegli il percorso di serving in base alla destinazione

Sentence Transformers per un’applicazione Python

Per un servizio Python, il percorso documentato ufficialmente consiste nell’usare il checkpoint google/embeddinggemma-2 tramite Sentence Transformers. Questa soluzione offre un controllo diretto su batching, assegnazione ai dispositivi, prompt, normalizzazione e troncamento dei vettori.

Un flusso di retrieval dovrebbe usare istruzioni separate per query e documenti. Negli esempi di Google, la query usa un prefisso dedicato alla ricerca, mentre il documento segue un formato come title: none | text: .... La scelta più sicura è usare model.encode con il nome del prompt corretto, invece di generare gli embedding di entrambi i lati con una chiamata generica.

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,
)

Scegli questa strada se vuoi il massimo controllo dal codice Python; quando più servizi devono condividere un contratto stabile, è preferibile un runtime che esponga il modello via HTTP.

Ollama per un endpoint REST locale immediato

La pagina di EmbeddingGemma 2 su Ollama mette a disposizione una semplice API locale all’indirizzo 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"
  }'

Ollama elenca tag del modello come 270m, 440m, 570m e 740m; le dimensioni dei pacchetti visibili vanno da circa 378 MB a 1,3 GB. Considerali varianti del modello confezionate separatamente, non etichette intercambiabili per il checkpoint completo da 740M. Prima di definire un contratto di produzione, verifica il tag installato e le modalità di input supportate: la descrizione della famiglia è multimodale, ma le schede delle varianti visibili non documentano tutte le modalità con lo stesso livello di chiarezza.

Servono comunque prefissi coerenti per i diversi task, corrispondenza tra modello e dimensione dei vettori e una ricostruzione dell’indice quando cambi modello.

Runtime edge per il deployment sui dispositivi

Google AI Edge documenta EmbeddingGemma V2 nella guida Universal Embedder, mentre la documentazione dei modelli di embedding LiteRT-LM descrive un modello di serving locale compatibile con OpenAI che espone /v1/embeddings. È il percorso da preferire quando il funzionamento offline e la privacy garantita dal dispositivo contano più della comodità di un deployment cloud tradizionale.

Per un server su hardware ordinario, conviene partire da Sentence Transformers o Ollama. Passa a un runtime specifico per l’edge quando funzionamento offline, privacy, ingombro all’avvio o integrazione con il dispositivo sono requisiti prioritari.

Casi d’uso multimodali che giustificano un modello più grande

EmbeddingGemma 2 dà il meglio quando il progetto deve usare un unico spazio di ricerca per contenuti di tipo diverso.

Ricerca nel codice e retrieval per sviluppatori

La tabella di valutazione pubblicata riporta per EmbeddingGemma 2 un punteggio MTEB Code di 78.68, contro 68.76 per EmbeddingGemma 1 nel benchmark del codice citato. È un buon motivo per provarlo nella ricerca nei repository, nel recupero della documentazione delle API e nei flussi RAG orientati al codice, ma non garantisce gli stessi risultati per la tua combinazione di linguaggi o per il tuo codebase.

Quando il modello più grande non vale la migrazione

In una pipeline che riceve esclusivamente testo OCR ordinario, il supporto multimodale può aggiungere complessità senza migliorare la qualità del retrieval. Un utente di Paperless-ngx ha riassunto così il compromesso:

“Non sono sicuro che embeddinggemma-2 sia migliore di regular embeddinggemma per il semplice OCR che paperless-ngx invia al modello. Sembra molto più lavoro per ottenere gli stessi risultati.” — u/Great-Cow7256, Reddit

Non è un risultato di benchmark, ma mette a fuoco il test giusto per una migrazione: confronta la qualità del retrieval sul tuo corpus reale prima di ricostruire un indice testuale che già funziona.

Come scegliere la dimensione: 768d, 512d, 256d o 128d

La documentazione di Google sugli embedding descrive per EmbeddingGemma 2 il troncamento in stile Matryoshka, che consente di scegliere una rappresentazione più compatta dopo la codifica. I vettori più piccoli riducono lo spazio occupato dall’indice e le dimensioni del trasferimento, ma con l’impostazione più aggressiva la qualità diminuisce.

Questi valori sono ripresi dalla tabella di valutazione pubblicata nella pagina del modello su Ollama. Per un nuovo indice multimodale, parti da 768d; scegli 512d o 256d quando lo spazio di archiviazione è un vincolo e usa 128d solo dopo aver testato un carico di lavoro ricco di testo.

Non combinare dimensioni diverse nello stesso indice vettoriale. Se un database esistente contiene vettori da 768 dimensioni, il passaggio a 256d richiede di generare nuovamente gli embedding dei documenti indicizzati e ricostruire l’indice. I vettori delle query devono usare lo stesso modello, gli stessi prompt, la stessa normalizzazione e la stessa dimensione dei vettori dei documenti.

Decidi in base al flusso di lavoro, non alle dimensioni del modello

Usa Gemini Embedding 2 per un endpoint Google gestito. Scegli Sentence Transformers per il controllo dal codice Python, Ollama per un servizio HTTP locale rapido e AI Edge/LiteRT-LM quando conta il deployment offline sui dispositivi.

Mantieni un modello più piccolo e solo testuale se il corpus è composto da semplice OCR e l’indice attuale raggiunge il livello di rilevanza richiesto. EmbeddingGemma 2 può semplificare un’architettura multimodale, ma non migliora automaticamente una pipeline solo testuale.

Domande frequenti sull’API di EmbeddingGemma 2

EmbeddingGemma 2 è disponibile tramite l’API Gemini?

La documentazione dell’API Gemini gestita da Google identifica attualmente gemini-embedding-2. EmbeddingGemma 2 è documentato soprattutto come modello open per l’inferenza locale, anche se i runtime locali possono esporre endpoint compatibili con le API.

EmbeddingGemma 2 può funzionare su CPU?

L’inferenza su CPU è possibile con i runtime locali che offrono esplicitamente un backend CPU; la documentazione AI Edge sugli embedding è il riferimento per il runtime. Le prestazioni dipendono comunque da hardware, quantizzazione, dimensione del batch e modalità utilizzata.

È necessario ricostruire i vettori esistenti?

Di solito sì, se cambi modello di embedding, formato dei task, politica di normalizzazione o dimensione dei vettori. Salva insieme all’indice l’identificativo del modello, la dimensione e i metadati di pre-processing, così la migrazione potrà essere riprodotta.