LlamaIndex e Qdrant: guida passo‑passo per una pipeline RAG nel 2026

Nel 2026 chi vuole costruire una propria applicazione di Retrieval‑Augmented Generation (RAG) incontra quasi inevitabilmente due nomi: LlamaIndex e Qdrant. Il primo è il framework che trasforma documenti grezzi in una forma sfruttabile dai grandi modelli di linguaggio, il secondo è la vector‑database che conserva questi dati e li rende ricercabili in millisecondi.

Panoramica su LlamaIndex e Qdrant

LlamaIndex, precedentemente noto come GPT Index, è un progetto open‑source ospitato su GitHub (run-llama/llama_index) con oltre 52.400 stelle e 8.300 fork al 30 settembre 2026. La versione più recente, 0.14.25, introduce correzioni di sicurezza e il supporto al modello Claude Sonnet 5.5 di Anthropic, consentendo l’uso di LLM diversi da OpenAI.

Il nucleo di LlamaIndex è costituito da tre componenti fondamentali:

• Reader: importa PDF, pagine web, tabelle, ecc.
• Index: organizza gli embedding vettoriali.
• Query Engine: esegue le interrogazioni contro l’indice.

Di per sé LlamaIndex non persiste i vettori; senza una base dati esterna gli embedding vivono solo in RAM e si perdono al termine del processo. Qui entra in gioco Qdrant, una vector‑database open‑source scritta in Rust, disponibile sia come container Docker che come servizio gestito.

Perché scegliere Qdrant

Qdrant 1.19.1, rilasciato il 4 settembre 2026, espone le porte 6333 (HTTP) e 6334 (gRPC) e offre tre vantaggi chiave rispetto a un indice in memoria:

• Persistenza su disco, quindi i vettori sopravvivono a riavvii.
• Filtri di metadati eseguiti direttamente nel motore, riducendo il carico sull’applicazione.
• Scalabilità mediante sharding e replica, gestibile anche per milioni di vettori.

La scelta della metrica di distanza è cruciale: cosine similarity è la più comune per embeddings testuali, mentre dot‑product o euclidean possono risultare più adatti a modelli specifici.

12 passi per costruire la tua pipeline RAG

Passo 1 – Preparare l’ambiente Python

Assicurati di avere Python 3.10 o superiore. Creiamo un virtual environment e installiamo le dipendenze:

python -m venv venv
source venv/bin/activate
pip install llama-index==0.14.25 qdrant-client==1.19.1

Passo 2 – Avviare Qdrant con Docker

Il modo più rapido è utilizzare Docker. Esegui:

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

Il volume qdrant_storage garantisce la persistenza dei dati.

Passo 3 – Creare la collection in Qdrant

Nel tuo script Python, usa il client per definire una collection con la metrica desiderata:

from qdrant_client import QdrantClient

client = QdrantClient(host="localhost", port=6333)
client.recreate_collection(
collection_name="docs",
vector_size=768,               # dimensione degli embedding
distance="Cosine"
)

Passo 4 – Configurare il Reader

LlamaIndex offre reader per diversi formati. Per PDF:

from llama_index import SimpleDirectoryReader

documents = SimpleDirectoryReader(inputdir="docs/").loaddata()

Puoi sostituire SimpleDirectoryReader con i lettori di LlamaHub (Notion, Slack, Google Drive, ecc.) con una sola riga.

Passo 5 – Generare gli embedding

Utilizza il modello LLM desiderato. Qui usiamo Claude Sonnet 5.5 tramite il wrapper OpenAI‑compatible:

from llama_index.embeddings import LangchainEmbedding
from langchain.embeddings import OpenAIEmbeddings

embed_model = LangchainEmbedding(OpenAIEmbeddings(model="claude-sonnet-5.5"))
embeddings = [embedmodel.embeddocument(doc.text) for doc in documents]

Passo 6 – Inserire i vettori in Qdrant

Associa a ciascun documento un ID, i vettori e i metadati (es. titolo, data, tipo):

points = [
{
"id": idx,
"vector": vec,
"payload": {
"title": doc.metadata.get("title", ""),
"source": doc.metadata.get("source", ""),
"category": doc.metadata.get("category", "generic")
}
}
for idx, (doc, vec) in enumerate(zip(documents, embeddings))
]

