Este texto fecha o assunto: como medir o sistema. Os temas anteriores montam o sistema peça por peça: como o modelo lê texto, como um texto vira vetor, como achar vizinhos, onde guardar, como cortar e ingerir documentos, como combinar busca por palavras e por significado, como reordenar candidatos e como costurar tudo num pipeline. Falta a pergunta que todo projeto enfrenta quando vai para a frente de usuários reais: como saber se o seu RAG está bom, e se uma mudança melhorou ou piorou o resultado?

Todos os números deste texto saem do mesmo laboratório de Reranking e RAG: os 9 documentos do Mercado Aurora cortados em 112 pedaços de até 60 tokens, as 56 perguntas com resposta marcada e as 14 perguntas sem resposta no acervo. Por isso a tabela de estágios da seção 4 reproduz, linha a linha, a de RAG, e você pode conferir. A metade do RAG que depende de um modelo de linguagem (a geração) eu não consegui medir, porque não havia um modelo rodando aqui, e o texto diz isso onde importa. O que ela ensina para essa metade é o método: o que medir, como escrever o juiz, como calibrá-lo e quantas perguntas são necessárias para acreditar no resultado.

Mapa da aula

Pré-requisitos: RAG, Reranking, Busca híbrida e Chunking. Os diagramas seguem um mapa de cores fixo: laranja é o que a pessoa controla (perguntas e conjuntos de teste), azul são vetores, índices e decisões, verde são pedaços e resultados bons, lima é a busca por palavras, verde limão é o reranker, terracota é o modelo de linguagem que gera a resposta, índigo é quem mede (as métricas e o juiz) e rosa é o que dá errado, custa caro ou regride.

Parte 1: O problema e o conjunto de avaliação

1. A ilusão do teste de cinco perguntas e os três pontos de medição

Quem monta um RAG pela primeira vez costuma abrir o chat, fazer uma pergunta fácil sobre a documentação, ler uma resposta elegante, fazer mais quatro de cabeça e concluir que funciona. Na semana seguinte vinte pessoas começam a usar a ferramenta e chegam as reclamações: o modelo inventou um preço, confundiu duas regras de devolução, respondeu com generalidades.

Cinco perguntas enganam por três motivos. Quem desenvolveu o sistema escolhe, sem perceber, perguntas parecidas com o texto dos documentos, e isso favorece a busca. Cinco perguntas também não cobrem os casos de borda, como siglas, perguntas cuja resposta está numa linha de tabela e, principalmente, perguntas que o acervo não responde. E o ruído de uma amostra pequena é enorme: acertar 4 de 5 parece 80%, mas cada pergunta vale 20 pontos, então uma só decide a nota.

O erro mais caro, porém, é tratar o RAG como caixa preta e olhar só o par pergunta e resposta. O RAG tem duas metades que falham de jeitos diferentes: a recuperação, que é rápida, determinística e barata de medir, e a geração, que é estocástica, lenta e cobra por token. Quando a resposta final está errada, a causa pode estar em três lugares distintos do pipeline.

A figura divide o sistema nas duas metades e marca os três pontos de medição. Na recuperação, o ponto 1 olha os 20 candidatos que a busca híbrida entregou: se o pedaço com a resposta não está ali, nada depois consegue salvá-lo. O ponto 2 olha os 5 pedaços que sobraram depois do reranker e do corte em k, que são os que de fato entram no prompt. Na geração, o ponto 3 olha a resposta final e pergunta se o modelo foi fiel aos pedaços que recebeu.

Separar os pontos transforma “a resposta está errada” em um diagnóstico. Se o ponto 1 falhou, o problema está no corte dos documentos, na indexação ou no embedding. Se o ponto 1 passou e o 2 falhou, a culpa é do reranker, do tamanho de k ou do limiar de corte. Se os dois passaram e o 3 falhou, o problema está no prompt ou no modelo. Medir só a resposta final é consertar um carro que não anda olhando o velocímetro.

2. O conjunto de avaliação

O conjunto de avaliação, que muita gente chama de golden set ou conjunto-ouro, é a régua fixa contra a qual toda mudança é medida antes de chegar perto dos usuários. Cada item guarda a pergunta escrita no vocabulário real de quem pergunta, o pedaço-ouro (o identificador ou a frase exata do documento que contém a resposta), uma resposta de referência curta quando a geração também será avaliada, e metadados de categoria e de documento de origem.

A figura mostra a anatomia de um item no alto e, embaixo, as categorias do laboratório. Elas importam porque uma média sobre perguntas de natureza diferente esconde onde o sistema falha, como a seção 12 vai mostrar. No laboratório, as 56 perguntas com resposta ficaram assim, e atribuí as categorias por regra, não por palpite. São 8 perguntas de tabela, em que a frase-ouro é uma linha de tabela (os prazos por região e os planos de suporte). São 6 perguntas técnicas, que dependem de sigla, token, limite ou cabeçalho (a prioridade P1, o prazo do token da API, o cabeçalho de assinatura dos avisos). São 24 de paráfrase, em que a pergunta tem no máximo uma palavra de conteúdo em comum com a frase-ouro. As outras 18 são fatos em prosa. A elas somam-se as 14 perguntas sem resposta no acervo, que testam se o sistema sabe recusar.

O conjunto do laboratório tem uma lacuna que vale registrar: nenhuma pergunta exige juntar dois pedaços. Um conjunto de avaliação de verdade deve ter uma categoria para isso, porque é onde os valores baixos de k e os cortes ruins doem. Eu não a inventei só para completar a lista.

De onde vêm as perguntas? A melhor fonte são os registros de perguntas reais de usuários ou do suporte humano, com a resposta marcada por quem conhece o negócio. Sem histórico, uma saída é pedir a um modelo que gere perguntas a partir dos documentos e passar tudo por revisão humana, para cortar o que ficou artificial. Há uma regra contra contaminação: o conjunto de avaliação não pode ser usado para ajustar o sistema. Se você escolhe o chunker, os pesos da fusão e o prompt olhando as mesmas perguntas que decidem o deploy, está ensinando o sistema a decorar a prova. Guarde um conjunto menor para explorar no dia a dia e deixe o conjunto de avaliação intocado.

Quantas perguntas bastam? A seção 9 faz a conta. Para ver diferenças de poucos pontos entre duas versões, a resposta honesta é que costumam ser centenas, não dezenas.

Parte 2: Métricas da recuperação

3. As métricas da recuperação

O recuperador recebe uma pergunta e devolve uma lista ordenada de pedaços. As métricas descrevem duas propriedades dessa lista: se o pedaço certo está nela e em que posição.

O recall@k é a fração dos pedaços relevantes que entraram entre os k primeiros. Se a resposta exige dois pedaços e os dois estão no top 5, o recall@5 é 1,0; se só um está, é 0,5. Quando cada pergunta tem um único pedaço-ouro, como no laboratório, o recall@k vira uma decisão de sim ou não por pergunta, e a média dessas decisões se chama hit@k. Um hit@5 de 0,95 diz que em 95% das perguntas o pedaço certo estava entre os 5 primeiros. É a métrica que protege o sistema: o pedaço que não foi recuperado não pode ser lido pelo modelo.

A precision@k é a fração dos k pedaços devolvidos que são relevantes. Com 5 pedaços devolvidos e um só relevante, é 0,20. Uma precisão baixa significa um prompt cheio de texto inútil, mais caro e mais fácil de distrair o modelo.

