Come archiviare e interrogare gli embeddings in MongoDB

L’ascesa degli LLM e della ricerca semantica ha cambiato radicalmente il modo in cui costruiamo sistemi di ricerca, raccomandazione e retrieval. La ricerca tradizionale per parole chiave—che sia tramite SQL LIKE, indici invertiti Lucene o indici full-text—è sempre meno sufficiente quando gli utenti si aspettano una comprensione in linguaggio naturale.

È qui che entrano in gioco gli embeddings e i database vettoriali.

MongoDB si è evoluto rapidamente in questo ambito con Atlas Vector Search, offrendo agli sviluppatori un unico database per documenti + metadati + vettori—tutto sotto un’unica API. In questa guida vedremo:

• Che cos’è MongoDB.
• Cosa sono i query embeddings e perché contano.
• Quando dovresti usare gli embeddings.
• Come archiviare gli embeddings in MongoDB.
• Come generarli e interrogarli con Python.

Questo tutorial è pratico e pronto per essere integrato nella tua pipeline di retrieval-augmented generation (RAG), similarity search o raccomandazione.

Che cos’è MongoDB?

MongoDB è un database NoSQL orientato ai documenti che archivia i dati in documenti BSON flessibili—BSON è una codifica binaria di JavaScript Object Notation (JSON)—una notazione testuale di oggetti ampiamente usata per trasmettere e archiviare dati nelle applicazioni web. A differenza dei database relazionali rigidi, MongoDB rende l’evoluzione dello schema semplice e offre:

• Scalabilità orizzontale (sharding).
• Ricco framework di aggregazione.
• Ricerca full-text.
• Vector search.
• Collezioni time series.
• Flessibilità di schema.

MongoDB Atlas—il servizio cloud completamente gestito—estende tutto questo con:

• Atlas Search (basato su Lucene).
• Atlas Vector Search (ricerca semantica tramite indicizzazione HNSW).
• Scalabilità automatica, backup, sicurezza e monitoraggio.

MongoDB è diventato una scelta solida per i carichi di lavoro AI perché i vettori spesso convivono con i metadati, e MongoDB Atlas riunisce tutto in un unico sistema.

Cosa sono gli embeddings e perché usiamo i query embeddings?

Quando lavori con ricerca o retrieval nelle applicazioni AI, uno dei primi concetti che incontri sono gli embeddings. 

Un embedding è in sostanza una rappresentazione numerica, una lunga lista di valori in virgola mobile, che cattura il significato di un testo (o immagine, audio, ecc.). Invece di guardare le parole esatte, gli embeddings mappano il testo in uno spazio vettoriale in cui idee simili finiscono vicine tra loro. Per esempio, considera tre diverse frasi dell’utente:

• Problema di fatturazione
• Errore di pagamento
• Stipendio non accreditato

Anche se le parole sono diverse, tutte e tre descrivono un problema finanziario. Un buon modello di embedding posiziona questi testi vicino nello spazio vettoriale, permettendoti di recuperarli in base al significato e non alle parole chiave.

Questo diventa particolarmente importante quando l’utente effettua una ricerca. Il testo che digita—«Perché il mio stipendio è in ritardo?»—viene anch’esso convertito in un embedding. Questo nuovo vettore è chiamato query embedding. Confronti poi questo vettore di query con tutti gli embeddings archiviati per trovare i documenti semanticamente simili. Più i vettori sono vicini, più il risultato è rilevante.

MongoDB Atlas rende questo flusso estremamente semplice con Atlas Vector Search. Dopo aver archiviato i tuoi documenti e i relativi embeddings in una collezione MongoDB, Atlas crea un indice vettoriale (basato su HNSW) che può recuperare rapidamente documenti simili su larga scala. Per esempio, se archivi articoli di supporto con i loro embeddings, una query come…

query = "Why isn't my salary showing up this month?"
query_vec = get_embedding(query) # Explained in below examplesOfferto da

…può essere usata direttamente in MongoDB:

results = collection.aggregate([
    {
        "$vectorSearch": {
            "path": "embedding",
            "queryVector": query_vec,
            "index": "vector_index",
            "limit": 3
        }
    }
])
Offerto da

MongoDB restituirà automaticamente i 3 articoli di supporto le cui embeddings sono più vicine alla query—senza che tu debba fare alcun matching per parola chiave o punteggio manuale.

Questa è la forza degli embeddings in MongoDB Atlas: archivi il significato, non solo il testo, e interroghi in base all’intento, non solo alle parole. Questo cambiamento è il motivo per cui gli embeddings sono diventati un elemento fondamentale per la ricerca semantica, i sistemi RAG, gli assistenti AI e le knowledge base intelligenti.

