Ragas: valutare il proprio RAG locale con dei chiffres

#Perché «sembra buono» non basta

Ragas è una libreria Python open source, con licenza Apache 2.0, che quantifica la qualità di una pipeline di ricerca documentale: la fedeltà della risposta ai passaggi forniti, la sua pertinenza rispetto alla domanda, la precisione e il recall del contesto recuperato. Distingue così gli errori della ricerca da quelli del modello. Può funzionare con un giudice locale, servito tramite Ollama, a condizione che il modello rispetti il formato di output strutturato imposto da Ragas e che il suo contesto contenga l'intera domanda, i passaggi e la risposta. Prima di adottarla, ricorda tre punti: i suoi punteggi servono a confrontare due versioni dello stesso sistema, non a valutare una qualità assoluta; il set di test conta più della libreria; e i tutorial online mescolano la vecchia e la nuova API.

Quando una risposta è errata, due cause molto diverse si nascondono dietro lo stesso sintomo: o i passaggi recuperati non contenevano l'informazione, oppure la contenevano e il modello ha risposto fuori tema. La correzione non è la stessa — suddivisione in segmenti ed embedding nel primo caso, modello e prompt nel secondo. Senza misurazioni, si corregge a caso, e un miglioramento su tre domande peggiora le risposte ad altre cinque senza che ce ne accorgiamo.

L'altro scoglio è il confronto. La domanda «Il modello da 27 miliardi di parametri è davvero migliore qui?» si risolve riproponendo lo stesso insieme di domande, non discutendone. È questo che rende possibile una valutazione riproducibile. Ragas supera le 15.000 stelle su GitHub. L'ultima versione pubblicata su PyPI è la 0.4.3, del 13 gennaio 2026, e il repository ha cambiato organizzazione su GitHub (vibrantlabsai). Fissa la versione che usi.

#Le quattro misure che contano

La documentazione di Ragas precisa che la pertinenza della risposta non ne valuta l'esattezza: misura soltanto l'adeguatezza alla domanda e penalizza le risposte incomplete o piene di dettagli inutili. Per questo non sostituisce la fedeltà. È la lettura incrociata di queste metriche a rendere utili i numeri. Un recall basso con una fedeltà elevata descrive un sistema onesto ma alimentato male: bisogna intervenire sul recupero delle informazioni. Una fedeltà bassa con un buon recall descrive il contrario: l'informazione c'era, ma il modello ha aggiunto contenuti inventati. I due problemi si correggono in punti opposti della catena.

#Costruire un set di test

È la parte che richiede lavoro e non può essere automatizzata senza conseguenze. Un insieme di dati utile contiene domande realmente poste dagli utenti, con le loro formulazioni poco curate, le loro abbreviazioni interne e i loro errori di battitura — non domande riformulate in modo accurato dalla persona che ha scritto la documentazione.

1. 01
   Partire dalle domande reali

   Da trenta a cinquanta domande tratte dall'uso reale valgono più di duecento domande inventate. Includi quelle che hanno dato esito negativo: sono le più istruttive.
2. 02
   Scrivere la risposta di riferimento

   Per ogni domanda, la risposta corretta, scritta in una o due frasi. Ragas la usa per stimare il recall del contesto: la versione basata su un LLM usa questa risposta di riferimento come sostituto dei passaggi attesi, evitando così di annotare i passaggi uno per uno.
3. 03
   Mantenere i casi senza risposta

   Domande a cui il corpus non dà risposta. Un buon sistema deve dirlo; senza questi casi, non si misura mai questa qualità.
4. 04
   Mantenere fisso il set di dati

   Non deve cambiare insieme al sistema, altrimenti non è possibile effettuare confronti nel tempo.