O hit@k não vê a posição, mas ela importa, porque os modelos dão mais peso ao começo do contexto (Reranking mostrou isso). O MRR, média do inverso da posição do primeiro acerto, resolve: 1 se o pedaço certo é o primeiro, 0,5 se é o segundo, 0,25 se é o quarto, 0 se ficou fora da lista. O nDCG é a versão que aceita níveis de relevância (por exemplo 2, 1 e 0) e desconta com um logaritmo os acertos que caem para o fim; em RAG com pedaço-ouro binário o MRR e o hit@k são mais fáceis de ler, e eu não usei o nDCG no laboratório.

A biblioteca Ragas dá nomes próprios a duas dessas ideias. Pela documentação que li, a Context Precision é a média da precisão@k calculada nas posições dos pedaços relevantes, de modo que pedaços relevantes perto do topo rendem mais. A Context Recall tem uma versão com modelo, que quebra a resposta de referência em afirmações e confere quantas são sustentadas pelo contexto recuperado, e versões sem modelo, que comparam os pedaços recuperados com os pedaços de referência por texto ou por identificador. Quando o gabarito é um identificador de pedaço, como o do laboratório, a variante de recall por identificador faz a conta do recall@k, e a de precisão por identificador, pela descrição que li, é a fração dos identificadores recuperados que estão no gabarito, ou seja, a precision@k.

hit@k  = média por pergunta de  [o ouro está entre os k primeiros]
RR     = 1 / posição do primeiro acerto  (0 se fora do top k)
MRR    = média do RR sobre as perguntas
ctx_precision = média, nas posições i dos acertos, de  (acertos até i) / i

A figura aplica as fórmulas a uma lista de 5 pedaços em que os pedaços da posição 2 e da posição 4 contêm a resposta. O hit@1 é 0, porque o primeiro lugar errou, e o hit@5 é 1. O RR é 1 ÷ 2 = 0,50, fixado pelo primeiro acerto. O recall@5 é 2 ÷ 2 = 1,0 e a precision@5 é 2 ÷ 5 = 0,40. A context precision soma a precisão em cada acerto, 1/2 no segundo lugar e 2/4 no quarto, e tira a média: (0,50 + 0,50) ÷ 2 = 0,50.

Uma consequência prática: com um único pedaço relevante por pergunta, a média das precisões nos acertos é só 1/posição, e a context precision vira o próprio MRR. Medir as duas e relatar os dois números como se fossem independentes não acrescenta informação.

4. A linha de base medida no laboratório

O pipeline é o de RAG, sem mudança. A busca por palavras (BM25, k1 = 1,5, b = 0,75) e a busca vetorial (multilingual-e5-small) trazem 20 candidatos cada, o RRF com k = 60 os funde em 20, o cross-encoder mmarco-mMiniLMv2 reordena esses 20 lendo o texto com o prefixo de documento e seção, e os 5 primeiros vão para o prompt. Uma pergunta acerta quando o pedaço contém a frase-ouro inteira. Este é o trecho que calcula as métricas, escrito sobre os resultados de cada estágio:

def hit(ac, k): return [any(a[:k]) for a in ac]               # ac[i] = lista de True/False por posição
def rr(ac):     return [next((1/(r+1) for r, x in enumerate(a) if x), 0.0) for a in ac]

for nome, ac in estagios.items():
    print(nome, np.mean(hit(ac, 1)), np.mean(hit(ac, 3)), np.mean(hit(ac, 5)),
          np.mean(hit(ac, 20)), np.mean(rr(ac)))

112 pedaços; 56 perguntas com resposta; 14 sem resposta
estágio           hit@1  hit@3  hit@5  hit@20    MRR
bm25               0.50   0.77   0.84    0.96   0.64
vetor              0.80   0.96   0.98    1.00   0.88
híbrido            0.77   0.93   0.95    1.00   0.86
híbrido+rerank     0.89   0.96   0.98    1.00   0.93

Os valores batem com os de RAG. Lendo por ponto de medição, o ponto 1 é um sucesso neste corpus: o pedaço certo estava entre os 20 candidatos em 56 das 56 perguntas. O ponto 2 perdeu uma: em 55 das 56 perguntas o ouro ficou entre os 5 do prompt. A única que caiu foi a da linha da tabela de suporte sobre o plano Business, que o reranker mandou para a 14ª posição.

Duas leituras que a tabela pede. Primeiro, o reranker ajuda, mas o vetor sozinho já era forte: o híbrido ficou até um pouco abaixo do vetor no hit@1 (0,77 contra 0,80), e a seção 10 mostra que essa diferença é ruído. O que o reranker acrescenta de fato está na categoria de paráfrase e na de tabela, não na média. Segundo, o 100% do hit@20 é generoso porque 20 candidatos são 18% do acervo de 112 pedaços. Num acervo de milhares de pedaços, o mesmo N seria uma fração minúscula, e o ponto 1 passaria a ser o gargalo.

Imprimir um relatório por pergunta é o que torna o diagnóstico acionável. Estas são as perguntas em que o ouro não ficou em primeiro lugar em pelo menos um dos dois estágios (15 de 56):

  # doc         híbrido  +rerank  nota do topo  pergunta
  5 trocas            7        1       -2.71  Posso devolver uma meia que não gostei?
  7 trocas            2        1        2.94  Quanto custa a garantia estendida?
  9 entregas          2        1        0.54  Quanto demora a entrega padrão para o Norte?
 13 entregas          1        2       -1.95  O que ganho se meu pedido atrasar muito?
 24 pagamentos        4        1        0.25  Em que dia o boleto deixa de valer?
 25 conta             2        1        9.60  Quanto tempo vale o link para redefinir a senha?
 35 fidelidade        2        2       -3.13  Quantos pontos preciso para chegar ao nível mais alto?
 36 prime             2        1        2.23  Quanto custa o Prime por ano?
 38 prime             2        1       -3.86  Se eu cancelar a assinatura logo depois de pagar, recebo o dinheiro de volta?
 39 prime             2        1       -2.10  Quantas pessoas da família posso incluir na assinatura?
 45 entregas          2        2       -0.42  Para o Sudeste, a entrega padrão chega em quanto tempo?
 46 suporte           3        1       -3.06  Quanto tempo leva para resolver um problema no plano Pro?
 47 suporte          13        5        1.47  O plano gratuito de suporte tem qual prazo de primeira resposta?
 48 suporte           6       14       -0.26  Em quanto tempo o plano Business responde pela primeira vez?
 55 api               1        2       -2.04  Como confirmar que um aviso de evento é autêntico?

As colunas do meio dão a posição do ouro depois de cada estágio. Quase todas as linhas melhoram com o reranker (as perguntas 5, 7, 9, 24, 25, 36, 38, 39 e 46 passaram a primeiro lugar). Duas pioraram, a 13 e a 55, e a seção 12 olha as duas de perto.

Parte 3: Métricas da geração

5. Fidelidade, relevância e correção

Depois que os pedaços entram no prompt, o problema muda de natureza. Em vez de listas de identificadores, há texto em linguagem natural escrito por um modelo, e a avaliação dessa parte costuma combinar três dimensões.

A fidelidade ao contexto (faithfulness ou groundedness) mede se tudo o que a resposta afirma é sustentado pelos pedaços recebidos. A documentação do Ragas descreve a conta assim: identifica-se cada afirmação da resposta, confere-se se ela pode ser inferida do contexto recuperado e divide-se o número de afirmações sustentadas pelo total. A própria documentação dá um exemplo com duas afirmações em que só uma é sustentada, e a nota é 0,5. O FaithfulnessMetric do DeepEval, pela página que li, usa a mesma definição: afirmações verdadeiras divididas pelo total, extraídas e conferidas por um modelo juiz. E o TruLens chama de groundedness a verificação em que a resposta é quebrada em afirmações e cada uma é procurada nas evidências do contexto.

