Deployment locale di EmbeddingGemma 2: guida ai rischi della migrazione

Portare EmbeddingGemma 2 in locale non significa automaticamente sostituire senza modifiche il servizio di embedding esistente. Il runtime può cambiare con un impatto minimo sull’applicazione, ma quando cambia il contratto di rappresentazione di solito bisogna ricreare i vettori. Il piano più sicuro separa tre decisioni: come eseguire il modello, se i vettori attuali sono ancora compatibili e se il retrieval multimodale offre una qualità sufficiente sul proprio corpus.

La decisione di migrazione in sintesi

Scegli EmbeddingGemma 2 se ti servono embedding locali per testo, codice, immagini, video o audio all’interno della stessa famiglia di modelli e puoi sostenere un backfill controllato. Non cambiare prima l’encoder delle query in produzione per poi “mettersi in pari” con i documenti: il modello di embedding fa parte dello schema dell’indice, anche quando la dimensione del vettore sembra la stessa.

La model card di Google riporta 61.36 su MTEB multilingual v2, 78.68 su MTEB code v1, 67.84 NDCG@5 nel visual-document retrieval, 50.67 Hit@1 nel video retrieval e 69.54 MRR@10 nell’audio retrieval a 768 dimensioni. Sono riferimenti utili, ma non sostituiscono i test sulle proprie query.

Cosa cambia — e cosa resta uguale — passando a EmbeddingGemma 2

EmbeddingGemma 2 proietta testo, codice, immagini, video e audio in uno spazio condiviso a 768 dimensioni. Il checkpoint è modulare: la guida ufficiale per gli sviluppatori descrive una configurazione da 270M per il solo testo, una da 440M per testo e visione, una da 570M per testo e audio e una configurazione completa da 740M. Disattivare un encoder riduce i pesi caricati e il picco di memoria; da solo, però, non crea un nuovo spazio semantico.

Questa distinzione è fondamentale durante la migrazione. Una query testuale prodotta con la configurazione da 270M può essere confrontata con un embedding documentale di EmbeddingGemma 2 generato con la configurazione completa, perché Google documenta queste configurazioni come compatibili all’interno dello stesso spazio vettoriale. Questo non significa che un vettore precedente di EmbeddingGemma 1, Qwen, Nomic o di un provider API possa essere interrogato in sicurezza con EmbeddingGemma 2 solo perché ha anch’esso 768 coordinate.

Anche il formato delle istruzioni fa parte del contratto. Per il retrieval asimmetrico, EmbeddingGemma 2 si aspetta un’istruzione per la query, ad esempio task: search result | query: ..., e una forma per il documento come title: ... | text: .... Il code retrieval ha una propria istruzione. Se la pipeline precedente usava prefissi, strategie di chunking, normalizzazione o campi incorporati diversi, registra il cambiamento come una nuova versione della rappresentazione e validalo come una vera migrazione.

Supporto dei runtime: scegli il percorso locale più lineare

Parti da Sentence Transformers per garantire la correttezza

La model card ufficiale documenta google/embeddinggemma-2 con Sentence Transformers e Transformers. Se ti serve il supporto ai contenuti multimediali, installa gli extra dedicati:

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

Per una migrazione è il percorso di riferimento migliore, perché nomi dei prompt, troncamento, normalizzazione e gestione degli input multimodali seguono gli esempi ufficiali. Non è necessariamente la soluzione con la latenza più bassa, ma offre una baseline affidabile prima di passare all’ottimizzazione.

Un test minimo per il solo testo è questo:

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

Eseguilo prima di introdurre un server, la quantizzazione o un vector database. Verifica che checkpoint, prompt di task, dimensione e normalizzazione funzionino correttamente insieme.

Passa ai runtime dell’ecosistema solo dopo aver verificato la parità delle funzioni

La guida per gli sviluppatori di Google elenca vLLM, Hugging Face Transformers, Sentence Transformers, SGLang, MLX, Ollama, LM Studio e LiteRT tra gli strumenti supportati per sviluppo o deployment. Considera però quell’elenco un’indicazione di disponibilità, non la prova che ogni runtime esponga la stessa combinazione di testo, immagini, video, audio, input interleaved, prefissi di task, troncamento e batching.

Per ogni runtime candidato verifica cinque aspetti con una richiesta reale: la revisione esatta del checkpoint, i tipi di input multimodale che utilizzi, le dimensioni dell’output, la normalizzazione dopo il troncamento e il comportamento dei prefissi per query e documenti. Un runtime che serve velocemente il testo ma ignora il tuo flusso per i documenti visivi non equivale al modello completo.