Quando usare i query embeddings

Usa gli embeddings quando vuoi la somiglianza semantica, ad esempio:

Retrieval-augmented generation (RAG)

• Fornisci al tuo LLM contesto accurato dalla tua knowledge base
• Sostituisci la fragile ricerca per parole chiave

Chatbot che richiedono comprensione profonda

• Helpdesk di portale
• Assistenza clienti

Raccomandazione di prodotti

• «articoli simili a questo articolo»

Rilevamento di documenti o duplicati

• Clustering
• Raggruppamento per argomenti

Quando la ricerca per parole chiave fallisce

• Query come «ritardo accredito stipendio» vs. «problema di elaborazione pagamento»

Non usare gli embeddings quando:

• Ti serve una corrispondenza esatta (ID, numeri di fattura).
• Il tuo dataset è minuscolo (la ricerca semplice basta).
• Ti servono filtraggi/confronti numerici (dovrebbero gestirli i metadati).

Come archiviare gli embeddings in MongoDB

La bellezza di MongoDB è che gli embeddings si inseriscono naturalmente nei documenti. Li archivi semplicemente come array di float.

Schema di documento di esempio

Ecco una tipica struttura di documento:

{
  "_id": "uuid-123",
  "text": "This is a sample document about MongoDB vector search.",
  "embedding": [0.123, -0.241, 0.998, ...],
  "tags": ["mongodb", "vector", "ai"],
  "createdAt": "2025-01-01T10:20:00Z"
}
Offerto da

Cose importanti da tenere a mente:

• Ogni embedding in una collezione deve avere la stessa dimensionalità.
• Idealmente gli embeddings dovrebbero essere archiviati come float32 (MongoDB li convertirà internamente in float64).
• Se i tuoi documenti sono lunghi, suddividili in chunk prima di eseguire l’embedding.
• Archivia i metadati separatamente—tag, categoria, URL, timestamp, ecc. Questo rende potente la ricerca ibrida.

Creare un indice vettoriale in MongoDB (passaggio critico)

Prima di archiviare o interrogare gli embeddings, devi creare un indice di ricerca vettoriale in MongoDB Atlas.

In MongoDB Atlas, vai su: Atlas → Database → Collections → Search → Create Search Index

Usa una definizione come:

{
  "fields": [
    {
      "type": "vector",
      "path": "embedding",
      "numDimensions": 1536,
      "similarity": "cosine"
    }
  ]
}
Offerto da

Questo dice a MongoDB:

• Il campo embedding contiene vettori.
• Ogni vettore ha 1536 dimensioni.
• Usa la similarità coseno per il ranking.

Questo indice alimenta tutte le query di vector search.

MongoDB include funzionalità native di vector search con supporto per:

• Similarità coseno.
• Distanza euclidea.
• punteggio dotProduct.

Scegli in base al tuo modello di embedding—ma come sapere cosa scegliere? Vediamolo nel dettaglio.

Similarità coseno

Cosa misura

Misura quanto sono allineati due vettori—ovvero l’angolo tra di essi. Ignora la magnitudine e si concentra solo sulla direzione.

Intuizione

• Se due vettori puntano nella stessa direzione → similarità vicina a 1
• Direzioni opposte → –1
• Ortogonali (non correlate) → 0

Quando usarla

Usa il coseno quando la magnitudine non conta, ma solo il pattern o il concetto espresso.

Usi comuni

• Embeddings testuali/NLP
• Ricerca semantica
• Sistemi di raccomandazione basati sul significato, non sulla scala

Il coseno è la scelta più sicura per la maggior parte dei modelli di embedding.

Distanza euclidea

Cosa misura

Misura la distanza in linea retta tra due vettori nello spazio.

Intuizione

• Distanza piccola → vettori simili
• Distanza grande → vettori lontani

Quando usarla

Usa l’euclidea quando contano valori assoluti e magnitudini, non solo la direzione.

Usi comuni

• Embeddings di immagini
• Misure fisiche/dati da sensori
• Algoritmi di clustering come K-means (che internamente usa l’euclidea)

Se i tuoi dati vivono naturalmente in uno spazio geometrico (es. intensità dei pixel), l’euclidea spesso ha più senso.

Prodotto scalare (dot product)

Cosa misura

Misura una combinazione di similarità e magnitudine. 

Matematicamente: dot(u, v) = |u| × |v| × cos(θ)

Intuizione