A relevância da resposta mede se o texto atende ao que foi perguntado. Uma resposta pode ser perfeitamente fiel e inútil: ao ouvir “qual o prazo para trocar uma geladeira com defeito?”, responder que o Mercado Aurora tem centro de distribuição próprio é dizer uma verdade documentada que não responde a nada. A relevância penaliza evasivas, rodeios e respostas fora de tópico.

A correção contra a referência compara a resposta gerada com a resposta de referência do conjunto de avaliação. É a checagem de ponta a ponta, e é a que mais depende do juiz estar bem calibrado, porque dois textos podem dizer a mesma coisa com palavras diferentes.

6. Auditoria de citações e recusa

Em RAG corporativo o modelo costuma ser instruído a marcar cada afirmação com o índice do pedaço que a sustenta, como [1] (RAG monta esse prompt). A citação só vale se for conferida, porque o modelo erra de três jeitos. Pode citar um índice que não existe, como [7] num prompt com 5 pedaços. Pode citar um pedaço que fala de outro assunto. Ou pode citar o pedaço certo, e esse é o único caso bom. As duas primeiras falhas são verificáveis até sem modelo: o índice existe? O texto citado sustenta a afirmação? A segunda pergunta já pede julgamento, e é aí que o juiz entra.

A figura mostra uma resposta dividida em duas afirmações. A primeira cita o pedaço 1, que fala do frete na troca por cor ou tamanho, e a afirmação é sustentada (pacote verde). A segunda promete um motoboy gratuito em 2 horas e cita o pedaço 2, que só fala de frete grátis acima de um valor: a citação existe, mas o pedaço não diz aquilo (pacote rosa). O avaliador marca a afirmação como infiel e a citação como falsa. As duas notas saem diferentes, 1 de 2 afirmações sustentadas (0,50) e uma citação válida em duas. Os pedaços e a resposta da figura são um exemplo que escrevi para mostrar o mecanismo; nenhum modelo gerou essa resposta.

O comportamento de recusa é a outra metade. O prompt de RAG manda o modelo responder “Não encontrei isso nos documentos.” quando o contexto não traz a resposta, e há uma barreira anterior, o limiar de nota do reranker, que corta a pergunta antes de gastar uma chamada ao modelo. A barreira dá para medir sem modelo, e a seção 13 faz isso. A recusa que depende do modelo (ele obedece à instrução ou inventa?) eu não medi.

Parte 4: O modelo como juiz

7. Como escrever o prompt do juiz

Ler centenas de respostas à mão não cabe na rotina de um time, então a prática comum é usar um modelo de linguagem como juiz: ele lê a pergunta, o contexto e a resposta e dá uma nota justificada. Pedir só “avalie de 1 a 5” produz notas imprevisíveis e infladas. Funcionam melhor três cuidados. A rubrica descreve cada nota com critérios observáveis, sem palavras como “razoável”. A escala é curta e discreta, de preferência aprovado ou reprovado, ou três a cinco níveis ancorados, porque escalas de 1 a 10 aumentam a inconsistência entre execuções. E o raciocínio vem antes da nota: o modelo extrai as afirmações e justifica cada uma antes de emitir o valor final, o que amarra a nota ao que ele de fato conferiu.

Este é o prompt de fidelidade que eu usaria. Escrevi, mas não o executei, porque não havia modelo para rodá-lo.

Você é um auditor de precisão factual. Sua função é avaliar se uma RESPOSTA é
sustentada pelo CONTEXTO fornecido.

INSTRUÇÕES:
1. Isole cada afirmação factual da RESPOSTA.
2. Para cada afirmação, verifique se o CONTEXTO a confirma diretamente.
3. Não use conhecimento seu sobre o mundo. O que não está no CONTEXTO é
   NÃO SUSTENTADO, mesmo que seja verdade.
4. Responda apenas no formato JSON indicado.

RUBRICA:
- 1.0: todas as afirmações são confirmadas pelo contexto.
- 0.5: a resposta mistura afirmações confirmadas com detalhes que o contexto não traz.
- 0.0: a resposta contradiz o contexto ou inventa fatos.

CONTEXTO: """{contexto}"""
PERGUNTA: """{pergunta}"""
RESPOSTA: """{resposta}"""

{"afirmacoes": [{"texto": "...", "sustentada": true, "trecho": "..."}],
 "justificativa": "...", "nota": 1.0}

Outra forma é o juiz por pares: em vez de dar nota a um texto isolado, o juiz recebe duas respostas (por exemplo a do chunker novo e a do antigo) e escolhe a melhor. Costuma concordar mais com pessoas em clareza e utilidade, mas cada par precisa ser avaliado duas vezes, com a ordem trocada, para neutralizar o viés de posição que a próxima seção descreve.

8. Vieses e calibração contra pessoas

Um juiz que ninguém testou só muda a ilusão de lugar. O artigo que popularizou a técnica (Zheng e colegas, MT-Bench e Chatbot Arena) nomeia três vieses nos modelos juízes: o de posição (preferir a primeira resposta), o de verbosidade (preferir a mais longa) e o de autopreferência (preferir o texto de um modelo da própria família), além da limitação de raciocínio em questões que exigem conta. O mesmo resumo reporta que juízes fortes chegam a mais de 80% de concordância com preferências humanas, o nível de concordância que pessoas têm entre si. Esse resultado vem dos benchmarks do próprio artigo e não garante a mesma concordância no seu acervo: o seu juiz precisa provar o próprio valor.

A figura mostra o protocolo: uma amostra de casos é rotulada por um especialista e pelo juiz, e se mede a concordância. A concordância percentual simples engana quando uma classe domina, porque um juiz que sempre aprova concorda bastante com qualquer conjunto em que a maioria é boa. O kappa de Cohen desconta a concordância esperada ao acaso:

kappa = (Po - Pe) / (1 - Pe)
Po = proporção de casos em que humano e juiz concordam
Pe = concordância esperada se cada um sorteasse segundo as suas próprias proporções

O exemplo da figura é didático, com números que inventei só para mostrar a conta: em 50 casos, os dois aprovaram 28, os dois reprovaram 16, o juiz aprovou e a pessoa reprovou 3, e o juiz reprovou e a pessoa aprovou 3. A concordância observada é 44 ÷ 50 = 0,88. Como cada um aprova 31 dos 50 casos, a concordância esperada ao acaso é 0,62 × 0,62 + 0,38 × 0,38 = 0,529, e o kappa é (0,88 − 0,529) ÷ (1 − 0,529) = 0,745. Pelas faixas usuais, algo acima de 0,6 já é uma concordância substancial, e abaixo de 0,4 é fraca (são faixas de convenção, que não verifiquei numa fonte). Um juiz que não atinge o nível que você definiu contra rótulos humanos não deve alimentar decisão nenhuma, e o tamanho da amostra de calibração também conta: com 50 casos o kappa tem uma incerteza grande, e vale rotular mais antes de comemorar.

O projeto ARES, descrito no resumo do artigo, ataca o mesmo problema por outro caminho: gera dados sintéticos para treinar juízes leves e corrige os erros deles com inferência apoiada em previsões (PPI), usando só algumas centenas de anotações humanas.

Parte 5: Estatística honesta

9. O tamanho da amostra e o ruído de medição

Comemorar variações pequenas como se fossem vitórias é um dos erros mais comuns. A equipe muda o prompt, roda 50 perguntas, vê o acerto subir de 82% para 84% (uma pergunta a mais) e conclui que o novo prompt é melhor. Uma amostra finita tem incerteza própria: pela aproximação binomial, o desvio padrão de uma proporção p medida em N perguntas é a raiz de p(1 − p) ÷ N.