Ragas propone anche la generazione assistita di set di test sintetici a partire dal corpus stesso: la documentazione distingue le domande a un solo passaggio (una sola fonte) dalle domande a più passaggi (più fonti da collegare), specifiche o astratte. Una guida ufficiale mostra come adattare questa generazione a un corpus non anglofono, usando lo spagnolo come esempio, per avviare una prima valutazione prima che le vere domande degli utenti abbiano avuto il tempo di accumularsi. È un comodo punto di partenza, mai un sostituto: un set interamente sintetico non include le formulazioni maldestre e gli errori di battitura che, proprio loro, rivelano le reali debolezze di una ricerca documentale.

#Eseguire tutto in locale

Ragas si basa su due modelli per valutare: un modello giudice che legge la domanda, i passaggi e la risposta, e un modello di embedding per le misure di similarità. Il quickstart di Ragas utilizza per impostazione predefinita OpenAI, ma mostra la variante Ollama: un client compatibile con OpenAI puntato su http://localhost:11434/v1, passato alla funzione llm_factory. Solo la pertinenza della risposta richiede un modello di embedding: fedeltà, precisione e recall del contesto utilizzano solo il giudice.

Due condizioni affinché il giudice locale sia credibile. La prima è l'output strutturato: le metriche attuali richiedono al giudice decisioni intermedie in un formato prestabilito (estrazione delle affermazioni, verdetti). Un modello locale può rispondere in prosa e non rispettare questo contratto, producendo errori JSON o punteggi vuoti (NaN); una guida di OneUptime consiglia di testare il giudice con una chiamata minima prima di qualsiasi campagna. Nessuna fonte ufficiale stabilisce una dimensione minima del modello: spetta a te verificarla. La seconda è il contesto: Ollama applica per impostazione predefinita 4.000 token di contesto quando la VRAM è inferiore a 24 GiB, e la documentazione consiglia di aumentare il valore (variabile OLLAMA_CONTEXT_LENGTH) per le attività impegnative. Un giudice la cui finestra di contesto viene superata valuta in realtà un testo troncato.

• Costruire la catena RAG che valuterai
• Scegliere un modello di embedding per il francese
• Aggiungi un reranker quando la precisione del contesto è bassa
• Langfuse: tracciare e conservare i punteggi ottenuti

# pip install ragas openai
from openai import AsyncOpenAI
from ragas.llms import llm_factory
from ragas.metrics.collections import Faithfulness, ContextRecall

# Client compatible OpenAI pointé sur Ollama (la clé est un simple libellé)
client = AsyncOpenAI(api_key="ollama", base_url="http://localhost:11434/v1")
juge = llm_factory("mistral", provider="openai", client=client)  # nom du modèle tiré avec ollama pull

fidelite = Faithfulness(llm=juge)
resultat = fidelite.score(
    user_input="Où se trouve la tour Eiffel ?",
    response="La tour Eiffel se trouve à Paris.",
    retrieved_contexts=["La tour Eiffel est située à Paris, en France."],
)
print(resultat.value)  # entre 0 et 1

#Leggere i risultati senza sbagliarsi

Sono indicatori, non voti

Una fedeltà di 0,82 non significa « 82 % di risposte corrette ». Questo valore serve a confrontare due versioni dello stesso sistema, non a certificare una qualità assoluta.

Il giudice presenta dei bias

L'articolo di riferimento sui giudici LLM (arXiv 2306.05685) descrive bias di posizione, di verbosità e di auto-preferenza. Mantieni lo stesso giudice da una campagna all'altra, altrimenti le differenze misurano il giudice e non il sistema.

Una sola campagna non dimostra niente

La generazione è variabile. Su un piccolo insieme di test, una differenza di pochi centesimi può essere considerata rumore.

Leggi manualmente alcuni casi

I numeri indicano dove guardare; non dicono cosa va male. I dieci peggiori casi di una campagna insegnano di più della media generale.

#Casi d'uso concreti

Scegliere la dimensione dei segmenti

