> For the complete documentation index, see [llms.txt](https://rws.gitbook.io/rws/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rws.gitbook.io/rws/index-public-articles.md).

# Guia Didático do Framework Ragas: Avaliação e Métricas de RAG e Agentes

## Abstract

Este artigo é um guia didático e prático sobre o **Ragas** (v0.4 Stable), a principal referência científica em código aberto para avaliação qualitativa e quantitativa de sistemas generativos. O documento explica o paradigma de avaliação baseada em LLM (*AI-as-a-Judge*), detalha a clássica **Tríade de RAG** (Fidelidade, Relevância, Revocação e Precisão) com diagramas de fluxo, explora a nova fronteira de **Avaliação de Agentes Inteligentes** (acurácia de ferramentas e aderência a tópicos) e fornece exemplos completos e funcionais de código em Python para implementação imediata em pipelines de CI/CD.

***

## 1. O Desafio de Avaliar Sistemas Probabilísticos

No desenvolvimento de software tradicional, os testes de código são determinísticos: se uma função recebe `soma(2, 2)`, esperamos exatamente `4`. Na engenharia de IA generativa, as saídas são probabilísticas. A mesma entrada pode gerar infinitas variações de texto corretas, erradas ou, pior, alucinações extremamente convincentes.

Para resolver isso de forma escalável e evitar revisões manuais humanas exaustivas e caras, o Ragas utiliza o padrão **AI-as-a-Judge (IA como Juiz)**. Usando modelos de linguagem poderosos calibrados por prompts científicos (com suporte a Rastreabilidade e *Reasoning*), o framework destrincha o pipeline e avalia de forma quantitativa cada componente da experiência cognitiva.

***

## 2. A Tríade de RAG (v0.4 Stable)

Avaliar apenas a resposta final do usuário esconde problemas silenciosos. Por exemplo: se a resposta for ruim, a culpa foi do banco vetorial (*retriever*) que trouxe documentos irrelevantes ou do modelo de linguagem (*generator*) que ignorou os documentos certos?

O Ragas soluciona este isolamento metodológico dividindo a avaliação em três pilares principais (Tríade de RAG), gerando 4 métricas core:

```mermaid
graph TD
    subgraph "A Tríade de RAG"
        Q["Pergunta do Usuário (Query)"] -->|1 - Busca Semântica| R["Contexto Recuperado (Contexts)"]
        R -->|2 - Prompt Aumentado| G["Resposta Gerada (Answer)"]
        
        %% Métricas de Ingestão e Recuperação
        Q -.->|Context Precision & Recall| R
        
        %% Métricas de Geração
        R -.->|Faithfulness| G
        Q -.->|Answer Relevancy| G
    end

    style Q fill:#cce5ff,stroke:#004085,stroke-width:2px
    style R fill:#fff3cd,stroke:#856404,stroke-width:2px
    style G fill:#d4edda,stroke:#28a745,stroke-width:2px
```

### Detalhamento das Métricas Core:

#### A. Context Precision (Precisão do Contexto)

* **O que mede**: Os chunks de informação altamente relevantes foram colocados nas primeiras posições de busca pelo retriever?
* **Como funciona**: O Ragas avalia a ordenação semântica e atribui notas mais baixas caso a resposta certa esteja "escondida" no final de uma lista longa de chunks irrelevantes.

#### B. Context Recall (Revocação do Contexto)

* **O que mede**: A informação necessária para responder à pergunta estava de fato presente no contexto recuperado?
* **Como funciona**: O Ragas compara as alegações da resposta de referência (*reference*) contra os chunks recuperados, garantindo que o banco de dados trouxe o que era esperado.

#### C. Faithfulness (Fidelidade / Groundedness)

* **O que mede**: A resposta final gerada se baseia estritamente no contexto recuperado, ou a IA "alucinou" trazendo informações externas?
* **Como funciona**: A resposta gerada é dividida em proposições lógicas atômicas, e cada uma é checada contra o contexto. É uma métrica que não necessita de resposta de referência humana (*reference-free*).

#### D. Answer Relevancy (Relevância da Resposta)

* **O que mede**: A resposta gerada realmente responde ao que o usuário perguntou, ou ela é vaga/incompleta?
* **Como funciona**: O Ragas gera perguntas hipotéticas a partir da resposta e compara a similaridade semântica destas perguntas geradas com a pergunta original do usuário.

***

## 3. Avaliação de Agentes Inteligentes (Multi-Turn & Traces)

À medida que os sistemas evoluem de prompts simples para agentes autônomos que tomam decisões e acionam ferramentas (ex: MCP Servers ou APIs SAP), a avaliação tradicional de turno único se torna obsoleta. Avaliar agentes exige focar no **Trace de Execução (Rastro de Spans)**.

O Ragas intercepta os passos lógicos executados e avalia:

```mermaid
sequenceDiagram
    autonumber
    participant U as Usuário
    participant A as Loop do Agente
    participant T as Execução de Ferramenta
    participant R as Ragas Evaluator

    U->>A: Pergunta: "Quanto sobrou no caixa de vendas?"
    A->>T: Invoca: run_bigquery_sql()
    T-->>A: Retorna: "Saldo: $54,000"
    A->>U: Resposta: "O caixa atual é de R$ 54.000."
    
    Note over A,R: Trace de Execução capturado pelo Ragas
    R->>R: Compara ferramentas usadas contra referências esperadas (ToolCallAccuracy)
    R->>R: Analisa se o agente manteve a coerência sem desviar do assunto (TopicAdherence)
```

* **Tool Call Accuracy (Acurácia de Chamadas de Ferramenta)**: Mede a exatidão das ferramentas invocadas pelo agente em termos de ordem e parâmetros, comparando-a com uma sequência ideal.
* **Topic Adherence (Aderência ao Tópico)**: Garante que o agente permaneça no escopo da conversa e não seja desviado por *prompt injections* ou loops degenerados de raciocínio.
* **Agent Goal Accuracy (Acurácia da Meta final)**: Avalia se o agente concluiu com sucesso o objetivo principal traçado na instrução inicial.

***

## 5. Integração no Pipeline de CI/CD (Poka-Yoke)

Avaliações sistemáticas não devem ocorrer apenas em notebooks locais. A melhor prática de engenharia de software é acoplá-las em barreiras automáticas de integração contínua (CI/CD):

```mermaid
graph LR
    A[Pull Request] --> B{Executar Ragas Suite}
    B -->|Score >= 0.85| C[Aprovar PR & Deploy]
    B -->|Score < 0.85| D[Bloquear PR - Alucinação Detectada]
    
    style B fill:#fff3cd,stroke:#856404,stroke-width:2px
    style C fill:#d4edda,stroke:#28a745,stroke-width:2px
    style D fill:#f8d7da,stroke:#721c24,stroke-width:2px
```

Ao acoplar o Ragas nos testes automáticos com ferramentas como Pytest e GitHub Actions, o time garante um mecanismo robusto de **Poka-Yoke (Mistake-Proofing)**, impedindo que código que gere alucinações ou perdas de precisão em produção seja integrado no branch principal.

***

## Conexões e Links Relacionados

* **Conceito**: \[\[Systematic-Evaluation-Pipeline]]
* **Conceito**: \[\[Ragas-Agent-Performance-Evaluation]]
* **Conceito**: \[\[Poka-Yoke]]
* **Resumos**: \[\[Ragas-Framework]]
* **Resumos**: \[\[Ragas-Agent-Performance-Evaluation]]

***

\[\[Index-Public-Articles]]

***

\[\[index]]