N = 56, p = 0,90:  desvio = 4,0 pontos  ->  margem de 95% de uns ±8 pontos
N = 56, p = 0,50:  desvio = 6,7 pontos  ->  margem de 95% de uns ±13 pontos

Com 56 perguntas, então, duas versões medidas em separado só se distinguem se diferirem por mais de 8 a 13 pontos. É a margem que o laboratório usou. O teste pareado, que a seção 10 apresenta, enxerga diferenças menores, mas tem um limite: só conta as perguntas em que as duas versões discordam. Simulei quantas perguntas fazem falta para que o teste do sinal exato detecte um ganho com 80% de chance, dado o ganho líquido e a fração de perguntas que mudam de resultado entre as duas versões:

ganho líquido  perguntas que mudam   perguntas necessárias   poder com 56 perguntas
 3 pontos            10%                   ~1.200                    3%
 5 pontos            10%                    ~400                     9%
 5 pontos            20%                    ~800                     8%
10 pontos            20%                    ~200                    28%

O que a tabela diz de útil: com 56 perguntas, o laboratório só tem chance razoável de enxergar ganhos grandes e só em parte dos casos (28% de poder para 10 pontos de ganho). Para distinguir ganhos de 3 a 5 pontos, o conjunto precisa de centenas ou milhares de perguntas. Essa é a razão prática para a regra da seção 2: o conjunto de avaliação deve crescer com o tempo, alimentado pelo que a produção revela.

10. Bootstrap pareado e teste do sinal

Em um teste pareado, compara-se o sistema A e o sistema B na mesma pergunta, e só as perguntas em que eles discordam carregam informação. O teste do sinal exato conta quantas vezes B ganhou e quantas perdeu entre essas e pergunta qual é a chance de um placar tão desigual vir do acaso se os dois fossem equivalentes. O bootstrap pareado reamostra as perguntas com reposição, milhares de vezes, e mostra o intervalo em que cai 95% da diferença. Este é o código, nas duas versões:

def sinal(a, b):                       # a e b: acertou/errou por pergunta
    g = sum((not x) and y for x, y in zip(a, b)); p = sum(x and (not y) for x, y in zip(a, b)); m = g + p
    pv = min(1.0, 2 * sum(math.comb(m, t) for t in range(0, min(g, p) + 1)) / 2 ** m) if m else 1.0
    return g, p, pv

def boot(a, b, B=10000, seed=7):
    rng = np.random.default_rng(seed); d = np.array(b, float) - np.array(a, float)
    medias = d[rng.integers(0, len(d), (B, len(d)))].mean(axis=1)
    return d.mean(), np.percentile(medias, 2.5), np.percentile(medias, 97.5)

Comparei quatro pares de estágios no hit@1 e, em separado, k = 3 contra k = 5:

== 2. comparações pareadas (hit@1)
híbrido+rerank menos híbrido: +0.125 (IC95% [+0.018, +0.232])  ganhas 9, perdidas 2, sinal p=0.065
híbrido+rerank menos vetor:   +0.089 (IC95% [-0.036, +0.214])  ganhas 9, perdidas 4, sinal p=0.267
híbrido+rerank menos bm25:    +0.393 (IC95% [+0.250, +0.536])  ganhas 23, perdidas 1, sinal p=0.000
híbrido menos vetor:          -0.036 (IC95% [-0.143, +0.071])  ganhas 4, perdidas 6, sinal p=0.754

== 3. k=3 contra k=5 no prompt
k=5 menos k=3: +0.018 (IC95% [+0.000, +0.054]) ganhas 1, perdidas 0, sinal p=1.000; empates 55

A figura organiza três desfechos que os números mostram. No primeiro, k = 5 contra k = 3: das 56 perguntas, 55 empataram e uma foi ganha por k = 5. O ganho é de 1,8 ponto, o intervalo toca o zero e o teste do sinal dá p = 1. Subir k de 3 para 5 aumenta os tokens de pedaços no prompt em 65% (de 146 para 241, em média) para ganhar uma pergunta, e a evidência não sustenta que o custo se paga. O terceiro desfecho é o oposto: reranker contra BM25 puro tem 23 vitórias e 1 derrota, o intervalo de 95% vai de +25 a +54 pontos e o teste do sinal é praticamente zero. Esse efeito é real e grande.

O desfecho do meio é o que mais ensina, e é o que acontece com a decisão que a maioria dos times enfrenta: o reranker sobre o híbrido. Ele ganhou 12,5 pontos de hit@1, com 9 vitórias e 2 derrotas. O intervalo do bootstrap vai de +1,8 a +23,2 e não inclui o zero, mas o teste do sinal exato dá p = 0,065, acima de 0,05. Os dois métodos olham os mesmos 11 casos em que o resultado mudou e discordam por pouco, o que é normal com tão poucas perguntas discordantes. A leitura honesta é “provável, não demonstrado”: a evidência favorece o reranker, e o conjunto atual não basta para encerrar a discussão. Contra o vetor sozinho a diferença ainda é menor (+8,9 pontos, 9 contra 4, intervalo cruzando o zero), e isso importa, porque um time que mede o reranker só contra o híbrido pode estar comparando com o adversário errado.

Há ainda uma conta de múltiplas comparações. Rodei quatro comparações de hit@1 neste conjunto; quando se roda um punhado de testes, é esperado que algum resultado apareça perto de 5% por acaso. Por isso relatei os quatro.

Parte 6: Diagnóstico e prevenção de regressão

11. O diagnóstico em camadas

Quando uma pergunta falha no conjunto de avaliação, o diagnóstico em camadas é o procedimento que localiza o culpado sem tentativa e erro. Ele faz três perguntas em sequência sobre o rastro da pergunta.

A primeira pergunta é se o pedaço-ouro estava entre os candidatos. Se não estava, a falha é da camada 1, e o conserto está no corte dos documentos, na indexação ou no embedding. Mexer no prompt ou trocar o modelo de linguagem não ajuda enquanto a busca não trouxer o pedaço. A segunda pergunta é se o ouro entrou nos k pedaços do prompt. Se não entrou, a falha é da camada 2: o reranker rebaixou o pedaço certo, o k é pequeno ou o limiar barrou a pergunta cedo demais. A terceira é se o modelo usou o pedaço que recebeu. Se não usou, a falha é da camada 3, e o conserto está nas instruções do prompt, na exigência de citações ou na escolha de um modelo mais capaz.

No laboratório, as camadas 1 e 2 deram resultado completo. A camada 1 falhou em 0 das 56 perguntas. A camada 2 falhou em 1, a da tabela de suporte do plano Business, e é uma falha de reranker: o ouro estava em sexto lugar no híbrido e o cross-encoder o jogou para a posição 14. A camada 3 eu não medi, porque não havia modelo gerando respostas, e prefiro deixar isso explícito a preencher a coluna com um número inventado. O relatório por pergunta da seção 4 é o que permite catalogar, para cada falha, a camada responsável.

12. Regressão mascarada pela média

A nota média é a maior aliada das decisões erradas. Um ganho grande na categoria mais numerosa pode esconder uma piora numa categoria pequena e importante, e só o recorte por categoria mostra isso. No laboratório, o hit@1 do híbrido sem reranker contra o híbrido com reranker, por categoria, ficou assim:

categoria       n  híbrido  +rerank    dif  ganhas/perdidas
fato em prosa  18     0.94     0.94  +0.00  0/0
tabela          8     0.38     0.62  +0.25  2/0
paráfrase      24     0.71     0.96  +0.25  7/1
técnica         6     1.00     0.83  -0.17  0/1

