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.