Qdrant: il database vettoriale di un RAG locale

#A cosa serve un database vettoriale

Un modello di embedding converte un testo in una lista di numeri — un vettore — in modo che due testi dal significato simile producano due vettori vicini. Trovare i passaggi pertinenti a una domanda equivale quindi a cercare i vettori più vicini a quello della domanda. Su mille passaggi, basta un semplice calcolo sull'intero insieme. Su un milione, serve una struttura di indicizzazione, ed è questo il compito di un database vettoriale: costruire e mantenere questa struttura, rispondere in pochi millisecondi anziché confrontare i vettori uno per uno e continuare a fornire risultati corretti mentre il corpus continua a ricevere nuovi documenti.

Questa fase condiziona tutto il resto: un modello eccellente che riceve i passaggi sbagliati risponde male, e nessuna istruzione nel prompt può compensare un recupero delle informazioni inefficace. Per questo motivo, la scelta del database vettoriale, a lungo considerata un dettaglio infrastrutturale intercambiabile, merita la stessa cura riservata alla scelta del modello linguistico stesso.

#Cosa offre Qdrant

Il progetto si descrive come un motore di ricerca e un database vettoriale «ad alte prestazioni, su larga scala», progettato per un filtraggio esteso, il che lo distingue dalle librerie che si limitano a cercare il vicino più prossimo senza condizioni. È scritto in Rust, caratteristica che i suoi autori indicano come il motivo della sua velocità e affidabilità sotto carico elevato. Quanto alla robustezza operativa, il progetto documenta anche la registrazione anticipata delle scritture (write-ahead logging), che garantisce la persistenza dei dati con conferma dell'aggiornamento, anche in caso di interruzione dell'alimentazione, oltre a metriche, telemetria e log di audit per monitorare un deployment in produzione ed eseguirne il debug.

Un server autonomo

Un container, un'API HTTP e gRPC, client ufficiali in Python, Go, Rust, JavaScript/TypeScript, .NET e Java. Funziona indipendentemente dalla tua applicazione, che può riavviarsi senza mai perdere l'indice costruito.

Filtraggio per payload

Ogni vettore contiene metadati — autore, data, servizio, tipo di documento — sui quali si applicano filtri durante la ricerca con le clausole should, must e must_not, non dopo. È la differenza tra una ricerca utilizzabile in azienda e una dimostrazione.

La quantizzazione dei vettori

Comprimere i vettori per ridurre notevolmente l'occupazione di memoria (di un fattore 4× con la quantizzazione scalare, fino a 32× con quella binaria), al prezzo di una perdita di precisione controllata e compensabile.

Vettori sparsi e multi-vettori

Oltre ai classici vettori densi, Qdrant supporta i vettori sparsi per la ricerca a testo integrale e gli oggetti con più embedding, utili per modelli a interazione tardiva come ColBERT.

La ricerca ibrida

Combinare più vettori in una stessa query per sfruttare sia la comprensione semantica sia la precisione della ricerca per parole chiave, ottenendo un risultato combinato tramite strategie configurabili come la fusione dei ranghi reciproci (RRF) o la fusione dei punteggi basata sulla distribuzione (DBSF).

Snapshot e ripristino

Salvare una collezione e ripristinarla altrove, un aspetto importante quando una nuova indicizzazione costerebbe ore di utilizzo della GPU.

Il deployment distribuito

Distribuire una collezione su più nodi tramite sharding e replica, con ridimensionamento senza interruzioni del servizio — utile al di là di un utilizzo strettamente locale, ma da tenere presente se il progetto cresce, per non dover ricostruire tutto da zero il giorno in cui una sola macchina non basta più.

#Avviare localmente

La strada più breve è il container ufficiale, con un volume che conservi i dati dopo il riavvio. Un’interfaccia web integrata, descritta dal progetto come «un modo visivo per interagire con i tuoi dati e monitorare lo stato del tuo deployment», permette poi di esplorare le collezioni, gestire i dati e interrogare l’API REST senza scrivere una riga di codice — è il miglior strumento di diagnosi quando una risposta è sbagliata: si guarda ciò che è stato effettivamente recuperato, anziché cercare di indovinarlo rileggendo il codice di recupero.

docker run -p 6333:6333 -p 6334:6334 \
  -v "$(pwd)/qdrant_storage:/qdrant/storage" \
  qdrant/qdrant