A figura mostra a média à esquerda, que sobe de 0,77 para 0,89, e as categorias no meio. O reranker ajuda muito em paráfrase (7 vitórias e 1 derrota) e em tabela (2 e 0), e não muda nada em fato em prosa. Na categoria técnica ele fez o contrário: 1,00 para 0,83. É o caso que a seção promete mostrar, e é preciso ler os números por inteiro. A categoria técnica tem 6 perguntas, e a queda de 17 pontos é uma pergunta: a que pede como confirmar a autenticidade de um aviso de evento, cuja resposta é o cabeçalho X-Aurora-Assinatura. O híbrido a colocava em primeiro, e o reranker preferiu um trecho de abertura da documentação da API (nota −2,04) e deixou o ouro em segundo. Um resultado assim é um alerta, não um veredito: uma pergunta em seis não permite afirmar que o reranker prejudica consultas técnicas. Também não permite descartar a hipótese, que é plausível, porque um modelo treinado em texto corrido pode subestimar cabeçalhos e siglas, como Reranking observou nas tabelas.

A conduta que sai disso tem duas partes. Primeiro, monitorar por categoria, com a regra de que uma queda numa categoria é tratada como alerta proporcional ao tamanho dela. Segundo, resolver o alerta ampliando a categoria: ninguém decide nada sobre consultas técnicas com 6 perguntas, e o caminho é juntar mais 30 ou 40 perguntas técnicas e repetir o teste. A outra pergunta que o reranker piorou é a 13, sobre o crédito por atraso, uma das perguntas de paráfrase. O relatório da seção 4 a mostra: o reranker preferiu um trecho do regulamento de pontos sobre cancelamento (nota −1,95) a um trecho de entregas que continha a resposta.

13. O trade-off do limiar de pontuação

Reranking mostrou que o cross-encoder devolve uma nota por par, e que um limiar sobre ela permite recusar antes de chamar o modelo. Medi o limiar nas 14 perguntas sem resposta e nas 56 com resposta. A recusa correta é a fração das perguntas sem resposta em que a nota do melhor pedaço ficou abaixo do limiar. A falsa recusa é a fração das perguntas com resposta que o limiar barrou. As úteis mantidas são as que tiveram o ouro no topo e passaram pelo limiar.

 limiar  recusa correta (14 sem resp.)    falsa recusa (56)   úteis mantidas
     -4         0.429 ( 6/14)         0.000 ( 0/56)          0.893
     -3         0.643 ( 9/14)         0.054 ( 3/56)          0.857
     -2         0.786 (11/14)         0.143 ( 8/56)          0.786
   -1.5         0.857 (12/14)         0.161 ( 9/56)          0.786
     -1         0.857 (12/14)         0.179 (10/56)          0.768
      0         0.857 (12/14)         0.232 (13/56)          0.750
      1         0.929 (13/14)         0.339 (19/56)          0.643
      2         1.000 (14/14)         0.464 (26/56)          0.536

A figura desenha o dilema. Com um limiar permissivo (−4), nenhuma pergunta legítima é barrada, mas 8 das 14 perguntas sem resposta seguem para o modelo, que pode inventar uma resposta plausível. No outro extremo (+2), as 14 perguntas sem resposta são barradas, e o preço é recusar 26 das 56 perguntas legítimas, quase metade. Entre os dois, a tabela traz uma observação que só aparece quando se lê linha a linha: o limiar −1 recusa corretamente as mesmas 12 perguntas do −1,5, e barra uma pergunta legítima a mais (10 contra 9). Escolher −1 nessa tabela não tem justificativa, porque o −1,5 empata em um eixo e é melhor no outro. Os limiares entre −2 e 0 pagam muito pouco pela recusa extra que compram.

Há um segundo cuidado, que Reranking e RAG já tinham: escolher o limiar olhando a tabela e avaliar na mesma tabela favorece o resultado. Para ver quanto, repeti 200 vezes um procedimento honesto, que escolhe o limiar numa metade das perguntas e mede na outra metade. O critério de escolha foi o das úteis mantidas menos as sem resposta que passam:

limiar escolhido no treino: mediana 0.0, faixa de 10% a 90%: -2.5 a 1.5
ganho no treino (otimista): 0.691 | ganho na outra metade: 0.539

O limiar que o procedimento escolhe varia de −2,5 a +1,5 conforme a divisão, e o ganho medido no treino é 15 pontos mais alto que o ganho na outra metade. Com tão poucas perguntas sem resposta (14), o “melhor” limiar é instável, e a conclusão certa é que esse número deve ser tratado como uma faixa. A escolha final é uma decisão de negócio: onde uma alucinação custa caro, como em saúde ou finanças, tolera-se uma falsa recusa maior para barrar quase tudo; num assistente de compras, tolera-se um pouco de risco para responder mais.

14. A esteira de CI para RAG

A defesa duradoura contra a regressão é automatizar a avaliação no ciclo de desenvolvimento. Cada alteração que possa mexer no resultado, seja o prompt, o modelo de embedding, o corte ou o acervo, deve disparar a suíte antes de entrar na branch principal.

A esteira funciona em duas velocidades. Na primeira, a cada pedido de mudança, roda a avaliação da recuperação (pontos 1 e 2) sobre o conjunto fixo: hit@k, MRR e a recusa pelo limiar, por categoria. Como não chama um modelo de linguagem pago, ela é rápida e não custa chamadas de API (não cronometrei o tempo no laboratório). O portão de aprovação reprova a mudança quando uma métrica cai além do que o ruído explica, usando o teste pareado das seções 9 e 10 e a regra por categoria da seção 12, não um limite fixo de “nunca cair um ponto”. Na segunda velocidade, diária ou semanal, roda a avaliação completa com geração e juiz (ponto 3), que custa mais e leva mais tempo e por isso vive em horário programado.

Parte 7: Produção e ferramentas

15. Avaliação online

Nenhum conjunto de laboratório prevê todas as maneiras de usar um sistema, e a avaliação offline precisa de telemetria em produção. Os sinais explícitos são o polegar para cima e para baixo e os comentários. Os implícitos são a reformulação da pergunta logo depois de uma resposta, que costuma indicar que a primeira falhou, o clique nas citações e a taxa de recusa pelo limiar. Os do sistema são a latência em percentis e o custo de tokens por consulta.

O ciclo da figura é o que mantém o conjunto de avaliação vivo. As perguntas que receberam polegar negativo, que foram barradas pelo limiar ou que geraram citações quebradas são triadas por uma pessoa, limpas de dados pessoais (LGPD) e entram no conjunto oficial, com o pedaço-ouro marcado. Cada erro de produção torna a suíte mais forte contra aquele padrão. O monitoramento também detecta deriva: com os meses entram produtos novos, regras antigas saem e o vocabulário dos clientes muda. Se a taxa de recusa sobe devagar sem nenhuma mudança de código, o acervo está ficando desatualizado em relação ao que as pessoas perguntam.

16. O que as ferramentas prontas oferecem

Consultei, em 15 de outubro de 2026, as páginas e os resumos listados nas fontes. Só descrevo o que li.

O Ragas organiza a avaliação em métricas de recuperação e de geração. A documentação lista context precision, context recall, faithfulness e response relevancy, entre outras, e diz que algumas métricas usam um ou mais modelos de linguagem para chegar à nota. As páginas de context precision e de context recall que li mostram variantes com modelo, sem modelo e baseadas em identificadores, e a de faithfulness descreve a conta de afirmações sustentadas sobre afirmações totais. O artigo apresenta a proposta como avaliação sem referência, que dispensa anotação humana de resposta correta.