Ripetere lo stesso set di test con segmenti da 256, 512 e poi 1024 token fornisce un valore di recall per ogni configurazione, anziché una preferenza non verificata.

Validare un cambio di modello di embedding

Un nuovo modello di embedding, anche se dichiarato migliore in un benchmark generale, può peggiorare la precisione del contesto sul tuo corpus specifico; solo una campagna di valutazione locale può mostrarlo.

Giustificare l'aggiunta di un reranker

Confrontare la precisione del contesto prima e dopo il reranking quantifica un vantaggio che, altrimenti, rimane solo un'impressione condivisa in riunione.

Monitorare una regressione dopo l'aggiornamento del corpus

L'aggiunta di nuovi documenti può degradare la ricerca; ripetere il test fermo dopo ogni importazione rileva la degradazione prima che l'utente la segnali.

Scegliere tra due fornitori o architetture

Di fronte a due proposte concorrenti per costruire la stessa pipeline documentale, un punteggio ottenuto sullo stesso set di test e sullo stesso corpus permette di decidere più rapidamente di una dimostrazione commerciale.

#Organizzare le campagne

Frequenza delle campagne

Dopo ogni cambiamento di suddivisione, di modello di embedding o di modello di generazione. Non serve una campagna quotidiana su un sistema stabile.

Dimensione del corpus di test

L'insieme delle domande rimane piccolo; il corpus documentale valutato, invece, deve essere una copia realistica del corpus di produzione — oppure coincidere con esso nella sua totalità.

Costo reale di una campagna

Ogni metrica richiama il giudice più volte (per la fedeltà: estrazione delle affermazioni, poi verifica di ciascuna). Il costo aumenta quindi in proporzione al numero di domande moltiplicato per il numero di metriche: cronometra l'esecuzione di cinque domande prima di avviare tutte e cinquanta, poi pianifica la campagna di conseguenza.

#Le limitazioni del metodo

Valutare con un modello significa chiedere a un'intelligenza artificiale di giudicare un'altra intelligenza artificiale: il metodo è utile, economico e imperfetto. Rileva le regressioni e ordina le varianti; non sostituisce la revisione umana in un ambito delicato, dove un errore fattuale comporta una responsabilità. Infine, ogni campagna richiede tempo di calcolo: su una macchina che serve anche gli utenti, la si avvia quando il carico è basso, di notte o nel fine settimana anziché nelle ore di utilizzo intenso.

Il bias di verbosità merita qualche parola in più, perché è controintuitivo. Un articolo di OneUptime spiega che, in una risposta lunga, un giudice ha più occasioni di citare le parole chiave della griglia di valutazione, di apparire esaustivo e di fornire una giustificazione convincente. Un prompt che spinge il modello valutato a essere più prolisso può quindi far aumentare un punteggio senza migliorare la risposta all'utente. Per la fedeltà, la documentazione di Ragas menziona anche una variante basata su HHEM-2.1-Open, un piccolo classificatore gratuito di Vectara per il rilevamento delle allucinazioni: sostituisce la fase di verifica con un modello specializzato, da provare se il tuo giudice locale è instabile.

La soluzione più semplice è metodologica: non confrontare mai un punteggio di fedeltà ottenuto con un giudice con un punteggio ottenuto con un altro, né con un punteggio pubblicato da terzi. Il valore ha senso solo all'interno della stessa configurazione di misurazione: stesso giudice, stesso prompt di valutazione, stessa versione delle metriche. È uno strumento di confronto interno, non una classifica universale.

• Fonte: repository ufficiale Ragas su GitHub
• Fonte: bias di verbosità dei giudici automatici
• Fonte: documentazione ufficiale della metrica di fedeltà
• Fonte: quickstart Ragas, variante Ollama
• Fonte: lunghezza di contesto predefinita di Ollama
• Fonte: valutare un RAG con un giudice locale che produce JSON non valido
• Fonte: articolo di riferimento sui giudici LLM

#FAQ