<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Adriano Leão</title>
    <description>The latest articles on DEV Community by Adriano Leão (@adrianocleao).</description>
    <link>https://dev.to/adrianocleao</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4248116%2F079fa34f-f175-4021-834f-9da05783032b.jpg</url>
      <title>DEV Community: Adriano Leão</title>
      <link>https://dev.to/adrianocleao</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/adrianocleao"/>
    <language>en</language>
    <item>
      <title>Como construir um benchmark reproduzível de LLMs em Python: o caso do Teor</title>
      <dc:creator>Adriano Leão</dc:creator>
      <pubDate>Mon, 16 Nov 2026 16:10:35 +0000</pubDate>
      <link>https://dev.to/adrianocleao/como-construir-um-benchmark-reproduzivel-de-llms-em-python-o-caso-do-teor-3h76</link>
      <guid>https://dev.to/adrianocleao/como-construir-um-benchmark-reproduzivel-de-llms-em-python-o-caso-do-teor-3h76</guid>
      <description>&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;Não basta preparar perguntas, enviar prompts e verificar se as respostas parecem corretas.&lt;/p&gt;

&lt;p&gt;É 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.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  1. Comece separando as capacidades
&lt;/h2&gt;

&lt;p&gt;O Teor possui 3.000 itens, organizados em oito trilhas.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;O ponto importante é que essas tarefas não precisam utilizar a mesma métrica.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;Por exemplo:&lt;/p&gt;

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

&lt;p&gt;Uma decisão central do projeto foi não agregar tudo em uma única nota.&lt;/p&gt;

&lt;h2&gt;
  
  
  2. Separe conhecimento de compreensão
&lt;/h2&gt;

&lt;p&gt;Uma mesma pergunta pode ser apresentada com ou sem os registros necessários para respondê-la.&lt;/p&gt;

&lt;p&gt;No primeiro modo, avaliamos o que o modelo consegue fazer com as informações que recebeu.&lt;/p&gt;

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

&lt;p&gt;A diferença entre os resultados é interessante para quem trabalha com RAG.&lt;/p&gt;

&lt;p&gt;Na avaliação do &lt;code&gt;gemini-3.5-deep-think&lt;/code&gt;, 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.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  3. Estruture as respostas antes de implementar as métricas
&lt;/h2&gt;

&lt;p&gt;O contrato de resposta utilizado pelo Teor tem duas propriedades principais:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"value"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;42&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"abstain"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Esse é um exemplo ilustrativo de uma resposta inteira.&lt;/p&gt;

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

&lt;p&gt;O campo &lt;code&gt;abstain&lt;/code&gt; permite indicar que não existe informação suficiente para responder.&lt;/p&gt;

&lt;p&gt;Essa estrutura torna possível distinguir respostas incorretas, abstenções e violações do formato esperado.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  4. Controle os dados e os splits
&lt;/h2&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;No Teor, registros relacionados são agrupados em famílias factuais antes da divisão dos conjuntos.&lt;/p&gt;

&lt;p&gt;Também utilizamos snapshots das fontes oficiais, manifestos, hashes e configurações identificáveis.&lt;/p&gt;

&lt;p&gt;O objetivo é que uma avaliação possa ser vinculada a uma versão concreta dos dados e do protocolo.&lt;/p&gt;

&lt;h2&gt;
  
  
  5. Execute parte do pipeline localmente
&lt;/h2&gt;

&lt;p&gt;O repositório disponibiliza uma CLI em Python. Para começar:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;git clone https://github.com/como-votam/teor.git
&lt;span class="nb"&gt;cd&lt;/span&gt; teor

python -m pip install uv
uv sync --extra &lt;span class="nb"&gt;eval&lt;/span&gt; --group dev

uv run teor --help
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A coleta e construção do benchmark podem ser feitas a partir das APIs legislativas oficiais.&lt;/p&gt;

&lt;p&gt;O README documenta o seguinte fluxo para a janela inicial de setembro de 2026:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;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
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Depois, é possível executar uma referência simples e calcular suas métricas:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;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
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Essa parte não exige uma chave de API de LLM. A coleta, naturalmente, depende do acesso às fontes oficiais.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  6. Não confunda desempenho com significância
&lt;/h2&gt;

&lt;p&gt;O Teor publica intervalos de confiança utilizando bootstrap por famílias factuais.&lt;/p&gt;

&lt;p&gt;Isso importa porque perguntas relacionadas a uma mesma votação não são necessariamente observações independentes.&lt;/p&gt;

&lt;p&gt;Também disponibilizamos referências simples, incluindo classe majoritária e BM25.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  7. Avalie o que a automação não consegue decidir
&lt;/h2&gt;

&lt;p&gt;Um dos pontos mais interessantes do projeto é a trilha de grounding.&lt;/p&gt;

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

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;É uma distinção que vale considerar em qualquer projeto que utilize LLMs para resumir documentos.&lt;/p&gt;

&lt;h2&gt;
  
  
  Explore ou contribua
&lt;/h2&gt;

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

&lt;p&gt;Também é possível explorar os itens, analisar dados pelo console SQL e executar um desafio de dez perguntas.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Benchmark:&lt;/strong&gt; &lt;a href="https://teor.comovotam.com.br/" rel="noopener noreferrer"&gt;https://teor.comovotam.com.br/&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;GitHub:&lt;/strong&gt; &lt;a href="https://github.com/como-votam/teor" rel="noopener noreferrer"&gt;https://github.com/como-votam/teor&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Documentação da CLI:&lt;/strong&gt; &lt;a href="https://github.com/como-votam/teor/blob/main/docs/cli.md" rel="noopener noreferrer"&gt;https://github.com/como-votam/teor/blob/main/docs/cli.md&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Metodologia:&lt;/strong&gt; &lt;a href="https://teor.comovotam.com.br/metodologia/" rel="noopener noreferrer"&gt;https://teor.comovotam.com.br/metodologia/&lt;/a&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;O projeto é open source, sob licença Apache 2.0.&lt;/p&gt;

&lt;p&gt;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?&lt;/p&gt;

</description>
      <category>ai</category>
      <category>python</category>
      <category>opensource</category>
      <category>discuss</category>
    </item>
  </channel>
</rss>
