EncouRAGe - Cheatsheet de Avaliação Local de RAG
EncouRAGe é um framework open-source para avaliar pipelines retrieval-augmented generation (RAG) com ênfase em executar localmente, rápido e confiavelmente. Onde muitos avaliadores de RAG chamam modelos juízes hospedados, EncouRAGe é projetado para computar métricas de retrieval e geração no seu próprio hardware, mantendo os dados de avaliação privados e resultados reproduzíveis. Encaixa-se no padrão 2026 onde qualidade RAG é tratada como uma propriedade de engenharia mensurável em vez de uma vibe.
Frameworks de avaliação evoluem rapidamente. Trate os comandos abaixo como a forma do fluxo de trabalho e confirme exatas flags contra os docs atuais.
Instalação
| Method | Command |
|---|
| pip | pip install encourage |
| De source | git clone o repo, depois pip install -e . |
| Modelos juízes locais | puxe modelos via seu runtime local (ex. Ollama/vLLM) |
| Verificar | python -c "import encourage; print('ok')" |
Por Que Avaliação Local
| Benefício | Por que importa |
|---|
| Privacy | Seus documentos/queries nunca saem de sua máquina |
| Reproducibility | Mesmo modelo + seed → mesmos scores |
| Cost | Sem billing por avaliação de API |
| Speed | Batch localmente sem limites de taxa |
O Que Fica Medido
Avaliação RAG divide-se nas duas metades do pipeline.
| Half | Métricas |
|---|
| Retrieval | Precisão de contexto, context recall, hit rate, MRR/NDCG |
| Generation | Faithfulness (grounding), answer relevance, correctness |
| End-to-end | Se a resposta final está correta e é apoiada |
Fluxo de Trabalho Principais
# Fluxo conceitual: monte um dataset, rode seu RAG, pontue-o
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", # roda localmente
)
print(results.summary()) # scores por métrica
results.to_json("eval.json")
| Step | Propósito |
|---|
| Dataset | Questões + (opcional) ground truth + contextos recuperados |
| Metrics | Quais dimensões de retrieval/geração pontuar |
| Judge model | O LLM local usado para métricas LLM-as-judge |
| Results | Scores agregados + por-exemplo, exportável |
Construindo um Dataset de Avaliação
| Field | Significado |
|---|
question | A query do usuário |
contexts | Chunks seu retriever retornou |
answer | Resposta gerada pelo seu pipeline |
ground_truth | Resposta de referência (para correctness/recall) |
Colha questões reais de traços de produção para tornar a avaliação representativa.
Interpretando Resultados
| Sintoma | Provável causa |
|---|
| Context recall baixa | Retriever perde chunks relevantes (chunking/embedding) |
| Context precision baixa | Contexto irrelevante demais recuperado (adicione reranking) |
| Faithfulness baixa | Modelo alucina além do contexto |
| Answer relevance baixa | Resposta desvia da questão (prompt/query issue) |
Encaixando Numa CI
# Gate uma mudança RAG em scores de avaliação
python run_eval.py --dataset eval.jsonl --min-faithfulness 0.85 \
--min-context-recall 0.8 || exit 1
Execute o mesmo conjunto eval em toda mudança retrieval/prompt/modelo para que regressões sejam apanhadas antes de enviar.
EncouRAGe vs Outros Avaliadores RAG
| Aspecto | EncouRAGe | RAGAS | TruLens | DeepEval |
|---|
| Ênfase | Local, rápido, reproduzível | Métricas RAG sem referência | Monitoramento + OTel tracing | Mentalidade unit-test, CI |
| Judge | Modelos locais | Configurável | Configurável | Configurável |
| Melhor para | Avaliação privada, on-prem | Scoring rápido de RAG | Monitoramento de produção | Gates CI estilo pytest |
Pares conceitualmente com RAGAS, TruLens e DeepEval — escolha se você precisa de privacidade local, métricas rápidas, monitoramento ou gates CI.
Recursos
