Preparare i Dati
In questa pagina
La Qualità del RAG Dipende dai Tuoi Dati
Una pipeline RAG è buona solo quanto i dati che indicizza. Puoi creare il prompt perfetto e selezionare il miglior modello di generazione, ma se il frammento recuperato taglia a metà una definizione o include un piè di pagina ripetitivo invece del testo utile, la tua risposta ne risentirà. La preparazione avviene in tre fasi: recuperare i dati dalla loro sede, rimuovere tutto ciò che non ha senso e suddividerli in frammenti ottimizzati per l’indicizzazione.
Recupero dei Dati
I corpora del mondo reale sono raramente omogenei. In genere avrai documentazione Markdown in un repository, alcune pagine da un sito web pubblico e una manciata di PDF normativi. Ogni fonte richiede il proprio caricatore, ma tutti devono produrre la stessa struttura—contenuto, fonte e tipo—così che il resto della pipeline rimanga agnostico rispetto all’origine del testo.
Per i file di testo, una scansione ricorsiva delle directory è sufficiente e il filtro per estensione impedisce di caricare accidentalmente file binari.
import os
def load_text_files(directory, extensions=(".txt", ".md", ".rst")):
"""Carica tutti i file di testo da una directory."""
documents = []
for root, dirs, files in os.walk(directory):
for f in files:
if any(f.endswith(ext) for ext in extensions):
filepath = os.path.join(root, f)
with open(filepath, "r", encoding="utf-8") as fh:
content = fh.read()
documents.append({
"content": content,
"source": filepath,
"type": "text",
})
return documents
docs = load_text_files("./data/")
print(f"{len(docs)} documenti caricati")
Le pagine web arrivano tramite HTTP, ma ciò che ottieni è HTML. L’estrazione seguente rimuove i tag usando espressioni regolari e collassa gli spazi multipli. Questo è sufficiente per un prototipo, ma il commento ti ricorda che in produzione BeautifulSoup farà un lavoro molto migliore con tabelle ed elenchi annidati.
import requests
def fetch_web_page(url):
"""Recupera il contenuto testuale di una pagina web."""
response = requests.get(url)
response.raise_for_status()
# Estrazione base del testo (usa BeautifulSoup per la produzione)
text = response.text
# Rimuovi i tag HTML
import re
text = re.sub(r'<[^>]+>', ' ', text)
text = re.sub(r'\s+', ' ', text).strip()
return {
"content": text,
"source": url,
"type": "web",
}
# Esempio
page = fetch_web_page("https://raw.githubusercontent.com/run-llama/llama_index/main/docs/docs/examples/data/paul_graham/paul_graham_essay.txt")
print(f"Contenuto: {len(page['content'])} caratteri")
I PDF meritano un trattamento speciale. Invece di concatenare l’intero documento, mantieni una voce per pagina e codifica il numero di pagina nella fonte come file.pdf#page=12. Quando il tuo assistente cita questo passaggio, l’utente saprà esattamente dove verificarlo.
# pip install PyPDF2
from PyPDF2 import PdfReader
def load_pdf(filepath):
"""Estrae il testo da un PDF."""
reader = PdfReader(filepath)
pages = []
for i, page in enumerate(reader.pages):
text = page.extract_text()
if text.strip():
pages.append({
"content": text,
"source": f"{filepath}#page={i+1}",
"type": "pdf",
"page": i + 1,
})
return pages
Pulizia dei Dati
La pulizia è fondamentale per la qualità del recupero perché ogni carattere estraneo consuma spazio nel frammento e offusca il vettore risultante. La funzione seguente concatena quattro trattamenti: rimuove i caratteri di controllo rimasti dalle conversioni di formato, normalizza le sequenze di nuove righe e spazi, cancella i marcatori di impaginazione tipici dei PDF e sostituisce gli URL infiniti con un semplice segnaposto affinché non occupino un intero frammento.
import re
def clean_text(text):
"""Pulisce il testo per l'indicizzazione RAG."""
# Rimuovi i caratteri di controllo
text = re.sub(r'[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]', '', text)
# Normalizza spazi e nuove righe
text = re.sub(r'\n{3,}', '\n\n', text)
text = re.sub(r' {2,}', ' ', text)
# Rimuovi intestazioni/piè di pagina ripetitivi (PDF)
text = re.sub(r'Page \d+ of \d+', '', text)
# Rimuovi URL molto lunghi
text = re.sub(r'https?://\S{100,}', '[URL]', text)
return text.strip()
# Applica la pulizia
for doc in docs:
doc["content"] = clean_text(doc["content"])
Strategie di Frammentazione (Chunking)
La frammentazione è il passo più importante nella preparazione: la dimensione e il metodo del frammento impattano direttamente sulla qualità del recupero. Esistono tre approcci, che vanno dal meccanico a quello consapevole della struttura.
La frammentazione a dimensione fissa scorre il testo in fette regolari. Ignora completamente il significato, rendendola applicabile a qualsiasi fonte, ma spesso taglia le frasi a metà. La sovrapposizione corregge parzialmente questo difetto: con overlap=200, la fine di ogni frammento si ripete all’inizio del successivo, garantendo che un’idea divisa rimanga intera in almeno uno dei due pezzi.
def chunk_fixed_size(text, chunk_size=2048, overlap=200):
"""Frammentazione a dimensione fissa con sovrapposizione."""
chunks = []
start = 0
while start < len(text):
end = min(start + chunk_size, len(text))
chunk = text[start:end]
if chunk.strip():
chunks.append(chunk.strip())
start += chunk_size - overlap
return chunks
La frammentazione basata sui paragrafi, raccomandata per la documentazione, si basa invece sui confini naturali del testo. Accumula i paragrafi finché restano sotto max_size, poi apre un nuovo frammento. La soglia min_size impedisce di indicizzare un titolo orfano o una riga isolata, che produrrebbero un vettore senza contenuto utilizzabile.
def chunk_by_paragraphs(text, max_size=1500, min_size=100):
"""Frammentazione intelligente basata sui paragrafi."""
paragraphs = text.split("\n\n")
chunks = []
current = ""
for para in paragraphs:
para = para.strip()
if not para:
continue
if len(current) + len(para) + 2 <= max_size:
current = current + "\n\n" + para if current else para
else:
if len(current) >= min_size:
chunks.append(current)
current = para
if current and len(current) >= min_size:
chunks.append(current)
return chunks
La frammentazione per sezioni Markdown sfrutta le informazioni già fornite dall’autore: i suoi titoli. Ogni sezione diventa un frammento autonomo, garantendo che una domanda su “autenticazione” recuperi l’intera sezione piuttosto che un frammento. Le sezioni troppo lunghe ricadono sulla frammentazione per paragrafi, assicurando che nessun frammento superi il limite.
def chunk_by_markdown_sections(text, max_size=2000):
"""Frammentazione per intestazioni Markdown (## e ###)."""
sections = re.split(r'\n(?=##\s)', text)
chunks = []
for section in sections:
section = section.strip()
if not section:
continue
if len(section) <= max_size:
chunks.append(section)
else:
# Sotto-frammenta le sezioni eccessivamente lunghe
sub_chunks = chunk_by_paragraphs(section, max_size=max_size)
chunks.extend(sub_chunks)
return chunks
Pipeline di Preparazione Completa
Infine, concatena le tre operazioni e scegli la strategia di frammentazione in base al tipo di file: i file .md passano attraverso le sezioni, tutto il resto attraverso i paragrafi. Ogni frammento porta poi i suoi metadati—fonte, posizione nel documento e numero totale di frammenti da quel documento. Senza questo, non potrai tracciare la fonte di una risposta. Le ultime due righe mostrano il tasso di espansione e la dimensione media: se questa media scende ben al di sotto del tuo chunk_size, il documento è più frammentato del previsto e devi rivedere la tua strategia di frammentazione.
def prepare_documents(raw_docs, chunk_size=1500, overlap=200):
"""Pipeline completa: pulisci, frammenta, arricchisci con metadati."""
all_chunks = []
for doc in raw_docs:
# 1. Pulisci
clean = clean_text(doc["content"])
# 2. Frammenta in base al tipo
if doc.get("source", "").endswith(".md"):
chunks = chunk_by_markdown_sections(clean, max_size=chunk_size)
else:
chunks = chunk_by_paragraphs(clean, max_size=chunk_size)
# 3. Arricchisci con metadati
for i, chunk in enumerate(chunks):
all_chunks.append({
"text": chunk,
"source": doc["source"],
"chunk_index": i,
"total_chunks": len(chunks),
})
return all_chunks
# Esecuzione
chunks = prepare_documents(docs)
print(f"{len(docs)} documenti -> {len(chunks)} frammenti")
print(f"Dimensione media: {sum(len(c['text']) for c in chunks) / len(chunks):.0f} caratteri")
Punti chiave
- La qualità del RAG dipende direttamente dalla qualità dei dati e dalla strategia di frammentazione
- Pulisci i dati prima dell’indicizzazione (rimuovi caratteri estranei, URL lunghi, duplicati)
- La frammentazione per paragrafi o sezioni Markdown preserva la coerenza semantica
- Una sovrapposizione del 10–15% tra i frammenti impedisce di dividere le idee
- Mantieni i metadati (fonte, pagina, posizione) per la tracciabilità delle risposte