Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Prompting aumentato dal recupero

Lezione 9 di 16 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Prompting aumentato dal recupero
  2. Architettura di un sistema RAP
  3. Pipeline completa
  4. Chunking: suddivisione dei documenti
  5. Strategie di recupero avanzate
  6. Utilizzo della Ricerca File nativa di OpenAI
  7. Stabilire una baseline
  8. Punti chiave

Lezione aggiornata il 3 novembre 2026 in base alla documentazione OpenAI: temperature e top_p sono accettati solo con uno sforzo di ragionamento pari a 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.

Prompting aumentato dal recupero

Il Prompting Aumentato dal Recupero (RAP) combina la ricerca documentale con il prompting per fornire al modello un contesto pertinente e aggiornato. È l’evoluzione naturale del grounding: invece di iniettare manualmente il contesto, automatizzi la ricerca dei passaggi rilevanti prima di ogni chiamata all’LLM.

La differenza diventa evidente su larga scala. Incollare manualmente tre paragrafi utili dalla tua documentazione funziona per una demo; ma una volta che la tua base documentale raggiunge qualche centinaio di pagine e le domande arrivano in continuo, nessuno sa più quali passaggi incollare. Il RAP delega questa scelta a un componente automatico, chiamato prima di ogni generazione, il cui unico ruolo è trovare cosa inserire nel prompt.

Architettura di un sistema RAP

Una pipeline RAP si scompone in tre fasi che operano a velocità e costi diversi. L’indicizzazione trasforma i tuoi documenti in embedding vettoriali; questo avviene una volta sola, offline, convertendo ogni documento in un vettore numerico che ne codifica il significato, archiviato insieme al testo originale. Il recupero, al contrario, viene eseguito per ogni domanda: trasformi la domanda in un vettore usando lo stesso modello di embedding, poi cerchi i vettori documentali più vicini. Infine, l’aumento è semplicemente un prompting standard: costruisci un prompt di sistema contenente i passaggi recuperati e istruisci il modello a non uscire da questo ambito.

Ricorda questa divisione: tutto ciò che è costoso avviene durante l’indicizzazione, dove puoi permetterti di essere esigente, mentre tutto ciò che si ripete per ogni domanda deve rimanere veloce. Il codice sottostante implementa i primi due passaggi utilizzando la similarità del coseno come misura di prossimità.

from openai import OpenAI
import numpy as np

client = OpenAI()

# Step 1: Generate document embeddings
def embed_texts(texts: list[str]) -> list[list[float]]:
    """Generates embeddings for a list of texts."""
    response = client.embeddings.create(
        model="text-embedding-3-large",
        input=texts
    )
    return [item.embedding for item in response.data]

# Step 2: Search by cosine similarity
def cosine_similarity(a: list[float], b: list[float]) -> float:
    """Calculates cosine similarity between two vectors."""
    a, b = np.array(a), np.array(b)
    return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)))

def retrieve(query: str, documents: list[str],
             doc_embeddings: list[list[float]],
             top_k: int = 3) -> list[str]:
    """Returns the top_k most relevant documents."""
    query_emb = embed_texts([query])[0]

    scores = [
        (i, cosine_similarity(query_emb, doc_emb))
        for i, doc_emb in enumerate(doc_embeddings)
    ]
    scores.sort(key=lambda x: x[1], reverse=True)

    return [documents[i] for i, _ in scores[:top_k]]

Pipeline completa

Assemblando questi mattoni si ottiene una classe che sta in una trentina di righe. La maggior parte delle decisioni avviene nel prompt di sistema generato, e vale la pena leggerlo riga per riga. Il modello riceve prima l’ordine di rispondere SOLO basandosi sui passaggi forniti, il che limita le risposte allucinate quando la documentazione è silente. Riceve poi l’istruzione di citare il numero del passaggio per ogni affermazione, ed è questo che rende possibile la verifica: un revisore può risalire alla fonte a colpo d’occhio. Una temperature di 0.1 completa l’impostazione: su una risposta ancorata ai documenti, la creatività è un bug.

class RAGPipeline:
    """Minimalist RAP pipeline."""

    def __init__(self, documents: list[str]):
        self.documents = documents
        self.embeddings = embed_texts(documents)

    def query(self, question: str, top_k: int = 3) -> str:
        """Answers a question based on the documents."""
        # Retrieval
        relevant_docs = retrieve(
            question, self.documents,
            self.embeddings, top_k
        )

        # Prompt augmentation
        context = "\n\n---\n\n".join(
            f"[Passage {i+1}]\n{doc}"
            for i, doc in enumerate(relevant_docs)
        )

        system = f"""You are a technical assistant.
Answer ONLY based on the provided passages.
If the passages do not contain the answer, say so.
Cite the passage number for every claim.

RELEVANT PASSAGES:
{context}"""

        # Generation
        response = client.responses.create(
            model="gpt-5.6-terra",
            reasoning={"effort": "none"},  # temperature requires effort none
            instructions=system,
            input=question,
            temperature=0.1
        )
        return response.output_text

Chunking: suddivisione dei documenti

Suddividere i documenti in chunk è cruciale per la qualità del recupero. Se i chunk sono troppo grandi, affogano le informazioni rilevanti; se troppo piccoli, perdono il contesto. Un manuale API suddiviso in blocchi da dieci pagine restituirà sempre lo stesso blocco generico, indipendentemente dalla domanda posta. Suddiviso in frasi isolate, restituirà una frase che inizia con “questo metodo” senza che il modello sappia a quale metodo ci si riferisca. L’overlap (sovrapposizione) mitiga specificamente questo rischio: ogni chunk ripete la fine del precedente, così le informazioni che attraversano un confine rimangono leggibili da almeno un lato.