Il client Python può funzionare anche senza alcun server: QdrantClient(":memory:") per un test usa e getta, oppure QdrantClient(path="chemin/vers/db") per un'archiviazione locale persistente. È prezioso per un prototipo o per test automatizzati: lo stesso codice può poi passare al server modificando una sola riga di connessione. Dal 2026 il progetto documenta una seconda modalità di integrazione, Qdrant Edge: una versione alleggerita progettata per dispositivi con risorse limitate, che viene eseguita direttamente nel processo dell'applicazione anziché in un'architettura client-server, con la possibilità di sincronizzarsi con un server Qdrant completo.

#Il minimo in Python

1. 01
   Connettersi

   from qdrant_client import QdrantClient, poi client = QdrantClient(url="http://localhost:6333") per collegarsi al container avviato sopra.
2. 02
   Creare una collezione

   client.create_collection(collection_name="docs", vectors_config=VectorParams(size=1024, distance=Distance.COSINE)) — la dimensione deve corrispondere esattamente alla dimensione del tuo modello di embedding.
3. 03
   Inserire punti

   client.upsert(collection_name="docs", points=[PointStruct(id=1, vector=[...], payload={"service": "support"})]) associa a ogni vettore un identificativo e metadati filtrabili.
4. 04
   Interrogare

   client.query_points(collection_name="docs", query=vecteur_question, limit=5).points restituisce i cinque passaggi più vicini, con il loro punteggio e il loro payload.

#Il filtraggio per metadati, la funzione che ci dispiace di aver trascurato

In una situazione reale, una domanda non riguarda quasi mai l'intero corpus. Si cercano documenti di un servizio, successivi a una certa data, di un determinato tipo o accessibili all'utente che pone la domanda. Qdrant applica queste condizioni durante la ricerca vettoriale, con una ricca gamma di filtri — corrispondenza di parole chiave, ricerca a testo completo, intervalli numerici, geolocalizzazione — combinati tramite le clausole logiche should, must e must_not. Questo permette di ottenere sempre il giusto numero di risultati pertinenti, mentre un filtraggio effettuato a posteriori potrebbe non lasciarne nessuno.

Il controllo degli accessi merita una menzione a parte: se più persone interrogano lo stesso indice, il filtro sui permessi impedisce al modello di citare a una persona un documento che quella persona non è autorizzata a leggere. Nessuna istruzione nel prompt sostituisce questo filtro, e implementarlo a livello di database anziché nel codice applicativo evita che un nuovo punto di accesso alla stessa collezione dimentichi di riapplicarlo.

#Far stare in memoria: la quantizzazione dei vettori

La pratica documentata consiste nel cercare nei vettori compressi, poi nel riordinare (rescoring) i migliori candidati con i vettori originali — Qdrant offre un parametro di sovracampionamento (oversampling) per regolare questo compromesso: impostandolo a 2,4 con un limite di 100 risultati, vengono preselezionati 240 candidati sull'indice quantizzato prima del riordinamento finale. Si mantiene gran parte della precisione riducendo la memoria a un quarto o meno, il che su una macchina che ospita anche un modello non è un lusso. La documentazione ufficiale dichiara inoltre un'accelerazione fino a 40 volte con la quantizzazione binaria rispetto ai vettori originali, un dato da verificare sul proprio insieme di dati anziché darlo per scontato. Il progetto riassume tutte queste opzioni di compressione, combinate con l'archiviazione su disco, annunciando una riduzione dell'uso della memoria fino al 97% — un ordine di grandezza che spiega perché la quantizzazione viene presentata come una funzionalità centrale anziché come un'impostazione marginale.

#Qdrant o un'altra base vettoriale

La domanda da porsi non è «qual è il miglior database vettoriale», ma «che cosa richiede oggi il mio progetto». Uno script di test non ha bisogno di altro che di una libreria in memoria. Un'applicazione aziendale che interroga già PostgreSQL trae vantaggio dall'aggiungervi un'estensione vettoriale anziché un servizio in più. Qdrant diventa la scelta giusta proprio quando più esigenze tra queste si presentano contemporaneamente: un servizio condiviso da più applicazioni, un filtraggio preciso dei metadati, un corpus che continua a crescere e il desiderio di non implementare da sé la persistenza o gli snapshot. Rivedere regolarmente questa scelta, anziché fissarla al primo prototipo, evita sia di complicare eccessivamente l'architettura di un progetto modesto sia di sottodimensionare un progetto che nel frattempo è cresciuto.

• Un RAG locale completo, dall'ingestione alla risposta
• Scegliere un modello di embedding per il francese
• Aggiungere un reranker per migliorare la rilevanza
• pgvector: quando PostgreSQL basta
• Il kit RAG locale QuelLLM
• Fonte: repository ufficiale Qdrant su GitHub
• Fonte: documentazione ufficiale sulla quantizzazione
• Fonte: avvio rapido Qdrant in Python

#FAQ