Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Architettura RAG Completa

Lezione 11 di 22 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Obiettivi
  2. Cos’è il RAG?
  3. Fasi della Pipeline
  4. Implementazione Completa
  5. Utilizzo
  6. Punti di Ottimizzazione
  7. Punti chiave

Lezione aggiornata il 3 novembre 2026 sulla base della documentazione OpenAI: temperature e top_p sono accettati solo con uno sforzo di ragionamento (reasoning effort) impostato su none, mentre i modelli GPT-5.6 ragionano per impostazione predefinita (medium). Le chiamate che impostano questi parametri devono quindi specificare reasoning={"effort": "none"} (API Responses) o reasoning_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.

PassoPossibili Ottimizzazioni
ChunkingDimensione del chunk, sovrapposizione, chunking semantico
EmbeddingScelta del modello, dimensioni, arricchimento del testo
RicercaIbrida, reranking, filtri sui metadata
PromptIstruzioni di sistema, formato del contesto, few-shot
GenerazioneModello, 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