Quando começamos a desenvolver o Teor, um benchmark aberto de modelos de linguagem sobre o Congresso brasileiro, percebemos que avaliar uma LLM envolve decisões bastante diferentes daquelas que tomamos ao desenvolver uma aplicação tradicional.

Não basta preparar perguntas, enviar prompts e verificar se as respostas parecem corretas.

É necessário definir o que está sendo avaliado, estabelecer referências verificáveis, controlar os dados disponíveis em cada cenário e garantir que os resultados possam ser comparados e reproduzidos.

Neste artigo, quero compartilhar algumas decisões que tomamos no Teor e mostrar como você pode experimentar parte do pipeline de avaliação em Python.

1. Comece separando as capacidades

O Teor possui 3.000 itens, organizados em oito trilhas.

Entre elas, avaliamos tarefas de extração de informações, interpretação de documentos, contagem de votos, compreensão de sequências temporais, previsão e uso de ferramentas.

O ponto importante é que essas tarefas não precisam utilizar a mesma métrica.

Uma contagem de votos pode ser avaliada comparando dois inteiros. Uma lista de autores pode ser comparada como conjunto. Uma previsão probabilística exige considerar a confiança associada à resposta.

Por exemplo:

  • Exact match: respostas factuais que exigem correspondência exata.
  • F1 de conjunto: respostas com múltiplas entidades, como autores.
  • Brier score: avaliação de probabilidades.
  • Verificação de citações: existência de trechos e referências.
  • Revisão humana: fidelidade semântica de afirmações.

Uma decisão central do projeto foi não agregar tudo em uma única nota.

2. Separe conhecimento de compreensão

Uma mesma pergunta pode ser apresentada com ou sem os registros necessários para respondê-la.

No primeiro modo, avaliamos o que o modelo consegue fazer com as informações que recebeu.

No segundo, observamos como ele responde sem aquele contexto documental, o que pode envolver conhecimento prévio, memorização ou inferência.

A diferença entre os resultados é interessante para quem trabalha com RAG.

Na avaliação do gemini-3.5-deep-think, por exemplo, a identificação de referências normativas em proposições da Câmara passou de 63,0% sem contexto para 95,0% com contexto.

Isso não significa que qualquer implementação de RAG produziria esse ganho. O experimento mede o desempenho com os registros fornecidos, não a qualidade de um sistema de recuperação de documentos em produção.

3. Estruture as respostas antes de implementar as métricas

O contrato de resposta utilizado pelo Teor tem duas propriedades principais:

{ "value": 42, "abstain": false } 

Esse é um exemplo ilustrativo de uma resposta inteira.

O tipo esperado de value depende da tarefa: pode ser um texto, número, conjunto, sequência, probabilidade ou estrutura de afirmações e citações.

O campo abstain permite indicar que não existe informação suficiente para responder.

Essa estrutura torna possível distinguir respostas incorretas, abstenções e violações do formato esperado.

Também é importante separar falhas do modelo de falhas de infraestrutura. Um erro de rede, por exemplo, não demonstra que o modelo desconhece uma informação.

4. Controle os dados e os splits

Se uma pergunta sobre uma votação aparece no conjunto de desenvolvimento e uma variante praticamente idêntica aparece no teste, a separação não oferece a independência que esperamos.

No Teor, registros relacionados são agrupados em famílias factuais antes da divisão dos conjuntos.

Também utilizamos snapshots das fontes oficiais, manifestos, hashes e configurações identificáveis.

O objetivo é que uma avaliação possa ser vinculada a uma versão concreta dos dados e do protocolo.

5. Execute parte do pipeline localmente

O repositório disponibiliza uma CLI em Python. Para começar:

git clone https://github.com/como-votam/teor.git cd teor python -m pip install uv uv sync --extra eval --group dev uv run teor --help 

A coleta e construção do benchmark podem ser feitas a partir das APIs legislativas oficiais.

O README documenta o seguinte fluxo para a janela inicial de setembro de 2026:

uv run teor collect \ --start 2026-09-01 \ --end 2026-09-30 \ --output data/setembro-2026 uv run teor snapshot verify data/setembro-2026 uv run teor build data/setembro-2026 \ --output data/benchmark uv run teor validate data/benchmark/items.jsonl 

Depois, é possível executar uma referência simples e calcular suas métricas:

uv run teor baseline \ data/benchmark/test-public.jsonl \ --dev data/benchmark/dev.jsonl \ --output data/random.jsonl uv run teor score \ data/benchmark/test-public.jsonl \ data/random.jsonl \ --output reports/random.json 

Essa parte não exige uma chave de API de LLM. A coleta, naturalmente, depende do acesso às fontes oficiais.

Para reproduzir exatamente uma execução publicada, é necessário utilizar os mesmos artefatos, parâmetros e versões do protocolo, não apenas repetir as datas da coleta.

6. Não confunda desempenho com significância

O Teor publica intervalos de confiança utilizando bootstrap por famílias factuais.

Isso importa porque perguntas relacionadas a uma mesma votação não são necessariamente observações independentes.

Também disponibilizamos referências simples, incluindo classe majoritária e BM25.

Um modelo que obtém uma porcentagem elevada não necessariamente produz um resultado melhor que uma estratégia muito mais simples. Esse é um problema particularmente relevante nas tarefas de previsão com classes desbalanceadas.

7. Avalie o que a automação não consegue decidir

Um dos pontos mais interessantes do projeto é a trilha de grounding.

Verificar se um trecho citado existe em um documento pode ser automatizado. Avaliar se esse trecho sustenta semanticamente a afirmação produzida é outro problema.

O protocolo do Teor prevê revisão humana independente para essa segunda etapa, em vez de presumir que a existência da citação demonstra fidelidade.

É uma distinção que vale considerar em qualquer projeto que utilize LLMs para resumir documentos.

Explore ou contribua

Publicamos 30 execuções, contando 27 modelos e três referências, com métricas e comparações disponíveis no site.

Também é possível explorar os itens, analisar dados pelo console SQL e executar um desafio de dez perguntas.

O projeto é open source, sob licença Apache 2.0.

Se você desenvolve aplicações com LLMs, gostaria de ouvir sua experiência: como você avalia a qualidade dos modelos antes de utilizá-los em produção? Tem utilizado benchmarks existentes ou criado conjuntos específicos para seu domínio?