Pipeline RAG Completo
In questa pagina
Mettiamo Tutto Insieme
Le lezioni precedenti hanno trattato ogni anello della catena separatamente: caricamento, frammentazione, codifica, indicizzazione, recupero e generazione. Ora è il momento di saldarli in un unico programma completo ed end-to-end che puoi eseguire così com’è e poi adattare ai tuoi documenti. Questo script sta in un solo file e richiede solo quattro dipendenze.
pip install mistralai faiss-cpu numpy requests
Il Pipeline Completo
Due scelte di progettazione strutturano questo codice. In primo luogo, raggruppiamo tutta la configurazione all’inizio del file: modelli, dimensione dei chunk, dimensione del batch e TOP_K sono costanti nominate. Questo ti evita di dover cercare valori hard-coded sepolti dentro le funzioni quando devi ottimizzare il comportamento. In secondo luogo, dividiamo la logica in sei funzioni indipendenti, ciascuna corrispondente a un passaggio e che stampa il proprio avanzamento come [n/6]. Questa traccia non è decorativa: quando il pipeline fallisce o restituisce una risposta strana, ti dice immediatamente se il problema risiede nel caricamento, nella frammentazione o nel recupero. Ogni funzione è anche sostituibile in isolamento: puoi inserire un caricatore PDF per load_data senza toccare il resto.
La funzione main concatena i passaggi, quindi interroga il corpus con tre domande sul saggio di Paul Graham usato come nostro dataset demo. Nota che recupero e generazione avvengono all’interno del ciclo, mentre l’indicizzazione avviene una sola volta in precedenza: ricodificare l’intero corpus per ogni domanda sarebbe assurdo sia in termini di costi che di latenza.
import os
import json
import numpy as np
import faiss
import requests
from mistralai.client import Mistral
# ============================================================
# Configurazione
# ============================================================
MISTRAL_API_KEY = os.environ.get("MISTRAL_API_KEY")
EMBED_MODEL = "mistral-embed"
CHAT_MODEL = "mistral-large-latest"
CHUNK_SIZE = 2048
BATCH_SIZE = 25
TOP_K = 3
client = Mistral(api_key=MISTRAL_API_KEY)
# ============================================================
# Passaggio 1: Caricamento Dati
# ============================================================
def load_data(url):
"""Carica un documento di testo da un URL."""
print("[1/6] Caricamento dati...")
response = requests.get(url)
response.raise_for_status()
text = response.text
print(f" -> {len(text)} caratteri caricati")
return text
# ============================================================
# Passaggio 2: Creazione Chunk
# ============================================================
def create_chunks(text, chunk_size=CHUNK_SIZE):
"""Divide il testo in chunk."""
print("[2/6] Creazione chunk...")
chunks = []
paragraphs = text.split("\n\n")
current = ""
for para in paragraphs:
para = para.strip()
if not para:
continue
if len(current) + len(para) + 2 <= chunk_size:
current = current + "\n\n" + para if current else para
else:
if current:
chunks.append(current)
current = para
if current:
chunks.append(current)
print(f" -> {len(chunks)} chunk creati (dim media: {sum(len(c) for c in chunks) // len(chunks)} char)")
return chunks
# ============================================================
# Passaggio 3: Generazione Embedding
# ============================================================
def create_embeddings(chunks, batch_size=BATCH_SIZE):
"""Codifica i chunk in embedding tramite mistral-embed."""
print("[3/6] Generazione embedding...")
all_embeddings = []
for i in range(0, len(chunks), batch_size):
batch = chunks[i:i + batch_size]
response = client.embeddings.create(
model=EMBED_MODEL,
inputs=batch,
)
all_embeddings.extend([d.embedding for d in response.data])
print(f" -> Batch {i // batch_size + 1}/{(len(chunks) - 1) // batch_size + 1} codificato")
embeddings = np.array(all_embeddings, dtype=np.float32)
print(f" -> Matrice: {embeddings.shape}")
return embeddings
# ============================================================
# Passaggio 4: Creazione Indice FAISS
# ============================================================
def create_index(embeddings):
"""Crea e popola un indice FAISS."""
print("[4/6] Creazione indice FAISS...")
dimension = embeddings.shape[1]
index = faiss.IndexFlatL2(dimension)
index.add(embeddings)
print(f" -> Indice: {index.ntotal} vettori, dimensione {dimension}")
return index
# ============================================================
# Passaggio 5: Recupero Chunk Rilevanti
# ============================================================
def retrieve(question, index, chunks, k=TOP_K):
"""Recupera i chunk più rilevanti."""
print(f"[5/6] Ricerca per: '{question[:50]}...'")
response = client.embeddings.create(
model=EMBED_MODEL,
inputs=[question],
)
query_vector = np.array([response.data[0].embedding], dtype=np.float32)
distances, indices = index.search(query_vector, k)
results = []
for dist, idx in zip(distances[0], indices[0]):
if idx >= 0:
results.append({
"text": chunks[idx],
"distance": float(dist),
})
print(f" -> {len(results)} chunk recuperati")
return results
# ============================================================
# Passaggio 6: Generazione Risposta
# ============================================================
def generate(question, context_chunks):
"""Genera la risposta usando il contesto recuperato."""
print("[6/6] Generazione risposta...")
context = "\n\n---\n\n".join([c["text"] for c in context_chunks])
prompt = f"""Contesto informativo:
{context}
---
Basandoti SOLO sul contesto sopra, rispondi alla seguente domanda in modo preciso e completo.
Domanda: {question}"""
response = client.chat.complete(
model=CHAT_MODEL,
messages=[
{"role": "system", "content": "Sei un assistente che risponde basandosi sul contesto fornito."},
{"role": "user", "content": prompt},
],
temperature=0.1,
)
answer = response.choices[0].message.content
print(f" -> Risposta generata ({len(answer)} caratteri)")
return answer
# ============================================================
# Pipeline Principale
# ============================================================
def main():
"""Esegue il pipeline RAG completo."""
# 1. Caricamento
url = "https://raw.githubusercontent.com/run-llama/llama_index/main/docs/docs/examples/data/paul_graham/paul_graham_essay.txt"
text = load_data(url)
# 2. Frammentazione
chunks = create_chunks(text)
# 3. Codifica
embeddings = create_embeddings(chunks)
# 4. Indicizzazione
index = create_index(embeddings)
# 5+6. Domanda -> Risposta
questions = [
"Quali erano le due cose principali su cui l'autore ha lavorato prima dell'università?",
"Cosa ha fatto l'autore durante il suo periodo a Y Combinator?",
"Quale linguaggio di programmazione ha imparato per primo l'autore?",
]
for question in questions:
print(f"\n{'='*60}")
context = retrieve(question, index, chunks)
answer = generate(question, context)
print(f"\nD: {question}")
print(f"R: {answer}")
if __name__ == "__main__":
main()
Esecuzione del Pipeline
Salva questo codice come rag_pipeline.py, esporta la tua chiave API nell’ambiente (non hard-codarla mai nel file, che finirebbe prima o poi in un repository) ed esegui lo script. L’output attraversa i sei passaggi, quindi elabora le tre domande con le relative risposte. Se alguna risposta sembra fuori tema, confrontala con i chunk mostrati nel passaggio 5 prima di incolpare il modello di generazione.
export MISTRAL_API_KEY="your-api-key"
python rag_pipeline.py
Cinque Direzioni per Ulteriori Miglioramenti
Questo pipeline è una fondazione, non un prodotto finito, e ciascuno dei suoi limiti indica un passo successivo. Il più immediato è la persistenza: nella sua forma attuale, lo script ricodifica l’intero corpus ad ogni esecuzione, mentre salvare l’indice FAISS e i chunk renderebbe le esecuzioni successive quasi istantanee. Il re-ranking è il livello successivo, facendo passare i risultati di FAISS attraverso un cross-encoder che giudica la rilevanza in modo molto più fine della sola distanza vettoriale. Il filtraggio per metadati affronta un’altra necessità: vincolare la ricerca per data, categoria o autore oltre alla similarità. Due miglioramenti finali si concentrano sull’esperienza utente: lo streaming, che visualizza la risposta mentre viene generata invece che dopo alcuni secondi di silenzio, e la cronologia delle conversazioni, che permette agli utenti di fare follow-up con “e per la versione 2?” senza ripetere l’intera domanda.
# 1. Salva l'indice per evitare ricalcoli
faiss.write_index(index, "my_rag.index")
np.save("my_chunks.npy", np.array(chunks, dtype=object))
# 2. Aggiungi re-ranking
# Dopo il recupero FAISS, usa un modello cross-encoder
# per riordinare i risultati per rilevanza fine
# 3. Filtraggio metadati
# Aggiungi filtri (data, categoria, autore) oltre
# alla similarità vettoriale
# 4. Streaming risposta
# Usa client.chat.stream() per visualizzare la risposta
# mentre viene generata
# 5. Cronologia conversazione
# Aggiungi gli scambi precedenti al prompt
# per un chatbot RAG contestuale
Punti chiave
- Il pipeline RAG completo si scompone in 6 passaggi: caricamento, frammentazione, codifica, indicizzazione, recupero, generazione
- Ogni passaggio è una funzione indipendente, facile da testare e sostituire
- Usa
temperature=0.1per risposte fattuali - Salva l’indice FAISS e gli embedding per evitare ricalcoli ad ogni esecuzione
- Questo pipeline è un punto di partenza solido da arricchire in base alle tue esigenze