Un server nativo compatto è un’ottimizzazione, non il piano di migrazione

Il repository pubblico embeddinggemma.c offre un server specializzato in stile C11/Metal per EmbeddingGemma 300M, con varianti per CPU, Metal, CUDA, ROCm e Intel XPU. Il README documenta un endpoint /v1/embeddings compatibile con OpenAI, dimensioni 768/512/256/128 e un download del modello Q4_0 da 278 MB. Il progetto riporta un confronto controllato su Apple M5 Max con llama.cpp build b8981, condotto su 54 combinazioni, con un vantaggio della media geometrica di 1.25×; sono risultati di throughput specifici del progetto, non un confronto di qualità né la prova della parità multimodale con il checkpoint da 740M.

Il vantaggio più interessante in fase di migrazione è la forma dell’API. Se l’applicazione parla già il protocollo OpenAI per gli embedding, un server locale compatibile con l’endpoint può ridurre il lavoro sugli adapter. Mantieni comunque il risultato di Sentence Transformers come riferimento per la correttezza finché il comportamento del server su modalità e prefissi non coincide con quello della pipeline in produzione.

Rischio di ricostruzione dell’indice: la dimensione è solo uno degli assi

Ricrea gli embedding quando cambia la funzione da sorgente a vettore

Considera necessaria una ricostruzione completa quando cambi famiglia del modello, versione, prefisso del task, normalizzazione, chunking, politica di troncamento, campi incorporati o semantica della similarità. La guida alla migrazione di Qdrant e l’analisi di Nalar sottolineano lo stesso principio operativo: vettori di documenti e query devono appartenere alla stessa versione della rappresentazione. Avere la stessa dimensione non dimostra la compatibilità semantica.

Non prendere un vecchio vettore da 768 dimensioni, tagliarlo e chiamarlo vettore EmbeddingGemma 2 da 256 dimensioni. Gli output Matryoshka di EmbeddingGemma 2 sono addestrati per specifiche dimensioni di troncamento e devono essere rinormalizzati dopo il taglio. La model card riporta questi punteggi ufficiali di riferimento:

La model card ufficiale riporta inoltre 67.84 NDCG@5 nel visual-document retrieval e 50.67 Hit@1 nel video retrieval a 768 dimensioni; usali come baseline a dimensione piena, senza inventare valori per le dimensioni ridotte. La conclusione affidabile è soprattutto direzionale: 256d resta molto più vicino alla qualità completa rispetto a 128d, mentre sui dati multimodali il calo a 128d è più marcato. Rigenera ogni vettore con il checkpoint ufficiale e la dimensione scelta, invece di troncare vettori prodotti da un altro modello.

Lo spazio condiviso di EmbeddingGemma 2 può evitare lavoro inutile

Esiste però un’eccezione importante. Se il corpus attuale è già stato vettorializzato con EmbeddingGemma 2 e stai soltanto caricando un sottoinsieme diverso degli encoder, la guida per gli sviluppatori di Google afferma che le configurazioni condividono lo stesso spazio vettoriale. Una query di solo testo può quindi essere confrontata con un vettore documentale prodotto dal modello completo. In questo caso non è necessariamente necessario rigenerare i vettori testuali esistenti solo perché il processo di serving ora include il supporto a visione o audio.

Per i nuovi record che contengono media servono comunque nuovi vettori. Un indice di solo testo non può recuperare un’immagine, un video o un elemento audio che non è mai stato vettorializzato. Aggiungere il retrieval multimodale è quindi una migrazione incrementale del corpus, anche quando il checkpoint del modello resta invariato.

Usa un cutover blue-green o named vector

Per un sistema live, il pattern di migrazione di Qdrant è il modello più chiaro: crea una nuova collection, scrivi i nuovi record su entrambe, esegui il backfill partendo dai dati sorgente autorevoli, confronta Recall@10/MRR/nDCG@10, sposta un alias e conserva la vecchia collection per il rollback. La guida di Qdrant usa la versione 1.19.0, un esempio da 512 dimensioni e batch da 100 punti; sono valori esemplificativi, non requisiti per EmbeddingGemma 2.