O TruLens descreve a chamada tríade do RAG: relevância do contexto, groundedness (a resposta quebrada em afirmações e cada uma procurada no contexto) e relevância da resposta, e afirma que bons resultados nas três sugerem um sistema sem alucinação dentro do limite da base de conhecimento. O DeepEval, pela página do FaithfulnessMetric, expõe a métrica como código: um objeto com limiar mínimo de aprovação (padrão 0,5), modelo juiz e opção de devolver a razão da nota, aplicado a um caso de teste com a pergunta, a resposta e o contexto recuperado, e avaliado por uma função evaluate. O ARES, descrito no resumo do artigo, avalia relevância do contexto, fidelidade e relevância da resposta com juízes leves treinados em dados sintéticos e corrige os erros deles com PPI.

Vale escrever o próprio código em dois casos. Para a recuperação (pontos 1 e 2), o cálculo de hit@k, MRR e teste pareado cabe em poucas dezenas de linhas, como o código desta aula, e roda sem custo de API. Para a geração, as ferramentas passam a compensar: elas já trazem os prompts de juiz, o tratamento de saída em JSON malformada e as tentativas repetidas, e reimplementar isso é trabalho de infraestrutura. Mesmo assim, uma nota de fidelidade vinda de uma biblioteca é uma nota de um juiz, e a seção 8 vale para ela do mesmo jeito.

Parte 8: Fechamento

17. Erros comuns

O erro de base é avaliar só a resposta final e ignorar a recuperação: tenta-se corrigir uma resposta errada trocando o prompt, quando o pedaço certo nem estava entre os candidatos. Outro é ajustar parâmetros no mesmo conjunto que decide o deploy, que produz notas otimistas que não se repetem em produção, como a seção 13 mediu no limiar. Um terceiro é montar um conjunto só de perguntas fáceis, sem siglas, sem tabelas e sem perguntas sem resposta, e descobrir as falhas de recusa em produção.

Os erros estatísticos vêm em seguida. Um é celebrar a diferença de dois pontos em 50 perguntas sem teste pareado. Outro é fazer o contrário e tratar um resultado de p = 0,065 como se fosse p = 0,001, ou como se fosse nada: a zona cinza pede mais perguntas, não uma decisão. Um terceiro é medir uma mudança só contra o adversário mais fácil, como o reranker contra o híbrido e não contra o vetor sozinho. E o último é concluir muito de uma categoria pequena, como a seção 12 mostra com 6 perguntas.

Do lado do juiz, o erro é confiar numa nota de um modelo que ninguém comparou com pessoas, e esquecer que o juiz tem vieses de posição, de tamanho e de autopreferência. Na operação, é subir o limiar de recusa até zerar as alucinações e criar um sistema que diz “não sei” a quem tem direito à resposta, o que a taxa de falsa recusa existe para denunciar.

18. Exercícios

1. Um sistema devolveu 4 pedaços e os relevantes estão nas posições 2 e 3. Calcule o hit@1, o hit@4, o RR e a context precision. Resposta: o hit@1 é 0 e o hit@4 é 1. O primeiro acerto está na posição 2, então RR = 1 ÷ 2 = 0,50. A precisão nos acertos é 1/2 na posição 2 e 2/3 na posição 3, e a context precision é (0,50 + 0,667) ÷ 2 ≈ 0,583.

2. Dois prompts foram testados em 100 perguntas: o A acertou 85 e o B acertou 87. Em 96 perguntas os dois tiveram o mesmo resultado, e nas 4 restantes o B ganhou 3 e o A ganhou 1. O que o teste do sinal diz? Resposta: com 4 casos discordantes, a probabilidade de um placar de 3 a 1 ou mais desigual, em qualquer direção, é (1 + 4 + 4 + 1) ÷ 16 = 0,625. A diferença é indistinguível do acaso, e o B não pode ser declarado melhor.

3. Pela tabela da seção 9, quantas perguntas você precisa para distinguir um ganho líquido de 5 pontos se 20% das perguntas mudam de resultado entre as duas versões? E quanto poder tem um conjunto de 56 perguntas para esse mesmo ganho? Resposta: cerca de 800 perguntas para 80% de poder, e 8% de poder com 56, o que significa que o conjunto atual quase nunca enxergaria esse ganho mesmo que ele existisse.

4. Um RAG de apoio a diagnóstico tem duas configurações de limiar: com o limiar 0, recusa corretamente 95% das perguntas sem base e recusa por engano 12% das perguntas com base; com o limiar −2, recusa por engano 2%, mas barra só 60% das sem base. Qual escolher, e que outra informação você pediria antes de decidir? Resposta: em medicina, uma alucinação custa mais que uma consulta manual ao prontuário, então a configuração mais rigorosa é a defensável. Antes de decidir eu pediria o número de perguntas sem base que sustenta os 95% e os 60%, porque com poucas perguntas os dois números têm margem enorme, e uma estimativa feita com 14 perguntas pode mudar 20 pontos de uma divisão para outra.

5. Rode o relatório da seção 4 no seu conjunto e liste, para cada pergunta em que o ouro não ficou em primeiro, a camada responsável. Quantas falhas pertencem a cada camada?

6. Agrupe as suas perguntas em categorias por uma regra escrita (por exemplo, “o gabarito é uma linha de tabela”) e meça o hit@1 antes e depois de uma mudança, por categoria, com o número de ganhas e perdidas. Alguma queda numa categoria pequena sobrevive quando você acrescenta mais perguntas dela?

7. Rotule à mão 50 respostas do seu sistema como aprovada ou reprovada e compare com a nota de um modelo juiz usando a rubrica da seção 7. Calcule a concordância e o kappa. O juiz passa da faixa que você definiu?

19. Glossário

20. Mapa de resolução de problemas

Este texto é o último do assunto. O percurso partiu de um modelo que não conhece os seus dados e chegou a um sistema que se mede. A figura reúne o que os textos ensinaram em um mapa de diagnóstico: quando o seu RAG falhar na avaliação ou em produção, comece por aqui.

Se a resposta vem incompleta, com uma tabela quebrada ou uma regra pela metade, o problema nasceu no corte e na preparação dos documentos, nas aulas Chunking e Ingestão de documentos. Se o sistema falha em códigos, siglas e nomes próprios, a busca por significado sozinha não bastou, e o caminho é o índice por palavras e a fusão da aula Busca híbrida, depois de conferir os embeddings e a busca das aulas Embeddings, Similaridade entre vetores, Busca vetorial e Banco de dados vetorial. Se o pedaço certo está entre os candidatos mas não chega ao prompt, falta o reordenamento e o limiar da aula Reranking. Se o pedaço certo chega ao prompt e o modelo ainda inventa, o problema está na montagem do prompt e na exigência de citações, que Prompt e contexto e RAG tratam, e vale lembrar do que LLMs ensina sobre por que o modelo inventa. E para qualquer mudança em qualquer um desses pontos, a avaliação desta aula, com os três pontos de medição, o recorte por categoria e o teste pareado, vem antes de dar o trabalho por concluído.

Parte 9: Depuração e asserções determinísticas

As duas seções a seguir ampliam o diagnóstico em camadas da seção 11 e a avaliação com juiz das seções 7 e 8 com duas disciplinas que valem para qualquer aplicação com Claude, tenha ela RAG ou não.

21. Depuração e tratamento de erros

