Architettura RAG Completa
In questa pagina
Lezione aggiornata il 3 novembre 2026 sulla base della documentazione OpenAI:
temperatureetop_psono accettati solo con uno sforzo di ragionamento (reasoning effort) impostato sunone, mentre i modelli GPT-5.6 ragionano per impostazione predefinita (medium). Le chiamate che impostano questi parametri devono quindi specificarereasoning={"effort": "none"}(API Responses) oreasoning_effort="none"(Chat Completions). Fonti: Using GPT-6 · GPT-5.6 Terra.
Obiettivi
- Comprendere l’architettura RAG end-to-end
- Implementare una pipeline RAG funzionale
- Identificare i componenti da ottimizzare
Cos’è il RAG?
Il RAG (Retrieval-Augmented Generation) combina la ricerca documentale con la generazione di testo da parte di un LLM. Invece di affidarsi esclusivamente alle sue conoscenze interne, il modello riceve documenti pertinenti come contesto, per poi elaborare la risposta basandosi su di essi. Tutto ciò che hai costruito dall’inizio di questo corso—embedding, indicizzazione, ricerca, valutazione—diventa qui la metà a monte di un sistema completo.
Perché il RAG?
Quattro ragioni lo giustificano, e si sommano tra loro. Innanzitutto, i dati proprietari: le tue policy sul lavoro da remoto, le procedure interne e il catalogo prodotti non sono mai apparsi nei dati di addestramento del modello, e nessun prompt potrà mai farveli apparire. In secondo luogo, le informazioni recenti: tutto ciò che è successivo alla data di addestramento è invisibile al modello, mentre un indice può essere aggiornato lo stesso giorno. La verificabilità conta altrettanto, perché ogni risposta è ancorata a fonti identificabili che l’utente può aprire e controllare, trasformando la natura della fiducia riposta nel sistema. Infine, il costo gioca a suo favore: aggiungere conoscenza tramite RAG costa molto meno del fine-tuning e le correzioni avvengono eliminando un documento piuttosto che riaddestrando un modello.
Fasi della Pipeline
Leggi il RAG come due fasi distinte che non devi confondere. L’ingestione avviene offline, una volta per tutte o ogni volta che il corpus si aggiorna:
Documenti → Chunking → Embedding → Archiviazione Vettoriale
La query avviene online, per ogni domanda posta, e deve rimanere veloce:
Domanda → Embedding → Ricerca → Contesto + Domanda → LLM → Risposta
Questa separazione ha una conseguenza pratica: i costi di ingestione si sostengono una volta sola e possono essere elevati, mentre i costi di query si pagano per ogni chiamata e determinano l’esperienza utente. Puoi quindi permetterti un’elaborazione sofisticata in fase di ingestione, ma devi mantenere la fase di query leggera.
Implementazione Completa
La classe seguente materializza le tre fasi in tre metodi distinti, più un quarto che le concatena. Questa separazione non è cosmetica: ti permette di testare la ricerca senza consumare token di generazione e di rieseguire la generazione su un contesto fisso per confrontare due prompt diversi.
from openai import OpenAI
import numpy as np
client = OpenAI()
class PipelineRAG:
def __init__(
self,
model_embedding: str = "text-embedding-3-large",
model_generation: str = "gpt-5.6-terra"
):
self.client = OpenAI()
self.model_embedding = model_embedding
self.model_generation = model_generation
self.chunks: list[dict] = []
self.embeddings: np.ndarray | None = None
# --- Fase di Ingestione ---
def ingest(self, documents: list[dict]):
"""Ingerisce documenti {id, text, metadata}."""
self.chunks = documents
texts = [d["text"] for d in documents]
# Genera embedding in batch
all_emb = []
for i in range(0, len(texts), 100):
batch = texts[i:i + 100]
resp = self.client.embeddings.create(
input=batch, model=self.model_embedding
)
batch_emb = sorted(resp.data, key=lambda x: x.index)
all_emb.extend([e.embedding for e in batch_emb])
self.embeddings = np.array(all_emb, dtype=np.float32)
print(f"Ingestione completata: {len(self.chunks)} chunk indicizzati")
# --- Fase di Recupero ---
def search(self, question: str, k: int = 5) -> list[dict]:
"""Trova i k chunk più rilevanti."""
query_emb = self.client.embeddings.create(
input=question, model=self.model_embedding
).data[0].embedding
scores = self.embeddings @ np.array(query_emb)
top_k = np.argsort(scores)[-k:][::-1]
return [
{**self.chunks[i], "score": float(scores[i])}
for i in top_k
]
# --- Fase di Generazione ---
def generate(self, question: str, contexts: list[dict]) -> str:
"""Genera una risposta basata sui contesti recuperati."""
# Costruisci il prompt
formatted_context = "\n\n---\n\n".join(
f"[Source: {c.get('id', 'unknown')}]\n{c['text']}"
for c in contexts
)
messages = [
{
"role": "system",
"content": (
"You are an assistant that answers questions "
"based solely on the provided documents. "
"If the information is not in the documents, "
"state this clearly. Cite your sources."
)
},
{
"role": "user",
"content": (
f"Reference documents:\n\n{formatted_context}\n\n"
f"---\n\nQuestion: {question}"
)
}
]
response = self.client.chat.completions.create(
model=self.model_generation,
reasoning_effort="none", # temperature richiede effort none
messages=messages,
temperature=0.2
)
return response.choices[0].message.content
# --- Pipeline Completa ---
def answer(self, question: str, k: int = 5) -> dict:
"""Pipeline RAG completa: ricerca → generazione."""
contexts = self.search(question, k=k)
response = self.generate(question, contexts)
return {
"question": question,
"response": response,
"sources": [
{"id": c["id"], "score": c["score"],
"excerpt": c["text"][:150]}
for c in contexts
]
}
Tre dettagli nella fase di generazione guidano la maggior parte della qualità. Il messaggio di sistema impone di rispondere solo dai documenti forniti e di ammettere quando le informazioni mancano: senza questa istruzione, il modello colmerà le lacune con le sue conoscenze generali, producendo una risposta plausibile ma inventata. Il prefisso [Source: id] prima di ogni estratto fornisce al modello qualcosa di specifico da citare, invece di un vago “secondo i documenti”. Infine, una temperature di 0.2 riduce la variabilità: per domande fattuali contro una base documentale, vuoi coerenza, non creatività.
Utilizzo
Testiamo la pipeline su un caso d’uso aziendale minimale: tre policy interne e una domanda che non copia nessuna delle loro formulazioni esatte.
# Prepara i documenti
documents = [
{
"id": "leave-policy",
"text": "Employees receive 25 days of paid leave "
"per year. Leave must be requested at least 2 weeks "
"in advance via the HR portal.",
"metadata": {"type": "hr", "date": "2026-01"}
},
{
"id": "remote-work-policy",
"text": "Remote work is authorized up to 3 days per week. "
"Tuesdays and Thursdays are mandatory office days. "
"Written agreement with the manager is required.",
"metadata": {"type": "hr", "date": "2026-01"}
},
{
"id": "reimbursement-procedure",
"text": "Expense reports must be submitted within 30 days "
"of the expense. Attach the original receipt. "
"Validation by the direct supervisor required for amounts over 200 euros.",
"metadata": {"type": "finance", "date": "2026-01"}
},
]
# Crea la pipeline
rag = PipelineRAG()
rag.ingest(documents)
# Poni una domanda
result = rag.answer("How many days of remote work per week?")
print(result["response"])
print("\nSources used:")
for s in result["sources"]:
print(f" [{s['score']:.3f}] {s['id']}: {s['excerpt']}")
Spingi l’esercizio oltre ponendo una domanda a cui nessun documento risponde, ad esempio sul piano sanitario aziendale. La pipeline restituirà comunque tre fonti—la ricerca restituisce sempre i suoi k migliori candidati—ed è il messaggio di sistema che deve impedire al modello di inventare una risposta. Verificare questo comportamento prima della produzione è meglio che scoprirlo tramite un reclamo.
Punti di Ottimizzazione
Ogni passo della pipeline può essere migliorato indipendentemente, permettendo progressi attraverso piccoli aggiustamenti misurabili.
| Passo | Possibili Ottimizzazioni |
|---|---|
| Chunking | Dimensione del chunk, sovrapposizione, chunking semantico |
| Embedding | Scelta del modello, dimensioni, arricchimento del testo |
| Ricerca | Ibrida, reranking, filtri sui metadata |
| Prompt | Istruzioni di sistema, formato del contesto, few-shot |
| Generazione | Modello, temperatura, citazioni |
Le prossime lezioni dettagliano ciascuna di queste ottimizzazioni. Affrontale in questo ordine: il chunking determina cosa può essere recuperato, e nessun reranking potrà mai correggere un documento frammentato male.
Punti chiave
- RAG = Ricerca + Contesto + Generazione LLM
- La pipeline si divide in ingestione (offline) e query (online)
- Ogni componente (chunking, embedding, ricerca, prompt, generazione) può essere ottimizzato indipendentemente
- Il RAG è più flessibile e meno costoso del fine-tuning per aggiungere conoscenza