Quando i tuoi documenti hanno una struttura di intestazioni, il chunking basato sulle sezioni è quasi sempre superiore al chunking a dimensione fissa: una sezione “Autenticazione” rimane intatta, con la sua introduzione e i suoi esempi.

def chunk_document(text: str, chunk_size: int = 500,
                   overlap: int = 50) -> list[str]:
    """Splits text into chunks with overlap."""
    words = text.split()
    chunks = []

    for i in range(0, len(words), chunk_size - overlap):
        chunk = " ".join(words[i:i + chunk_size])
        if chunk.strip():
            chunks.append(chunk)

    return chunks

def chunk_by_sections(text: str) -> list[str]:
    """Splits by sections (Markdown headings)."""
    sections = []
    current = []

    for line in text.split("\n"):
        if line.startswith("## ") and current:
            sections.append("\n".join(current))
            current = [line]
        else:
            current.append(line)

    if current:
        sections.append("\n".join(current))

    return sections

Strategie di recupero avanzate

Reranking

Dopo il recupero iniziale, usa l’LLM per riordinare i risultati. La logica è quella di un imbuto: la ricerca vettoriale è veloce ma approssimativa e riporta una dozzina di candidati plausibili; il modello, più lento ma più sfumato, rilegge questi candidati conoscendo la domanda e li classifica. Mantieni poi solo la cima della lista per la generazione. Il guadagno è più visibile sulle domande in cui diversi passaggi parlano dello stesso argomento ma solo uno risponde effettivamente: tre sezioni menzionano la parola “quota”, ma solo una spiega come aumentarla.

def rerank(question: str, passages: list[str]) -> list[str]:
    """Reorders passages by relevance using the LLM."""
    prompt = f"""Question: {question}

Here are candidate passages. Rank them from most relevant
to least relevant for answering the question.
Return only the numbers in order (e.g., 3, 1, 2).

{chr(10).join(f"[{i+1}] {p[:200]}" for i, p in enumerate(passages))}"""

    response = client.responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperature requires effort none
        input=prompt,
        temperature=0.0
    )
    # Parse returned order and reorganize
    return response.output_text

Hypothetical Document Embedding (HyDE)

Genera un documento ipotetico ideale, poi cerca documenti simili. Il problema che questa tecnica risolve è la discrepanza lessicale: una domanda posta in linguaggio quotidiano non assomiglia, vettorialmente, a un paragrafo di documentazione tecnica. Chiedendo prima al modello di scrivere la risposta che immagina, ottieni un testo scritto nel registro dei tuoi documenti, ed è questo testo che usi come query. Non importa se il paragrafo ipotetico contiene approssimazioni: non serve mai come risposta, ma solo come sonda.

def hyde_retrieve(question: str, documents: list[str],
                  doc_embeddings: list[list[float]]) -> list[str]:
    """Retrieval via HyDE."""
    # Generate a hypothetical passage
    hypo_response = client.responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperature requires effort none
        input=f"Write a short technical paragraph that would perfectly "
              f"answer this question: {question}",
        temperature=0.5
    )
    hypothetical_doc = hypo_response.output_text

    # Search for documents similar to the hypothetical passage
    return retrieve(hypothetical_doc, documents,
                    doc_embeddings, top_k=3)

Utilizzo della Ricerca File nativa di OpenAI

Per una distribuzione rapida, l’API offre un recupero integrato. Carichi il file, crei un vector store, alleghi il file ad esso e dichiari lo strumento file_search nella chiamata: chunking, embedding e ricerca sono gestiti lato server. Questa è la scelta giusta quando i tuoi documenti sono standard e non ti importa dove risiedano i dati. La pipeline fatta in casa mantiene il vantaggio non appena hai bisogno di padroneggiare il chunking, ospitare l’indice tu stesso o inserire un reranking specifico.

# Upload file
file = client.files.create(
    file=open("documentation.pdf", "rb"),
    purpose="assistants"
)

# Create a vector store
vector_store = client.vector_stores.create(
    name="Technical Documentation"
)

client.vector_stores.files.create(
    vector_store_id=vector_store.id,
    file_id=file.id
)

# Query with File Search
response = client.responses.create(
    model="gpt-5.6-terra",
    instructions="Answer based on the provided documentation.",
    input="How do I configure authentication?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id]
    }]
)

Stabilire una baseline

Prendi dalle cinque alle dieci pagine di documentazione tecnica e implementa l’intera pipeline, dal chunking alla generazione. Scrivi dieci domande le cui risposte si trovano nei documenti, esegui la pipeline su ciascuna, poi ripeti con il reranking abilitato: è osservando su quali domande cambia la classifica che capisci cosa manca alla sola ricerca vettoriale. Concludi misurando la percentuale di risposte correttamente ancorate, quelle in cui ogni affermazione si riferisce effettivamente a un passaggio fornito. Questa cifra è il tuo punto di partenza; tutte le ottimizzazioni successive saranno giudicate rispetto ad essa, non rispetto all’impressione lasciata da due o tre risposte lette a caso.

Punti chiave

  • Il RAP automatizza l’iniezione di contesto rilevante nel prompt
  • Il chunking è critico: sperimenta con dimensioni diverse
  • Il reranking con l’LLM migliora significativamente la pertinenza
  • HyDE è utile quando la domanda differisce notevolmente dal lessico dei documenti
  • OpenAI File Search semplifica la distribuzione per i casi standard