Quando a aplicação “não funciona”, há dois tipos de problema que parecem iguais para o usuário e têm causas e remédios opostos. No primeiro, a chamada à API falha: a resposta nem chega, ou chega como erro. No segundo, a chamada dá certo, devolve status 200 e um texto bem formado, mas o texto está errado, vago ou inventado. O primeiro tipo se resolve com código de tratamento de erros. O segundo se resolve com avaliação, que é o assunto do resto desta aula. Misturar os dois é gastar uma tarde trocando o prompt para consertar uma chave de API vencida, ou colocar um laço de repetição em volta de uma resposta que está errada por culpa do pedaço recuperado.

Os erros da API vêm num formato previsível. A documentação oficial da Anthropic (consultada em 18 de outubro de 2026) lista os códigos HTTP com um tipo de erro para cada um: 400 invalid_request_error, 401 authentication_error, 402 billing_error, 403 permission_error, 404 not_found_error, 409 conflict_error, 413 request_too_large, 429 rate_limit_error, 500 api_error, 504 timeout_error e 529 overloaded_error. O corpo é sempre JSON, com um objeto error que traz type e message, e um campo request_id no nível de cima. A mesma identificação volta no cabeçalho request-id de toda resposta, e é o dado que o suporte pede quando você abre um chamado. A documentação avisa também que os valores de type podem aumentar com o tempo, então o código não deve quebrar diante de um tipo desconhecido.

Os quatro casos a seguir se leem assim:

• Erro de requisição inválida (400, invalid_request_error): o problema está no que você enviou, no formato ou no conteúdo. Repetir a mesma chamada devolve o mesmo erro. O conserto é no código, lendo o campo message, que costuma apontar a posição do campo problemático. A documentação dá exemplos de 400 por parâmetro que o modelo escolhido não aceita. A mesma página diz que o tipo pode valer também para outros códigos 4XX que ela não lista, e que a API devolve 400 quando o uso chega a um limite de gasto definido por você na organização ou no workspace.
• Limite de taxa (429, rate_limit_error): a sua organização passou de um limite de uso. A requisição estava correta, e por isso repetir mais tarde funciona. A documentação diz que o SDK oficial já tenta de novo, com espera exponencial, duas vezes por padrão, e respeita o cabeçalho retry-after quando ele existe. Há uma exceção que a página destaca: um 429 causado por teto mensal de gasto do nível de uso não traz retry-after e continua falhando até o acesso voltar, então repetir em laço não adianta.
• Erro do servidor (500, api_error, e 529, overloaded_error): o problema é do lado da Anthropic. A orientação oficial para o 500 é repetir com espera exponencial e, se persistir, contatar o suporte com o request_id. O 529 significa API temporariamente sobrecarregada por tráfego alto de todos os usuários, e o tratamento prático é o mesmo, esperar e tentar de novo.
• Tempo esgotado (504, timeout_error): a requisição demorou demais para ser processada. A documentação recomenda a API de streaming para pedidos longos, em especial os de mais de 10 minutos, e a Message Batches API quando não se precisa da resposta na hora. Evitar um max_tokens grande em chamada sem streaming faz parte da recomendação, porque algumas redes derrubam conexões ociosas. Segundo a página, os SDKs validam que uma chamada sem streaming não deve passar de 10 minutos de espera.

O motivo de separar esses casos é a decisão de repetir ou não. Erros transitórios (429 de taxa, 500, 504, 529) merecem nova tentativa com espera crescente, para não bater de novo no mesmo problema ao mesmo tempo que todos os outros clientes. Erros permanentes (400, 401, 403, 404) não merecem: repetir só gasta tempo e esconde o defeito. Na prática, use os SDKs e capture as classes de exceção tipadas em vez de procurar texto na mensagem de erro, tratando as mais específicas primeiro, como a própria documentação aconselha. Um detalhe de borda que a página registra: com streaming, o erro pode acontecer depois de a API já ter devolvido 200, e nesse caso o tratamento padrão de status não o pega. Há eventos de erro próprios no fluxo, descritos na página de streaming, que eu não li.

Como saber de qual dos dois tipos é o seu problema? Pergunte se a chamada devolveu uma resposta de sucesso. Se houve exceção ou status diferente de 2xx, é erro da API, e o código HTTP e o type dizem de quem é a culpa e se vale repetir. Se o status foi 200 e o texto está ruim, é erro de qualidade, e aí o diagnóstico em camadas da seção 11 assume: o pedaço certo estava entre os candidatos, entrou no prompt, foi usado? Um caso intermediário é a resposta cortada, em que a chamada tem sucesso mas o texto termina no meio porque o limite de saída acabou. Pela referência da API que conheço, o campo stop_reason da resposta indica isso (valor max_tokens); não reconfirmei esse campo na consulta desta aula, então confira na referência de Messages antes de confiar nele. Cortada pelo limite parece erro de qualidade e é, na verdade, configuração.

A segunda metade do item 9.1 é a regra de mudar uma variável por vez. Uma aplicação com Claude tem muitas peças que se mexem: o prompt de sistema, o modelo, a temperatura, o k da recuperação, o tamanho dos pedaços, o limiar de recusa, a versão do índice. Se você troca três delas e a nota sobe, não sabe qual ajudou, e se desce, não sabe qual atrapalhou. Com uma variável por vez, cada experimento tem uma só explicação possível, e o resultado fica atribuído a uma mudança. O teste pareado das seções 9 e 10 entra aqui como o árbitro: rode a versão antiga e a nova sobre o mesmo conjunto fixo, mude uma coisa, e só então leia o placar de vitórias e derrotas. A seção 10 mostrou o preço de ignorar essa regra por outro caminho: comparar o reranker só contra o híbrido, e não contra o vetor sozinho, é mudar duas coisas na cabeça sem notar. Quando duas mudanças estão acopladas de verdade (por exemplo, trocar o modelo de embedding obriga a reconstruir o índice), trate o par como uma única variável e anote isso.

O que não confirmei nesta seção: a página de limites de taxa (nomes exatos dos cabeçalhos de limite restante e de reinício), a página de streaming com os eventos de erro e a referência do campo stop_reason. Também não testei nenhuma dessas falhas contra a API.

22. Asserções determinísticas antes do juiz

A seção 7 ensinou a usar um modelo como juiz. Ele é flexível, entende paráfrase e consegue avaliar coisas que nenhuma regra captura, como clareza ou utilidade. Mas cobra por chamada, leva segundos por pergunta, e dá notas que variam entre execuções e têm os vieses da seção 8. Antes de gastar um juiz, vale perguntar quanto do que você quer verificar dispensa um modelo. Uma parte surpreendentemente grande dispensa, e para essa parte existe a asserção determinística: um teste escrito em código comum, que devolve passou ou falhou e dá o mesmo resultado em qualquer execução.

A regra de ordem é rodar as asserções primeiro e só mandar ao juiz o que passou por elas. Três razões sustentam a regra. A primeira é custo: uma checagem de formato roda em microssegundos e não consome token, enquanto o juiz custa dinheiro em cada resposta, inclusive nas que estavam quebradas de maneira óbvia. A segunda é velocidade: um conjunto de 500 perguntas com asserções termina rápido o bastante para rodar a cada pedido de mudança, no primeiro nível da esteira da seção 14. A terceira é confiabilidade: uma asserção não tem humor, não prefere o texto mais longo e não se deixa convencer por uma resposta com tom seguro. Se a resposta devia ser JSON e não é, não existe rubrica que a salve, e perguntar a um juiz se “parece correta” é pedir a um modelo que opine sobre algo que o código já sabe.

Os exemplos mais comuns, aplicados ao RAG deste laboratório:

