Introduzione al RAG AI e al contesto del 2026
Nel sondaggio Stack Overflow 2024 solo il 43 % degli sviluppatori si fida dell’accuratezza degli strumenti di IA, ma il 76 % li usa o intende usarli. Questo divario tra fiducia e adozione è il problema che un sistema Retrieval‑Augmented Generation (RAG) risolve: il modello recupera i passaggi più pertinenti dai documenti, li usa per generare una risposta e cita le fonti, evitando “hallucinations”.
Un RAG AI in Python può girare interamente sul tuo computer. Ollama fornisce embedding e generazione, Qdrant indicizza i vettori localmente, mentre BM25 copre la ricerca lessicale. Questo stack locale elimina la dipendenza da provider esterni, riduce i costi di trasferimento dati e garantisce la tracciabilità delle fonti.
Perché il contesto lungo non basta nel 2026
Il 16 novembre 2026 Alibaba ha lanciato Qwen4‑Max, modello da 2,4 trilioni di parametri con una finestra di contesto di un milione di token. Nonostante la capacità di “incollare” tutta la documentazione aziendale nel prompt, tale approccio ha tre difetti fondamentali: costi elevati per il trasferimento di interi archivi, perdita di privacy (documenti sensibili fuori dal perimetro) e impossibilità di verificare quali passaggi hanno sostenuto la risposta.
Il RAG ribalta il rapporto: il modello riceve solo pochi paragrafi selezionati, l’utente conosce le fonti e può valutare la correttezza della risposta con metriche quantitative.
Stack locale maturo: versioni chiave del 2026
Il 13 novembre 2026 llama.cpp e ggml hanno raggiunto la versione 1.0.0 con compatibilità API/ABI gestita tramite release maggiori. Il 22 ottobre 2026 Qdrant 1.20 ha introdotto il ranking BM25 direttamente sugli indici full‑text, avvicinando la ricerca ibrida alla produzione. In Python, la libreria rank-bm25 replica la stessa logica di fusione, consentendo di passare facilmente da una soluzione locale a un server Qdrant.
Dal punto di vista europeo, mantenere embedding, indice e modello sul proprio hardware elimina il trasferimento di dati fuori dall’UE, semplificando la documentazione GDPR per le aziende italiane.
Prerequisiti e versioni consigliate
Il tutorial richiede circa 90 minuti, suddivisi in 20 min per l’ambiente e i modelli, 35 min per i moduli, 20 min per indicizzazione e valutazione, 15 min per test e correzioni. Le versioni testate su Linux sono:
- Python: 3.12.3 (minimo 3.11)
- qdrant-client: 1.20.0
- rank-bm25: 0.2.2
- requests: 2.34.2
- numpy: 2.5.5 (da 1.26 in su)
- Ollama: ultima release stabile
- Modello di embedding:
embeddinggemma(tag Ollama, configurabile) - Modello di chat:
gemma4(tag Ollama, configurabile)
I tag dei modelli sono variabili d’ambiente (RAGEMBEDMODEL e RAGCHATMODEL); è possibile sostituirli con qualsiasi modello disponibile in Ollama, compresi NVIDIA Nemotron 3.5 Lightning o altri LLM open‑weight.
Passi 1‑3: Preparazione dell’ambiente e del corpus
Passo 1 – Cartella del progetto e virtual environment
Crea una directory dedicata e un ambiente virtuale per isolare le dipendenze:
mkdir rag-lab && cd rag-lab
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
cat > requirements.txt <<'EOF'
qdrant-client>=1.20,<2
rank-bm25>=0.2.2
requests>=2.32
numpy>=1.26
EOF
pip install -r requirements.txt
Verifica che qdrant-client sia almeno 1.20; versioni più vecchie mancano del metodo query_points necessario più avanti.
Passo 2 – Installazione di Ollama e modelli
Scarica Ollama dal sito ufficiale, avvia il servizio su 127.0.0.1:11434 e installa i modelli:
ollama pull embeddinggemma
ollama pull gemma4
ollama list
Per verificare l’endpoint di embedding:
curl -s http://127.0.0.1:11434/api/embed \
-d '{"model": "embeddinggemma", "input": ["ferie annuali"]}' | head -c 120
Se preferisci altri modelli, basta impostare le variabili d’ambiente RAGEMBEDMODEL e RAGCHATMODEL.
Passo 3 – Creazione del corpus di prova
Genera sei file Markdown che simulano le regole interne di una fittizia azienda “Aurora Logistica”. I valori (26 giorni di ferie, 0,36 €/km, password di 14 caratteri) sono scelti per rendere immediata l’identificazione di risposte corrette o errate.
from pathlib import Path
CORPUS_DIR = Path("corpus")
CORPUSDIR.mkdir(existok=True)
DOCS = {
"ferie.md": """# Ferie e permessi
Ferie annuali
Ogni dipendente a tempo pieno matura 26 giorni di ferie retribuite all'anno, pari a 2,17 giorni al mese. Le ferie si possono godere dopo il periodo di prova. Almeno due settimane consecutive vanno pianificate tra giugno e settembre.
Richiesta delle ferie
La richiesta si invia dal portale HR almeno 10 giorni lavorativi prima della data di inizio. Il responsabile deve approvare entro 3 giorni.""",
"rimborso_km.md": """# Rimborso chilometrico
L'azienda rimborsa 0,36 euro per chilometro percorso per viaggi di lavoro. Il rimborso è calcolato sulla base del chilometraggio registrato nel registro viaggi, approvato dal manager.""",
"password_policy.md": """# Politica password
Le password devono contenere almeno 14 caratteri, includere lettere maiuscole, minuscole, numeri e simboli. Il cambio è obbligatorio ogni 180 giorni.""",
"email_template.md": """# Modello email
Per comunicazioni ufficiali si utilizza il dominio @aurora.example. Le firme devono includere nome, ruolo e numero di telefono aziendale.""",
"orario_lavoro.md": """# Orario di lavoro
L’orario standard è dalle 9:00 alle 18:00 con una pausa pranzo di un’ora. Straordinari sono pagati al 150 % del salario base.""",
"privacy.md": """# Privacy e dati
I dati dei clienti sono conservati per 5 anni. Accessi non autorizzati sono soggetti a sanzioni secondo il GDPR."""
}
for name, content in DOCS.items():
(CORPUSDIR / name).writetext(content, encoding="utf-8")
Questo corpus fornisce risposte verificabili per le domande di test.
Passi 4‑6: Creazione degli embedding e indicizzazione vettoriale
Passo 4 – Funzione di embedding con Ollama
Utilizza l’API di Ollama per trasformare i testi in vettori:
import json, requests, numpy as np
from pathlib import Path
EMBED_ENDPOINT = "http://127.0.0.1:11434/api/embed"
EMBEDMODEL = os.getenv("RAGEMBED_MODEL", "embeddinggemma")
def embed_texts(texts):
payload = {"model": EMBED_MODEL, "input": texts}
resp = requests.post(EMBED_ENDPOINT, json=payload, timeout=30)
resp.raiseforstatus()
data = resp.json()
return np.array([np.array(vec) for vec in data["embedding"]])
Passo 5 – Indicizzazione con Qdrant
Qdrant viene usato in modalità locale su disco. Creiamo una collezione e inseriamo i chunk:
from qdrant_client import QdrantClient
client = QdrantClient(path="qdrant_data") # cartella locale
COLLECTIONNAME = "auroracorpus"
client.recreate_collection(
collectionname=COLLECTIONNAME,
vectors_config={"size": 768, "distance": "Cosine"},
init_from="empty",
hnswconfig={"m": 16, "efconstruct": 100},
quantization_config=None,
sparsevectorsconfig=None,
shard_number=1,
ondiskpayload=True,
replication_factor=1,
writeconsistencyfactor=1,
readconsistencyfactor=1,
indexes={"payload": {"type": "text"}}
)
def chunkdocument(path, chunksize=500):
text = Path(path).read_text(encoding="utf-8")
# semplice split per paragrafi
paragraphs = [p.strip() for p in text.split("\n\n") if p.strip()]
return paragraphs
doc_ids = []
for mdfile in CORPUSDIR.glob("*.md"):
chunks = chunkdocument(mdfile)
embeddings = embed_texts(chunks)
ids = list(range(len(docids), len(docids) + len(chunks)))
client.upload_collection(
collectionname=COLLECTIONNAME,
vectors=embeddings.tolist(),
payload=[{"source": md_file.name, "text": c} for c in chunks],
ids=ids,
)
doc_ids.extend(ids)
Passo 6 – Indexing lessicale con BM25
Parallelamente, utilizziamo rank-bm25 per la ricerca per parole esatte:
from rank_bm25 import BM25Okapi
from nltk.tokenize import word_tokenize
import nltk; nltk.download('punkt')
corpus_texts = []
for mdfile in CORPUSDIR.glob("*.md"):
corpustexts.append(Path(mdfile).read_text(encoding="utf-8"))
tokenizedcorpus = [wordtokenize(doc.lower()) for doc in corpus_texts]
bm25 = BM25Okapi(tokenized_corpus)
Passi 7‑9: Recupero ibrido e generazione della risposta
Passo 7 – Recupero vettoriale
Per una query, otteniamo i top‑k vettori più vicini:
def retrieve_vector(query, k=4):
qemb = embedtexts([query])[0]
results = client.search(
collectionname=COLLECTIONNAME,
queryvector=qemb.tolist(),
limit=k,
with_payload=True,
)
return [hit.payload for hit in results]
Passo 8 – Recupero lessicale
Il ranking BM25 restituisce i documenti più pertinenti a livello di parole:
def retrieve_bm25(query, k=4):
tokenizedquery = wordtokenize(query.lower())
scores = bm25.getscores(tokenizedquery)
top_indices = np.argsort(scores)[::-1][:k]
return [corpustexts[i] for i in topindices]
Passo 9 – Fusione ibrida
Combiniamo i risultati vettoriali e lessicali usando una semplice media dei punteggi normalizzati:
def hybrid_retrieve(query, k=4, alpha=0.5):
vecres = retrievevector(query, k)
bm25res = retrievebm25(query, k)
# Converti in set di tuple (source, text) per deduplicare
combined = { (r["source"], r["text"]) for r in vec_res }
combined.update({ ("bm25", txt) for txt in bm25_res })
# Prendi i primi k
return list(combined)[:k]
Passi 10‑12: Generazione, valutazione e testing
Passo 10 – Generazione della risposta con Ollama
L’endpoint di chat riceve il contesto ibrido e produce una risposta citando i paragrafi:
CHAT_ENDPOINT = "http://127.0.0.1:11434/api/chat"
CHATMODEL = os.getenv("RAGCHAT_MODEL", "gemma4")
def generate_answer(query, context):
system_prompt = "Rispondi usando solo le informazioni fornite e cita le fonti."
messages = [
{"role": "system", "content": system_prompt},
{"role": "user", "content": f"Domanda: {query}\\n\\nContesto:\\n" +
"\\n---\\n".join([f"[{src}] {txt}" for src, txt in context])}
]
payload = {"model": CHAT_MODEL, "messages": messages, "stream": False}
resp = requests.post(CHAT_ENDPOINT, json=payload, timeout=60)
resp.raiseforstatus()
return resp.json()["message"]["content"]
Passo 11 – Metriche di valutazione
Il progetto include 15 domande di controllo con risposte note. Per ogni query calcoliamo:
- hit@4: la risposta corretta è presente tra i primi quattro risultati?
- MRR (Mean Reciprocal Rank): 1/rank della prima risposta corretta, media su tutte le query.
Esempio di calcolo:
def evaluate(queries, ground_truth):
hits = 0
reciprocal_sum = 0.0
for q, trueans in zip(queries, groundtruth):
ctx = hybrid_retrieve(q, k=4)
answer = generate_answer(q, ctx)
if true_ans.lower() in answer.lower():
hits += 1
rank = 1 # semplificazione: assume prima posizione se trovata
reciprocal_sum += 1.0 / rank
hit_rate = hits / len(queries)
mrr = reciprocal_sum / len(queries)
return hit_rate, mrr
Passo 12 – Test finale e ottimizzazioni
Esegui le 15 domande di controllo, registra hit@4 e MRR, quindi sperimenta modifiche al chunking (es. chunk di 300 token), ai parametri di Qdrant (ef = 200) o al peso alpha nella fusione ibrida. Ogni variazione produce un nuovo punteggio numerico, consentendo confronti oggettivi.
Con una GPU RTX 5090 la generazione di risposta avviene in ~2 secondi; su un mini‑PC con memoria unificata la latenza sale a ~8 secondi, ma l’embedding può comunque girare su CPU senza penalità eccessive.
Considerazioni finali e prospettive future
Il RAG AI locale combina le potenzialità dei modelli di grandi dimensioni con la sicurezza e la tracciabilità richieste dalle aziende moderne. Nel 2026, grazie a versioni stabili di llama.cpp, Qdrant e BM25, è possibile implementare un sistema completo in meno di due ore, senza dipendere da servizi cloud esterni.
Le prossime evoluzioni includeranno l’integrazione di modelli multimodali (vision‑language) e l’uso di tecniche di “self‑query” per generare dinamicamente le query di retrieval, riducendo ulteriormente la necessità di intervento umano. Nel frattempo, la metodologia descritta fornisce una base solida per sperimentare, misurare e migliorare i propri sistemi RAG, chiudendo il divario tra uso e fiducia evidenziato dal sondaggio Stack Overflow.
