EncouRAGe - Cheatsheet Local RAG Evaluation
EncouRAGe è un framework open-source per valutare retrieval-augmented generation (RAG) pipeline con un”enfasi su esecuzione localmente, velocemente, e affidabilmente. Dove molti RAG evaluator chiamano fuori verso hosted judge models, EncouRAGe è progettato per calcolare metriche di retrieval e generation sul tuo hardware, mantenendo i dati di valutazione privati e i risultati riproduttibili. Si adatta al pattern 2026 dove la qualità RAG è trattata come una proprietà engineering misurabile piuttosto che un vibe.
I framework di valutazione evolvono velocemente. Tratta i comandi sotto come la forma del workflow e conferma i flag esatti contro la documentazione attuale.
Installazione
| Metodo | Comando |
|---|
| pip | pip install encourage |
| From source | git clone il repo, poi pip install -e . |
| Local judge models | tira model via il tuo runtime locale (e.g. Ollama/vLLM) |
| Verifica | python -c "import encourage; print(''ok'')" |
Perché Valutazione Locale
| Beneficio | Perché importa |
|---|
| Privacy | I tuoi documenti/query non lasciano mai la tua macchina |
| Reproducibility | Stesso modello + seed → stessi scores |
| Cost | Nessuna per-eval API billing |
| Speed | Batch localmente senza rate limits |
Cosa Viene Misurato
La valutazione RAG si divide nelle due metà della pipeline.
| Metà | Metriche |
|---|
| Retrieval | Context precision, context recall, hit rate, MRR/NDCG |
| Generation | Faithfulness (grounding), answer relevance, correctness |
| End-to-end | Se la risposta finale è giusta e supportata |
Workflow Principale
# Flusso concettuale: assembla un dataset, esegui il tuo RAG, segnalo
import encourage
dataset = encourage.load_dataset("eval_questions.jsonl") # question, ground_truth, contexts
results = encourage.evaluate(
dataset=dataset,
metrics=["faithfulness", "answer_relevance",
"context_precision", "context_recall"],
judge_model="local/llama-3.1-8b-instruct", # esegue localmente
)
print(results.summary()) # per-metric scores
results.to_json("eval.json")
| Passo | Scopo |
|---|
| Dataset | Domande + (opzionale) ground truth + retrieved contexts |
| Metrics | Quali dimensioni di retrieval/generation segnare |
| Judge model | L”LLM locale usato per LLM-as-judge metrics |
| Results | Aggregate + per-example scores, esportabili |
Costruire un Dataset di Eval
| Field | Significato |
|---|
question | La query dell”utente |
contexts | Chunk che il tuo retriever ha ritornato |
answer | La risposta generata dalla tua pipeline |
ground_truth | Risposta di riferimento (per correctness/recall) |
Raccogli domande vere da tracce di produzione per rendere l”eval rappresentativo.
Interpretare i Risultati
| Sintomo | Probabile causa |
|---|
| Low context recall | Il retriever manca chunk rilevanti (chunking/embedding) |
| Low context precision | Troppo contesto irrilevante recuperato (aggiungi reranking) |
| Low faithfulness | Il modello allucinisce oltre il contesto |
| Low answer relevance | La risposta diverge dalla domanda (prompt/query issue) |
Montare in CI
# Gate il cambio RAG su score di valutazione
python run_eval.py --dataset eval.jsonl --min-faithfulness 0.85 \
--min-context-recall 0.8 || exit 1
Esegui lo stesso set eval su ogni retrieval/prompt/model change così le regressioni sono catturate prima che shippino.
EncouRAGe vs Altri RAG Evaluator
| Aspetto | EncouRAGe | RAGAS | TruLens | DeepEval |
|---|
| Emphasis | Local, fast, reproducible | Reference-free RAG metrics | Monitoring + OTel tracing | Unit-test mindset, CI |
| Judge | Local models | Configurable | Configurable | Configurable |
| Best for | Private, on-prem eval | Quick RAG scoring | Production monitoring | Pytest-style CI gates |
Pair concettualmente con RAGAS, TruLens, e DeepEval — scegli se hai bisogno di privacy locale, metriche veloci, monitoring, o gating CI.
Risorse