• Formato: a resposta é JSON válido? Tem os campos que o seu código espera? Os tipos estão certos (a nota é número, não texto)? Um json.loads dentro de um try resolve a primeira pergunta, e a comparação com um esquema resolve as outras.
• Presença de campo: se o prompt exige o campo fonte, ele existe e não está vazio? Se a recusa deve ser exatamente “Não encontrei isso nos documentos.”, a resposta de uma pergunta sem acervo contém essa frase?
• Citação que existe: a seção 6 listou três jeitos de errar uma citação, e os dois primeiros podem ser tratados sem modelo. O índice [7] num prompt com 5 pedaços é impossível, e uma expressão regular que extrai os números entre colchetes e confere se estão de 1 a 5 detecta isso. Se o modelo foi instruído a copiar uma frase literal do pedaço, confira com uma busca de texto se a frase aparece mesmo no pedaço citado.
• Limites e proibições: o tamanho está dentro do pedido? Apareceu algum dado que não podia aparecer, como um CPF? Um número que a resposta cita (o prazo de 7 dias, por exemplo) aparece no pedaço fornecido?

import json, re

def asserir(resposta_texto, n_pedacos):
    erros = []
    try:
        dados = json.loads(resposta_texto)
    except json.JSONDecodeError:
        return ["não é JSON válido"]
    for campo in ("resposta", "citacoes"):
        if campo not in dados:
            erros.append(f"falta o campo {campo}")
    for c in dados.get("citacoes", []):
        if not (1 <= c <= n_pedacos):
            erros.append(f"citação [{c}] não existe entre os {n_pedacos} pedaços")
    return erros          # lista vazia = passou; só então chame o juiz

Esse trecho é um exemplo meu para mostrar o formato da ideia; não o rodei contra respostas de um modelo. O que ele ilustra é o desenho: a função devolve uma lista de falhas com motivo, o que torna cada reprovação diagnosticável, e só uma lista vazia libera a resposta para o passo caro.

A asserção também tem limite, e conhecê-lo evita o erro oposto. Uma citação que existe no texto não prova que ela sustenta a afirmação: o pedaço [2] pode existir e falar de outro assunto, como na figura da seção 6. Uma resposta pode ter o formato perfeito e conteúdo falso. Por isso a ordem é asserção e depois juiz, não asserção no lugar do juiz. As asserções filtram o que é barato de rejeitar e garantem que o juiz receba material avaliável, e o juiz fica com a pergunta que exige entendimento: a afirmação é sustentada, a resposta atende ao pedido? Outro benefício aparece na calibração da seção 8. Quando você mede o kappa do juiz contra pessoas, uma amostra que já passou pelas asserções não gasta rótulos humanos em respostas quebradas, e a concordância medida diz respeito ao que o juiz realmente decide.

Na esteira de CI, isso fica assim: primeiro as asserções, sobre todo o conjunto, a cada mudança; depois o juiz, só sobre as respostas aprovadas, no horário programado. Uma queda súbita na taxa de aprovação das asserções é, além disso, um sinal de depuração de primeira ordem: ela quase sempre indica que uma mudança de prompt ou de modelo quebrou o formato, e a regra de uma variável por vez aponta qual.

Não encontrei, nas páginas que consultei, uma recomendação oficial da Anthropic com este nome ou com esta ordem exata. A ideia de verificar o que for verificável por código antes de usar um modelo avaliador é prática de engenharia que escrevo a partir do que se conhece de testes de software, e não uma citação da documentação. Para a formulação, confira o vocabulário nos materiais oficiais de avaliação.

Fontes

Consultadas em 15 de outubro de 2026. Li os resumos e as páginas listadas por uma ferramenta que as resume, e não integralmente, então detalhes que a ferramenta não trouxe podem existir nelas.

• Es e colegas, “Ragas: Automated Evaluation of Retrieval Augmented Generation” (arXiv 2309.15217, 2023): proposta de avaliação de RAG sem referência, que dispensa anotação humana de resposta correta, nas dimensões do recuperador, do uso fiel do contexto e da qualidade da geração. A página que li não nomeia as métricas nem a conferência.
• Zheng e colegas, “Judging LLM-as-a-Judge with MT-Bench and Chatbot Arena” (arXiv 2306.05685): vieses de posição, verbosidade e autopreferência, limitação de raciocínio, e concordância acima de 80% de juízes fortes com preferências humanas (resumo).
• Saad-Falcon e colegas, “ARES: An Automated Evaluation Framework for Retrieval-Augmented Generation Systems” (arXiv 2311.09476): juízes leves treinados em dados sintéticos, correção por PPI com algumas centenas de anotações humanas, avaliação de relevância do contexto, fidelidade e relevância da resposta (resumo). O resumo não menciona intervalos de confiança.
• Ragas: lista de métricas: nomes das métricas de RAG e a nota geral de que métricas baseadas em modelo podem usar uma ou mais chamadas. A página não define as métricas.
• Ragas: Context Precision, Context Recall e Faithfulness: definições, variantes com modelo, sem modelo e por identificador, e a conta de afirmações sustentadas sobre afirmações totais.
• TruLens: tríade do RAG: relevância do contexto, groundedness e relevância da resposta.
• DeepEval: FaithfulnessMetric: definição da métrica, parâmetros threshold (padrão 0,5), model e include_reason, exemplo com LLMTestCase e evaluate. A página que li não mostra assert_test.
• Claude API errors (platform.claude.com/docs/en/api/errors): consultada em 18 de outubro de 2026. Códigos HTTP e tipos de erro, formato do corpo, request_id, tentativas automáticas do SDK, streaming e pedidos longos (seção 21). Redirecionada de docs.anthropic.com.
• RAG, Reranking, Busca híbrida e Chunking: o pipeline, o corpus do Mercado Aurora, as 56 perguntas e as métricas de partida.

Medido por mim (ambiente virtual no scratchpad da sessão, macOS, CPU; sentence-transformers, torch e tiktoken como em Reranking, modelos multilingual-e5-small e mmarco-mMiniLMv2 do cache local; nada instalado fora do ambiente): a tabela de estágios, as camadas 1 e 2, o relatório por pergunta, as comparações pareadas com teste do sinal exato e bootstrap de 10.000 reamostragens, o recorte por categoria, o limiar sobre as 14 perguntas sem resposta, a validação do limiar em metades (200 divisões), a simulação de tamanho de amostra e a contagem de tokens de k = 3 e k = 5. O cálculo do kappa da seção 8 usa números que inventei para mostrar a conta.

Sem execução ou sem fonte: não rodei nenhum modelo de linguagem, então a camada 3 (fidelidade, relevância, citações e recusa feita pelo modelo) não tem número medido, o prompt do juiz não foi executado e a resposta da figura de citações é um exemplo escrito por mim. As categorias do conjunto foram atribuídas por regra e o conjunto não tem perguntas que juntem dois pedaços. O corpus é pequeno e inventado, as 14 perguntas sem resposta são poucas, e o limiar foi escolhido e avaliado sobre o mesmo conjunto, com a verificação em metades como atenuante. As faixas do kappa são convenção que não conferi numa fonte. Não li o Ragas, o TruLens, o DeepEval nem o ARES além do que as páginas e os resumos citados dizem, e não rodei nenhum deles. Os tempos de execução da esteira de CI não foram cronometrados. Nas seções 21 e 22, não li a página de limites de taxa, a de streaming nem a referência do campo stop_reason, não provoquei nenhum dos erros contra a API, o trecho de asserções é um exemplo que não executei, e a ordem asserção antes do juiz é prática de engenharia minha, sem fonte oficial confirmada.

Relacionados

• LLMs
• Prompt e contexto
• Embeddings
• Similaridade entre vetores
• Busca vetorial
• Banco de dados vetorial
• Chunking
• Ingestão de documentos
• Busca híbrida
• Reranking
• Agents
• MCP
• Spec-driven development