client.upsert(collection_name="docs", points=points)

Passo 7 – Creare l’indice LlamaIndex collegato a Qdrant

LlamaIndex dispone di un wrapper QdrantVectorStore:

from llamaindex.vectorstores import QdrantVectorStore
from llama_index import VectorStoreIndex

vector_store = QdrantVectorStore(
client=client,
collection_name="docs"
)

index = VectorStoreIndex.fromdocuments(documents, vectorstore=vector_store)

Passo 8 – Configurare il Query Engine

Il query engine gestisce le richieste dell’utente. Impostiamo un retriever basato su similarity search e un semplice prompt:

from llamaindex.queryengine import RetrieverQueryEngine
from llama_index.retrievers import VectorIndexRetriever

retriever = VectorIndexRetriever(index=index, similaritytopk=5)
query_engine = RetrieverQueryEngine(retriever=retriever)

Passo 9 – Aggiungere filtri di metadati

Per scenari come la ricerca di clausole contrattuali, filtriamo per category o date:

from llamaindex.queryengine import MetadataFilters

filters = MetadataFilters(filters=[
{"field": "category", "operator": "=", "value": "contract"},
{"field": "date", "operator": ">", "value": "2023-01-01"}
])

retriever = VectorIndexRetriever(index=index, similaritytopk=5, filters=filters)
query_engine = RetrieverQueryEngine(retriever=retriever)

Passo 10 – Testare la pipeline

Esegui una domanda di prova:

response = query_engine.query("Quali sono le clausole di risoluzione del contratto X?")
print(response)

Il risultato includerà il testo estratto e i metadati di origine, consentendo la verifica nel documento originale.

Passo 11 – Persistenza e backup

Qdrant salva automaticamente i dati su disco. Per una copia di sicurezza, basta copiare la cartella qdrant_storage su un volume di backup o su un bucket S3.

Passo 12 – Deploy della chat‑engine

Wrap la query engine in una semplice API Flask o FastAPI:

from fastapi import FastAPI, Request
app = FastAPI()

@app.post("/chat")
async def chat(request: Request):
data = await request.json()
question = data.get("question")
answer = query_engine.query(question)
return {"answer": str(answer)}

Avvia il server e collega un’interfaccia frontend (React, Vue o Streamlit) per fornire una chat in linguaggio naturale agli utenti finali.

Casi d’uso concreti

La combinazione LlamaIndex + Qdrant si adatta a molteplici settori:

• Supporto tecnico: centinaia di manuali PDF diventano ricercabili mediante domande naturali.
• Studi legali: filtri per tipo di contratto, data o controparte consentono di individuare rapidamente clausole specifiche.
• Team di sviluppo: trasformano wiki interne e documentazione di architettura in assistenti conversazionali.
• E‑commerce: confrontano descrizioni di prodotto, recensioni e schede tecniche per rispondere a richieste come “Quale frigo è più adatto a un monolocale?”.

Vantaggi rispetto a soluzioni cloud‑only

Utilizzare Qdrant in locale elimina dipendenze da servizi esterni, riduce i costi di trasferimento dati e garantisce la conformità a normative sulla privacy (GDPR, HIPAA). Inoltre, la licenza open‑source permette di personalizzare il motore di ricerca secondo le esigenze specifiche dell’organizzazione.

Considerazioni finali e prossimi passi

Questa guida fornisce una base solida per costruire una pipeline RAG robusta nel 2026. Per andare oltre:

• Integrare LlamaHub per leggere dati da fonti dinamiche (Notion, Slack, API REST).
• Sperimentare agenti multi‑step di LlamaIndex per combinare ricerca, calcolo e azioni esterne.
• Valutare l’uso di sharding avanzato di Qdrant su cluster Kubernetes per gestire decine di milioni di vettori.
• Monitorare le release di LlamaIndex (es. 0.15.x) e Qdrant (es. 1.20) per sfruttare ottimizzazioni di filtro e nuove metriche di distanza.

Seguendo questi dodici passi, avrai una pipeline pronta per la produzione, indipendente dal cloud, e capace di scalare con le esigenze della tua azienda.