• Magnitudine maggiore E allineamento → punteggio più alto
• Sensibile alla lunghezza del vettore
• Non normalizzato automaticamente

Quando usarlo

Usa il dot product quando vuoi che vettori più lunghi abbiano più influenza o quando il modello di embedding è addestrato pensando al prodotto interno.

Usi comuni

• Embeddings di large language model che assumono punteggio da inner product
• Layer di similarità nelle reti neurali
• Modelli di raccomandazione in cui la “forza” delle caratteristiche è significativa

Regola pratica veloce

Generare, archiviare e interrogare embeddings in MongoDB (tutorial Python)

Vediamolo passo passo come se stessimo costruendo un sistema reale.

Installa le dipendenze

pip install pymongo openaiOfferto da

Genera gli embeddings

Usando OpenAI (sostituisci con qualsiasi provider di embedding preferisci):

import os
from openai import OpenAI

os.environ["OPENAI_API_KEY"] = "your_api_key_here"
client = OpenAI()

def get_embedding(text: str):
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=text
    )
    return response.data[0].embeddingOfferto da

Connettiti a MongoDB e inserisci documenti

Usando OpenAI (sostituisci con qualsiasi provider di embedding preferisci):

from pymongo import MongoClient
import uuid

mongo = MongoClient("<MONGODB_ATLAS_URI>")
db = mongo["vector_db"]
collection = db["documents"]

text = "This is a sample document about MongoDB vector search."
embedding = get_embedding(text)

document = {
    "_id": str(uuid.uuid4()),
    "text": text,
    "embedding": embedding,
    "tags": ["mongodb", "search"],
}

collection.insert_one(document)
print("Document inserted successfully!")Offerto da

A questo punto, i tuoi dati sono pronti per la ricerca semantica.

Interrogare gli embeddings in MongoDB

Ora arriva la parte divertente: recuperare documenti simili usando una query vettoriale. MongoDB usa $vectorSearch in una pipeline di aggregazione.

Genera il vettore di query

from pymongo import MongoClient
query = "How does MongoDB handle semantic search?"
query_vec = get_embedding(query)Offerto da

Esegui la vector search (query embeddings)

results = collection.aggregate([
    {
        "$vectorSearch": {
            "index": "vector_index",
            "path": "embedding",
            "queryVector": query_vec,
            "numCandidates": 100,
            "limit": 5,
            "similarity": "cosine"
        }
    },
    {
        "$project": {
            "text": 1,
            "score": {"$meta": "vectorSearchScore"}
        }
    }
])

for r in results:
    print(r)Offerto da

Questo restituisce i cinque documenti più simili semanticamente.

È potente per le pipeline RAG in cui vuoi la ricerca semantica.

Spiegazione passo passo della query sopra

$vectorSearch → Trova i documenti il cui campo embedding è più vicino a queryVector usando la metrica di similarità specificata

numCandidates → Quanti potenziali match il motore dovrebbe considerare prima di selezionare i risultati top

limit → Numero di risultati finali simili da restituire

$project → Restituisce il testo originale più un campo speciale chiamato score

Cos’è il campo score?

MongoDB Atlas Vector Search restituisce un campo di metadati speciale, "score": {"$meta": "vectorSearchScore"}, che ti indica quanto è simile un vettore archiviato al tuo vettore di query.

Il significato dello score dipende dalla metrica di similarità che scegli, come spiegato di seguito:

Best practice

• Suddividi i documenti lunghi (300–500 token ciascuno): Rilevanza migliore + evita di fare embedding di blocchi lunghi
• Archivia i metadati separatamente: Aiuta nel filtraggio e nel ranking
• Genera gli embeddings in batch: Migliora la capacità e riduce i costi del modello
• Usa embeddings float32 nel tuo modello: MongoDB internamente usa float64 ma accetta array float32
• Indicizza solo il campo vettoriale: Campi extra nell’indice aumentano memoria e latenza

Errori comuni da evitare

Considerazioni finali

Gli embeddings e la ricerca semantica sono ormai fondamentali nei prodotti AI moderni. Che tu stia costruendo un chatbot, una pipeline RAG, un motore di raccomandazione o un livello di ricerca intelligente, ti serve un modo affidabile per archiviare i vettori e interrogarli in modo efficiente.

MongoDB ti offre una piattaforma unificata in cui:

• Vive il tuo testo.
• Vivono i tuoi metadati.
• Vivono i tuoi embeddings.
• Gira la tua vector search.
• Tutto scala insieme.

Questo evita la complessità di gestire database separati e ti permette di concentrarti sullo sviluppo delle funzionalità di prodotto, non dell’infrastruttura.