Un’architettura basata su named vector può mantenere rappresentazioni vecchie e nuove nella stessa collection, ma solo se il vector database lo supporta e il flusso di aggiornamento scrive entrambe in modo coerente. La guida di Weaviate alla migrazione del vectorizer raccomanda gli alias delle collection in produzione, perché la collection precedente può essere conservata per un rollback immediato ed eliminata dopo la validazione. L’alternativa — aggiungere un vettore alla collection esistente — può aumentare permanentemente lo storage ed è più adatta al confronto che allo stato finale del sistema.

Qualità multimodale: valida proprio i casi che il modello modifica

Lo spazio condiviso di EmbeddingGemma 2 è utile solo se il comportamento del retrieval è adatto ai tuoi dati. Un benchmark basato esclusivamente sul testo può confermare che la migrazione non ha danneggiato la ricerca testuale, ma non rilevare problemi nelle pagine PDF, nei grafici, nelle didascalie delle immagini, nei frame video, nelle clip audio o nei record interleaved.

Inizia con slice separate e annotate:

1. Query testuale → blocco di testo.
2. Query di codice → blocco di codice.
3. Query testuale → immagine o documento visivo.
4. Query testuale → frame video o segmento audio.
5. Query mista testo più media → documento misto.
6. Query multilingue → documento nelle lingue che utilizzi.

Per la prima baseline multimodale mantieni 768d o 512d. La model card ufficiale assegna 280 token a ogni immagine, 140 token a ogni frame video e 25 token per secondo di audio all’interno di un contesto condiviso da 8.192 token. Gli input misti consumano lo stesso budget: un record con testo, immagini e video lascia quindi meno spazio a ciascun componente rispetto a un input a modalità singola.

La model card riporta inoltre che 128d provoca un calo di qualità maggiore nei task multimodali rispetto a quelli solo testuali. Per questo 128d può essere un candidato da valutare in prima battuta su un grande indice testuale, ma non è la scelta predefinita per un archivio di contenuti misti. Prima di accettare il risparmio di storage, confronta 256d con le query reali sui documenti visivi e sui casi cross-modal.

Confronta una pipeline unificata basata su EmbeddingGemma 2 con l’attuale pipeline separata per testo e immagini, usando query identiche; non dedurre la qualità multimodale dalla sola architettura a spazio condiviso del modello.

Un piano di deployment graduale per un sistema RAG esistente

1. Fai l’inventario del contratto attuale. Registra ID del modello, revisione del checkpoint, prefissi, chunking, dimensioni, metrica, normalizzazione, campi sorgente e tutte le modalità già indicizzate.
2. Crea un set di valutazione rappresentativo. Includi obiettivi di Recall@k, MRR o nDCG e slice separate per testo, codice, documenti visivi, audio, video, lingue e query lunghe.
3. Stabilisci la baseline locale. Passa prima lo stesso corpus in Sentence Transformers. Registra latenza degli embedding, latenza della ricerca, memoria, dimensione dell’indice, errori e distribuzioni dei punteggi.
4. Costruisci un indice candidato versionato. Mantieni ID stabili dei documenti e conserva testo/media sorgente autorevoli fuori dal vector store, così da rendere riproducibile il backfill.
5. Gestisci le scritture durante il backfill. Usa uno snapshot della sorgente con replay delle modifiche, oppure scrivi i nuovi record e quelli aggiornati su entrambe le versioni della rappresentazione.
6. Esegui lo shadowing delle query di produzione. Confronta risultati ordinati, percentuale di risposte vuote, latenza e rilevanza annotata senza modificare le risposte visibili agli utenti.
7. Esegui il cutover in modo atomico. Collega l’encoder delle query EmbeddingGemma 2 e l’indice corrispondente sotto un’unica versione o un alias. Non distribuire mai il nuovo encoder delle query insieme al vecchio indice, nemmeno come stato intermedio.
8. Mantieni disponibile il rollback. Conserva il vecchio indice e il vecchio percorso di query finché il traffico rappresentativo non supera le soglie di accettazione; poi interrompi le doppie scritture e recupera lo storage.

FAQ

EmbeddingGemma 2 può funzionare solo su CPU?

Sì, con un runtime compatibile con la CPU. La model card raccomanda float32 quando bfloat16 non è disponibile, mentre la configurazione solo testo conta 270M di parametri. Il throughput su CPU dipende da runtime, precisione, batching e hardware: misuralo sul tuo corpus invece di riutilizzare numeri ottenuti su GPU.

La scelta del runtime è un compromesso tra correttezza del percorso di riferimento, parità delle funzioni, efficienza del serving e costo della validazione di una nuova versione del retrieval.