Architettura RAG in produzione: ricerca ibrida, reranking e test

La retrieval-augmented generation (RAG) è uno schema in cui, quando arriva una domanda, si recuperano i passaggi giusti dai propri documenti e li si passa a un modello linguistico: così la risposta poggia su testi che controlli, non su quello che il modello ricorda dall'addestramento. Il nome gliel'hanno dato Lewis e colleghi nel 2020. Alla fine di questa guida avrai un'architettura RAG da produzione in sei passi: chunk che portano con sé il proprio contesto, due indici sugli stessi chunk, un recupero ibrido unito per posizione, un reranker, un prompt che cita le fonti e un set di domande di prova che ti avverte quando qualcosa peggiora.
La demo è la parte facile. Un database vettoriale, una chiamata per gli embedding e un prompt rispondono bene alle prime dieci domande. In produzione il recupero sbaglia in silenzio, perché il modello scrive una risposta scorrevole con qualunque cosa riceva. Anthropic ha misurato la versione di base, embedding su chunk grezzi, su codice, narrativa, articoli scientifici e documenti finanziari: nel 5,7% delle domande il passaggio con la risposta non era tra i primi 20 risultati. Vuol dire più di una domanda su venti con una risposta presa dalla pagina sbagliata, scritta con lo stesso tono sicuro delle altre.
Cosa serve prima di cominciare
Prima di tutto, verifica che il recupero ti serva davvero. Secondo Anthropic, una base di conoscenza sotto i 200.000 token, circa 500 pagine, entra per intero nel prompt, e il prompt caching contiene il costo delle richieste ripetute. La RAG vale la sua complessità quando i documenti sono di più, cambiano ogni giorno o includono file che non tutti gli utenti possono vedere. Il lato del prompt lo trattiamo nella guida al context engineering.
Se sei oltre quella soglia, prepara:
- 50 domande vere, ognuna abbinata al passaggio che le risponde. Prendile dai ticket di assistenza, dalle call commerciali o dai log di ricerca, mai dai documenti stessi.
- Un archivio che gestisca vettori e parole chiave: Postgres con pgvector e la ricerca full-text, oppure un database vettoriale con un indice per parole chiave.
- Un modello di embedding e un reranker, scelti insieme, perché sono i due pezzi che cambierai più spesso.
- Le regole di accesso ai documenti: quale utente o cliente può leggere quale file, salvate come dati e non nella testa di qualcuno.
Passo 1: dividi per struttura e dai a ogni chunk il suo contesto
Dividi i documenti dove li ha divisi chi li ha scritti: titoli, sezioni, paragrafi. Una tabella, un blocco di codice o una procedura numerata restano in un solo chunk, perché mezza tabella non risponde a niente. Qualche centinaio di token per chunk è un buon punto di partenza; la stima dei costi di Anthropic ne ipotizza 800.
Staccato dal documento, un chunk perde il suo argomento. La frase «Il fatturato è cresciuto del 3% rispetto al trimestre precedente» si recupera male, perché non dice di quale azienda né di quale trimestre. Il contextual retrieval lo risolve prima dell'indicizzazione. Un modello legge tutto il documento accanto a ciascun chunk e scrive un prefisso di 50-100 token che lo colloca («Questo chunk viene dal bilancio di ACME del secondo trimestre 2023; il trimestre precedente il fatturato era...»). Il prefisso si aggiunge al chunk prima di calcolarne l'embedding e prima che entri nell'indice per parole chiave. Con il prompt caching il documento si legge una volta sola, non una volta per chunk, e Anthropic ha stimato il costo una tantum in 1,02 dollari per milione di token di documento.
Salva ogni chunk con i suoi metadati: id del documento, titolo, percorso della sezione, data dell'ultimo aggiornamento e lista di accesso. Tutti i passi successivi li usano.
Passo 2: indicizza ogni chunk due volte
Gli embedding cercano per significato. Trovano il passaggio sulla disdetta dell'abbonamento quando l'utente scrive «come smetto di pagare». Sulle stringhe esatte invece sono deboli: codici di errore, codici prodotto, nomi commerciali, numeri di clausola, cioè gli identificativi di cui sono fatte le domande tecniche e legali. Un indice per parole chiave come BM25, o la ricerca full-text di Postgres, li trova alla lettera.
I numeri di Anthropic mostrano che ognuno dei due indici fa la sua parte. Gli embedding contestuali da soli hanno portato il tasso di errore dal 5,7% al 3,7%. Con un indice per parole chiave sugli stessi chunk contestualizzati si è scesi al 2,9%, il 49% in meno rispetto alla partenza.
In Postgres stanno tutti e due nella stessa tabella: una colonna vector con un indice HNSW per la somiglianza e una colonna tsvector con un indice GIN per le parole chiave, come nella guida alla ricerca ibrida di Supabase. Nella stessa tabella tieni anche le colonne di accesso. Il passo 3 ne ha bisogno, e le policy seguono gli schemi di Supabase RLS in scala.
Passo 3: recupera largo e unisci le liste con la reciprocal rank fusion
A ogni domanda lancia entrambe le ricerche e prendi da ciascuna una lista ampia di candidati, tra i 50 e i 150 chunk. Applica il filtro di accesso dentro tutte e due le query. Filtrare dopo il recupero apre una falla: un documento che l'utente non può vedere spinge fuori dalla lista uno che potrebbe vedere, e un bug nel filtro lo consegna intero.
Le due liste hanno punteggi su scale diverse, la similarità coseno da una parte e BM25 dall'altra, e sommarli non ha senso. La reciprocal rank fusion lascia stare i punteggi e usa le posizioni:
punteggio(chunk) = 1 / (k + posizione nella lista vettoriale) + 1 / (k + posizione nella lista per parole chiave)Vince il chunk che sta in alto in entrambe. Quello trovato da una sola ricerca conta comunque. La costante k riduce la distanza tra il primo e il decimo posto: Cormack, Clarke e Büttcher l'hanno fissata a 60 nell'articolo presentato al SIGIR del 2009 che ha introdotto il metodo, e la funzione d'esempio di Supabase usa 50. Dai più peso a una delle due ricerche quando il set di prova lo indica, per esempio alle parole chiave se i documenti sono riferimenti di API.
Passo 4: riordina i candidati con un reranker e tieni una lista corta
Gli embedding valutano domanda e chunk separatamente. Un reranker, di solito un cross-encoder, li legge insieme e giudica se quel passaggio risponde a quella domanda. È più preciso e più lento, quindi vede solo i candidati già uniti. Anthropic ha passato i primi 150 a un reranker e ne ha tenuti 20. Il tasso di errore è sceso dal 2,9% all'1,9%, il 67% in meno rispetto ai soli embedding.
Il reranker aggiunge una chiamata a ogni domanda, con la sua latenza e il suo prezzo. Mettili sulla bilancia con il guadagno sul tuo set di prova. E togli i chunk quasi identici prima del taglio, così cinque copie dello stesso paragrafo non riempiono la lista.
Passo 5: metti prima i passaggi migliori e fai citare le fonti al modello
Dentro il prompt l'ordine conta. Lo studio Lost in the Middle (Liu e colleghi, TACL 2024) ha rilevato che i modelli usano meglio le informazioni quando stanno all'inizio o alla fine del contesto, e sensibilmente peggio quando stanno nel mezzo. Quindi manda meno passaggi, metti per primo quello in cima alla classifica e non riempire la finestra solo perché c'è spazio. Ogni chunk in più sono anche token pagati a ogni richiesta, un costo che analizziamo nell'articolo sul costo dei token nelle feature AI.
Etichetta ogni passaggio con un id, il titolo e la data. Poi chiedi tre cose nelle istruzioni: rispondere solo con i passaggi forniti, citare l'id dopo ogni affermazione e dire chiaramente quando i passaggi non contengono la risposta. Nell'interfaccia, mostra gli id come link alla fonte. Chi può aprire il paragrafo dietro una frase lo controlla in pochi secondi, e un «i documenti non ne parlano» vale più di un'ipotesi presentata come un fatto.
Passo 6: misura il recupero e le risposte separatamente
Una risposta sbagliata ha due cause possibili, e si correggono in modi diversi. O il recupero ha mancato il passaggio, o il modello ce l'aveva e ha scritto altro. Tieni un numero per ciascuna.
- Recall del recupero a k: per ogni domanda del set, il passaggio giusto è tra i primi k risultati? È il dato che riporta Anthropic, visto dall'altro lato.
- Fedeltà: ogni affermazione della risposta trova riscontro nei passaggi recuperati? Il framework RAGAS la definisce insieme alla pertinenza della risposta e a quella del contesto, e le misura tutte e tre senza risposte di riferimento scritte a mano.
Fai girare le 50 domande a ogni modifica del chunking, del prompt contestuale, del modello di embedding, del reranker o del prompt di sistema, e conserva i risultati release per release. In produzione registra la domanda, gli id recuperati con i punteggi, la risposta e le citazioni. Leggine un campione ogni settimana. Da quel log escono le domande che il set di prova non aveva previsto, e diventano le sue voci successive.
Come capire se funziona
- Una domanda con un identificativo esatto, un codice di errore o un codice prodotto, recupera il chunk che lo contiene.
- Una domanda a cui i documenti non rispondono riceve «non trattato», mai un'invenzione.
- Un utente di prova senza accesso a un documento non riceve mai un chunk di quel documento, né nella risposta né nelle citazioni.
- Recall a 20 e fedeltà sul set di prova escono con ogni release, accanto ai numeri della release precedente.
Errori frequenti e come correggerli
Le risposte restano indietro dopo che un documento cambia. Reindicizza il documento a ogni modifica: cancella i vecchi chunk e scrivi i nuovi con la data aggiornata. Una ricostruzione notturna lascia un giorno di risposte sbagliate.
Un nuovo modello di embedding peggiora i risultati da un giorno all'altro. I vettori di due modelli diversi non si possono confrontare. Ricalcola gli embedding di tutto l'archivio in un nuovo indice con un numero di versione, fai girare il set di prova e passa al nuovo solo se vince.
Tabelle e procedure tornano a pezzi. Il divisore tagliava a numero di caratteri. Passa a un chunking che segue la struttura e tieni ogni tabella o lista numerata in un solo chunk.
Il modello ignora il passaggio con la risposta. Era ottavo su venti, in mezzo al contesto. Usa il reranker, accorcia la lista e metti il passaggio migliore per primo.
Lo streaming nasconde un recupero lento. Il primo token arriva tardi e nessuno sa perché. Misura i tempi di recupero e di reranking da soli, prima che parta la generazione; la parte di streaming è nella guida all'API Anthropic in Next.js.
Domande frequenti
Per un archivio piccolo e stabile, spesso no. Secondo Anthropic, una base di conoscenza sotto i 200.000 token, circa 500 pagine, entra per intero nel prompt, e il prompt caching contiene il costo delle richieste ripetute. Il contesto lungo non basta più quando i documenti sono di più, cambiano ogni giorno o includono file che alcuni utenti non devono vedere, perché un prompt non applica permessi. In più ogni domanda paga tutti i token inviati. E lo studio Lost in the Middle mostra che più contesto non significa usarlo meglio. Le due cose stanno bene insieme: il recupero sceglie, una finestra ampia legge.
Se il prodotto gira già su Postgres, parti da pgvector e dalla ricerca full-text nella stessa tabella. Ricerca ibrida, filtri di accesso e join con i tuoi dati stanno così in una sola query, e non c'è un secondo sistema da tenere allineato. Un database vettoriale dedicato si giustifica quando il numero di vettori o il carico di query supera quello che una sola istanza Postgres serve entro la latenza che ti sei dato, e lo diranno i tuoi test di carico. Decidi sulle misure, e tieni il recupero dietro una sola funzione, così l'archivio si può cambiare più avanti senza toccare il resto.
Applica i permessi dentro la query di recupero, mai nel prompt. Salva il cliente o la lista di accesso su ogni chunk, filtra su quella colonna sia nella ricerca vettoriale sia in quella per parole chiave, e affianca la row-level security come seconda difesa. Un'istruzione come «non rivelare i file riservati» è testo da cui il modello si può far convincere a uscire. Separa per utente o per cliente anche qualunque cache di risposte o di chunk recuperati, perché una cache condivisa serve a una persona i risultati di un'altra. Prova con un utente senza accesso e controlla le citazioni oltre alla risposta.
Aggiorna i chunk di un documento ogni volta che il documento cambia, così l'indice non resta mai indietro rispetto alla fonte. Ricostruisci tutto solo quando cambia qualcosa di generale: le regole di chunking, il prompt contestuale o il modello di embedding. Costruisci il nuovo indice accanto al vecchio con un numero di versione, fai girare il set di prova su entrambi e passa al nuovo quando ottiene risultati almeno pari. Tieni la versione vecchia finché la nuova non ha retto qualche giorno di traffico vero, così tornare indietro è un cambio di configurazione.
Articoli correlati
30 luglio 2026 · 6 min di lettura
28 ottobre 2026 · 9 min di lettura
12 luglio 2026 · 7 min di lettura