Escolher um modelo de linguagem só porque a ficha técnica promete números altos já não chega. Em setembro de 2026, com dezenas de LLMs open-source a disputar o mesmo espaço, a única forma de saber qual funciona melhor para o teu caso é correr um benchmark tu mesmo, com os teus dados e no teu hardware. Este tutorial mostra, passo a passo, como usar o lm-evaluation-harness da EleutherAI, a ferramenta que se tornou referência da indústria para avaliar modelos de forma reprodutível, e como complementá-lo com o OpenCompass e com leaderboards como o LMArena.
No final, vais ter um projeto completo capaz de testar qualquer modelo (local ou via API) em dezenas de tarefas académicas, gerar relatórios comparáveis e detetar regressões antes de colocares um modelo em produção. Não é preciso ser investigador de IA. É preciso paciência, uma GPU decente (ou paciência a dobrar sem ela) e seguir os passos pela ordem certa.
Este guia insere-se no acompanhamento que fazemos na cobertura de inteligência artificial do shattered.io e serve tanto para quem escolhe entre dois modelos open-source para um projeto pessoal como para uma equipa de engenharia que precisa de justificar, com números, a troca de fornecedor de IA. Ao longo dos onze passos seguintes vais instalar a ferramenta, correr o primeiro benchmark, acelerar tudo com vLLM, criar uma tarefa de avaliação à tua medida e terminar com um script que compara vários modelos automaticamente. Também há uma secção de erros comuns, uma lista alargada de resolução de problemas e dicas avançadas para quando os números tiverem de resistir a uma auditoria interna.
O que é o lm-evaluation-harness e porque se tornou o padrão
O lm-evaluation-harness é um projeto open-source da EleutherAI que resolve um problema muito concreto: como correr o mesmo benchmark em modelos diferentes, com os mesmos prompts, o mesmo método de pontuação e o mesmo formato de relatório. Sem uma ferramenta assim, cada equipa acaba a implementar o seu próprio código de avaliação, os números deixam de ser comparáveis entre si e a “vantagem” de um modelo sobre outro pode não passar de uma diferença na forma como o prompt foi construído.
A própria documentação oficial descreve o projeto como uma estrutura unificada para testar modelos generativos de linguagem num número grande de tarefas de avaliação diferentes, o que resume bem porque acabou por se tornar a base de leaderboards públicos como o Open LLM Leaderboard da HuggingFace. Quando duas equipas em lados opostos do mundo publicam o mesmo número de MMLU para o mesmo modelo, é porque ambas usaram este harness (ou um clone fiel da sua lógica de prompting) e não porque calharam a implementar exatamente o mesmo código de raiz.
A versão mais recente do repositório, a v0.4.13, lançada a 31 de agosto de 2026, trouxe um sistema de plugins que permite registar backends de modelos, filtros, métricas e agregações a partir de um pacote próprio, sem precisar de fazer fork do projeto. Basta usar um entry point lm_eval.* ou a flag --plugins para apontar para módulos locais. Isto facilita muito a tarefa de quem quer avaliar um modelo proprietário ou uma arquitetura pouco comum sem reescrever a ferramenta toda.
O repositório também recebeu, a meio de agosto de 2026, um pacote de tarefas do LegalBench com uma suite “Contract NLI” composta por 14 tarefas de inferência sobre acordos de confidencialidade (NDA), o que mostra a direção do projeto: cobrir cada vez mais domínios verticais, além dos clássicos benchmarks académicos. Todas as tarefas, incluindo estas, são definidas através de ficheiros de configuração YAML, o que torna o processo de criar uma tarefa nova muito mais acessível do que escrever código Python de raiz. O repositório mantém-se ativo, com commits recentes a poucos dias da data de publicação deste artigo, um bom sinal de manutenção contínua para quem depende dele em produção.
Pré-requisitos: hardware, software e versões
Antes de instalar seja o que for, confirma que tens os componentes abaixo. Dá para correr o lm-evaluation-harness apenas em CPU para modelos pequenos, mas para qualquer coisa acima dos 3-4 mil milhões de parâmetros vais querer uma GPU com pelo menos 12 GB de VRAM.
| Componente | Versão mínima recomendada | Para que serve |
|---|---|---|
| Python | 3.10 ou 3.11 | Ambiente de execução do harness |
| lm-evaluation-harness | v0.4.13 (agosto de 2026) | Motor de avaliação e biblioteca de tarefas |
| PyTorch | 2.3 ou superior, com suporte a CUDA | Backend de inferência para modelos HuggingFace |
| vLLM | versão mais recente compatível com o teu CUDA | Inferência acelerada para modelos grandes |
| Git | 2.30+ | Clonar o repositório e as tarefas |
| GPU (opcional mas recomendado) | 12 GB+ de VRAM (NVIDIA) | Reduzir o tempo de avaliação de horas para minutos |
| Espaço em disco | 20 GB livres | Pesos de modelos e datasets de benchmark descarregados |
Se não tiveres GPU, não é motivo para desistir: a secção sobre avaliação via API compatível com OpenAI mais à frente permite testar modelos hospedados sem qualquer processamento local pesado. E se já tens modelos a correr localmente com o Ollama ou com o llama.cpp, também os podes ligar ao harness através de um endpoint local, como se verá no Passo 7.
Vale a pena reservar também algum tempo antes de começar: a primeira execução de qualquer tarefa descarrega o dataset correspondente do HuggingFace Hub, o que pode acrescentar vários minutos consoante a tua ligação à internet. Datasets como o MMLU já vêm em cache depois da primeira utilização, mas tarefas menos comuns podem ter ficheiros na ordem das centenas de megabytes. Se planeias correr o mesmo conjunto de tarefas em várias máquinas (por exemplo, um portátil de desenvolvimento e um servidor de produção), considera descarregar os datasets uma vez e partilhar a pasta de cache do HuggingFace entre ambientes, o que evita repetir downloads desnecessários.
Passo 1: preparar o ambiente Python
Começa por isolar o projeto num ambiente virtual. Isto evita conflitos de versões entre o harness e outras bibliotecas de IA que já tenhas instaladas, um problema comum quando se trabalha com várias ferramentas de LLM ao mesmo tempo, sobretudo se já tens projetos de fine-tuning ou de inferência local na mesma máquina, cada um com as suas próprias dependências de PyTorch.
mkdir benchmark-llm-projeto
cd benchmark-llm-projeto
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pipNo Windows, o comando de ativação muda para .venv\Scripts\activate. Confirma que estás mesmo dentro do ambiente virtual antes de avançar: o nome (.venv) deve aparecer no início da linha de comandos.
Passo 2: instalar o lm-evaluation-harness
Com o ambiente pronto, clona o repositório oficial e instala em modo editável. Isto permite editar ficheiros de tarefas diretamente na pasta clonada sem ter de reinstalar o pacote a cada alteração.
git clone --depth 1 https://github.com/EleutherAI/lm-evaluation-harness
cd lm-evaluation-harness
pip install -e .
# Extras opcionais conforme o backend que vais usar
pip install -e ".[vllm]"
pip install -e ".[openai]"Confirma a instalação com lm-eval --version. Se aparecer um número de versão sem erros de importação, está tudo pronto para o primeiro benchmark. Se o comando não for reconhecido, o pip provavelmente instalou os binários fora do PATH ativo do teu ambiente virtual, o que se resolve reativando o .venv antes de repetir o comando.
Passo 3: escolher o motor de inferência certo
O lm-evaluation-harness não corre modelos por si só: precisa de um backend que carregue os pesos e produza respostas. Existem quatro opções principais e a escolha certa depende do tamanho do modelo e do hardware disponível.
- HuggingFace Transformers: o mais simples de configurar, ideal para modelos até 7-8 mil milhões de parâmetros numa única GPU.
- vLLM: motor otimizado para débito elevado, recomendado quando o modelo é grande ou quando é preciso avaliar centenas de exemplos rapidamente.
- GGUF (via llama.cpp): para modelos quantizados a correr em CPU ou GPUs com pouca VRAM.
- API compatível com OpenAI: para avaliar modelos hospedados externamente, incluindo os que já correm atrás de uma gateway como o LiteLLM.
Não há uma resposta universal aqui. Uma equipa pequena a testar um modelo de 7B numa GPU consumer ganha mais com HuggingFace puro, pela simplicidade. Uma equipa a comparar cinco modelos de 30B ou mais ganha tempo real com vLLM, mesmo com a curva de aprendizagem inicial um pouco mais alta.
Um guia técnico bastante citado sobre este tema, publicado pelo engenheiro de machine learning Philipp Schmid, mostra exatamente como ligar o harness ao Hugging Face TGI e ao vLLM em servidores dedicados, o que confirma que a escolha do backend não é um detalhe menor: pode ser a diferença entre um benchmark que corre em 20 minutos e outro que demora a noite toda. Se o teu objetivo é apenas confirmar rapidamente se um modelo novo está ao nível do anterior antes de o promoveres para produção, HuggingFace puro com um batch pequeno costuma bastar. Se precisas de repetir o mesmo processo todas as semanas contra vários candidatos, o investimento em configurar o vLLM paga-se rápido em horas de GPU poupadas.
Passo 4: correr o primeiro benchmark (MMLU e HellaSwag)
Chegou a hora de correr uma avaliação real. O comando abaixo carrega um modelo do HuggingFace Hub e avalia-o em três tarefas clássicas: MMLU (conhecimento geral em 57 áreas), HellaSwag (raciocínio de senso comum) e GSM8K (problemas de matemática em texto).
lm_eval \
--model hf \
--model_args pretrained=meta-llama/Meta-Llama-3.1-8B-Instruct,dtype=auto \
--tasks mmlu,hellaswag,gsm8k \
--num_fewshot 5 \
--batch_size auto \
--output_path results/llama-3.1-8b/Dependendo do hardware, esta avaliação pode demorar entre 15 minutos e várias horas. O parâmetro --num_fewshot 5 define quantos exemplos de contexto são dados ao modelo antes da pergunta real, uma prática comum para simular como o modelo se comporta em uso real, e não numa avaliação de zero-shot artificial.
Passo 5: interpretar os resultados e as métricas
No final da execução, o harness grava um ficheiro JSON com os resultados e imprime uma tabela no terminal. Um exemplo típico de saída tem este aspeto:
| Tasks |Version|Filter|n-shot| Metric |Value | |Stderr|
|----------|------:|------|-----:|----------|-----:|---|-----:|
|mmlu | 2|none | 5|acc |0.6821|± |0.0039|
|hellaswag | 1|none | 5|acc_norm |0.8194|± |0.0038|
|gsm8k | 3|flexible| 5|exact_match|0.7532|±|0.0119|O campo Value mostra a percentagem de acerto (0 a 1) e o Stderr indica a margem de erro estatística. Uma diferença de 0,5 pontos percentuais entre dois modelos, com um stderr de 0,4, não é significativa. É um erro comum ler um leaderboard e tirar conclusões de diferenças que estão dentro da margem de ruído estatístico.
Repara também na coluna Filter: tarefas como o GSM8K usam um filtro chamado flexible, que tenta extrair a resposta numérica final mesmo quando o modelo “pensa em voz alta” antes de a dar. Sem este tipo de filtro, um modelo que raciocina corretamente mas formata a resposta de forma pouco convencional seria penalizado injustamente. A coluna Version identifica a revisão exata da tarefa, o que importa porque, tal como visto antes, o repositório recebe atualizações regulares a tarefas existentes. Ao arquivar os teus resultados, guarda sempre este número de versão junto com o resto do relatório.
Passo 6: acelerar a avaliação com vLLM em modelos maiores
Quando o modelo já não cabe confortavelmente numa GPU ou quando o número de exemplos é elevado, o backend HuggingFace puro torna-se lento. É aqui que o vLLM entra, com paralelismo de tensores e gestão de memória mais eficiente. O harness integra-se diretamente com ele:
lm_eval \
--model vllm \
--model_args pretrained=meta-llama/Meta-Llama-3.1-8B-Instruct,dtype=auto,gpu_memory_utilization=0.8,tensor_parallel_size=2 \
--tasks mmlu,hellaswag,gsm8k \
--num_fewshot 5 \
--batch_size auto \
--output_path results/llama-3.1-8b-vllm/O parâmetro tensor_parallel_size distribui o modelo por múltiplas GPUs, se as tiveres. Se só tens uma placa gráfica, deixa esse valor em 1. Quem já usa um guia de vLLM com Docker para servir modelos como o DeepSeek V4 Flash pode reaproveitar o mesmo contentor para correr estes benchmarks, sem montar um segundo ambiente. Na prática, migrar do backend HuggingFace para o vLLM costuma cortar o tempo total de avaliação para uma fração do original em tarefas com muitos exemplos, precisamente pelo processamento em lote mais eficiente e pela gestão de memória paginada que o vLLM implementa nos bastidores.
Passo 7: avaliar qualquer modelo via API compatível com OpenAI
Nem sempre o modelo a testar está nos teus servidores. Se estiver atrás de uma API compatível com o formato de mensagens da OpenAI (o que inclui a maioria dos gateways modernos), usa a interface local-chat-completions:
lm_eval \
--model local-chat-completions \
--model_args model=gpt-4o-mini,base_url=http://localhost:8000/v1/chat/completions \
--tasks mmlu,gsm8k \
--num_fewshot 5 \
--apply_chat_templateA flag --apply_chat_template é essencial: sem ela, o harness pode enviar prompts em formato incorreto para modelos que esperam a estrutura de conversação. Esta abordagem funciona bem com quem já centraliza o acesso a vários fornecedores através de uma gateway única, evitando ter de reconfigurar credenciais para cada modelo testado.
Passo 8: escolher as tarefas de benchmark certas
O harness inclui mais de 60 benchmarks académicos padrão, com centenas de subtarefas e variantes. Escolher as tarefas certas para o teu caso de uso poupa horas de computação desnecessária. A tabela seguinte resume as mais usadas em avaliações de produção.
| Tarefa | O que mede | Few-shot típico | Quando usar |
|---|---|---|---|
| MMLU | Conhecimento geral em 57 disciplinas | 5-shot | Avaliação geral de capacidade do modelo |
| HellaSwag | Raciocínio de senso comum e continuação de texto | 0 ou 5-shot | Testar coerência em contexto do dia a dia |
| GSM8K | Problemas de matemática em linguagem natural | 5-shot | Avaliar raciocínio numérico passo a passo |
| TruthfulQA | Tendência para gerar afirmações falsas mas plausíveis | 0-shot | Casos de uso sensíveis a desinformação |
| LegalBench (Contract NLI) | Inferência sobre cláusulas contratuais e NDAs | 0 ou 5-shot | Aplicações jurídicas e de compliance |
| HumanEval | Geração de código Python funcional | 0-shot | Modelos usados como assistentes de programação |
Para listar todas as tarefas disponíveis na tua instalação local, corre lm_eval --tasks list. Isto é particularmente útil depois de atualizares a versão do harness, já que novas suites (como a de LegalBench referida antes) vão sendo acrescentadas com regularidade. A documentação oficial no ReadTheDocs mantém uma lista atualizada de todas as tarefas e dos respetivos parâmetros suportados, o que costuma ser mais fiável do que confiar apenas no resultado do comando local, sobretudo em versões mais antigas do harness.
Uma regra prática para escolher tarefas: começa sempre por um subconjunto pequeno e rápido (MMLU, HellaSwag e GSM8K cobrem conhecimento geral, senso comum e raciocínio numérico em menos de uma hora na maioria das GPUs de consumo) e só depois acrescenta tarefas de domínio específico, como o LegalBench ou o HumanEval, quando o caso de uso o justificar. Correr as 60 e tal tarefas disponíveis de uma vez, sem critério, costuma gastar horas de computação em benchmarks irrelevantes para o problema que estás a tentar resolver.
Passo 9: comparar vários modelos lado a lado
Correr o benchmark modelo a modelo é fácil de esquecer ou de fazer com parâmetros diferentes por engano, o que invalida a comparação. A solução é um pequeno script que garante que todos os modelos passam exatamente pelas mesmas condições.
#!/usr/bin/env bash
set -e
MODELOS=(
"meta-llama/Meta-Llama-3.1-8B-Instruct"
"mistralai/Mistral-7B-Instruct-v0.3"
"Qwen/Qwen2.5-7B-Instruct"
)
for MODELO in "${MODELOS[@]}"; do
NOME_PASTA=$(echo "$MODELO" | tr '/' '_')
lm_eval \
--model vllm \
--model_args pretrained="$MODELO",dtype=auto,gpu_memory_utilization=0.85 \
--tasks mmlu,hellaswag,gsm8k,truthfulqa_mc2 \
--num_fewshot 5 \
--batch_size auto \
--output_path "results/${NOME_PASTA}/"
done
echo "Benchmarks concluídos. Resultados em results/"Guarda este ficheiro como comparar_modelos.sh, dá-lhe permissão de execução com chmod +x comparar_modelos.sh e corre-o de um jantar para outro se o hardware for limitado. No dia seguinte tens três pastas JSON prontas para comparar linha a linha.
Para transformar os três ficheiros JSON numa tabela legível, um pequeno script em Python com a biblioteca pandas resolve o trabalho pesado: lê cada ficheiro results.json dentro das pastas geradas, extrai o valor de acc ou exact_match de cada tarefa e monta uma tabela com uma linha por modelo e uma coluna por tarefa. Isto poupa a leitura manual de ficheiros JSON extensos e facilita colar o resultado final diretamente num relatório ou numa folha de cálculo para partilhar com o resto da equipa.
Passo 10: criar uma tarefa de avaliação personalizada em YAML
Os benchmarks académicos são úteis, mas raramente refletem o teu caso de uso real, seja um chatbot de apoio ao cliente ou um assistente jurídico. O harness permite criar tarefas próprias sem tocar em código Python, através de um ficheiro YAML.
# tarefas_personalizadas/apoio_cliente_pt.yaml
task: apoio_cliente_pt
dataset_path: json
dataset_kwargs:
data_files: ./dados/apoio_cliente_exemplos.jsonl
output_type: generate_until
test_split: test
doc_to_text: "Pergunta do cliente: {{pergunta}}\nResposta:"
doc_to_target: "{{resposta_esperada}}"
generation_kwargs:
until: ["\n\n"]
max_gen_toks: 256
metric_list:
- metric: exact_match
aggregation: mean
higher_is_better: trueCria o dataset em formato JSONL, com um objeto por linha contendo os campos pergunta e resposta_esperada. Depois, corre o benchmark apontando para a pasta da tarefa:
lm_eval \
--model hf \
--model_args pretrained=meta-llama/Meta-Llama-3.1-8B-Instruct \
--tasks apoio_cliente_pt \
--include_path ./tarefas_personalizadas/ \
--output_path results/apoio-cliente/Esta é, na prática, a diferença entre um benchmark que impressiona num relatório e um benchmark que evita um modelo mau em produção: testar com os dados e o vocabulário reais do teu domínio, não só com perguntas de exame genéricas.
Um detalhe que costuma passar despercebido na primeira tentativa: o campo doc_to_text aceita a sintaxe de templates Jinja2, o que permite construir prompts condicionais bem mais complexos do que uma simples substituição de variável. Isto é útil quando o teu dataset tem exemplos de tamanhos ou formatos diferentes e precisas de ajustar o prompt consoante o caso, por exemplo incluindo ou omitindo um contexto adicional dependendo de o campo existir ou não no registo JSONL.
Passo 11: montar um projeto completo de benchmarking automatizado
Junta tudo o que viste até aqui num projeto reutilizável. A estrutura de pastas abaixo funciona como ponto de partida para qualquer equipa que precise de repetir estes testes sempre que sai um modelo novo.
benchmark-llm-projeto/
├── .venv/
├── lm-evaluation-harness/
├── tarefas_personalizadas/
│ └── apoio_cliente_pt.yaml
├── dados/
│ └── apoio_cliente_exemplos.jsonl
├── results/
│ ├── llama-3.1-8b/
│ ├── mistral-7b/
│ └── qwen2.5-7b/
├── comparar_modelos.sh
└── requirements.txtO ficheiro requirements.txt deve fixar as versões principais, para que o benchmark de hoje seja reprodutível daqui a seis meses:
lm-eval @ git+https://github.com/EleutherAI/[email protected]
torch>=2.3
vllm
accelerateCom este projeto pronto, avaliar um modelo novo passa a ser uma questão de acrescentar uma linha ao array MODELOS do script de comparação e voltar a correr, em vez de reconstruir o processo do zero de cada vez que aparece um lançamento.
Ferramentas complementares: OpenCompass, Chatbot Arena e LiveBench
O lm-evaluation-harness cobre bem os benchmarks académicos, mas não é a única peça do puzzle. Outras ferramentas ajudam a preencher lacunas que os testes automáticos não conseguem medir sozinhos, seja pela escala de modelos e datasets suportados, seja pelo tipo de sinal que recolhem (humano em vez de puramente estatístico).
O OpenCompass, mantido pela comunidade open-compass, funciona como uma plataforma “tudo-em-um” de avaliação, com suporte para modelos como Llama 3, Mistral, InternLM2, GPT-4, Qwen, GLM e Claude sobre mais de 100 datasets. A versão mais recente, 0.5.3, lançada a 29 de junho de 2026, trouxe suporte ao LongBenchv2, compatibilidade com modelos InternLM3 e uma reformulação da classe de modelo OpenAI. O repositório soma cerca de 7,2 mil estrelas no GitHub em 2026. Entre as funcionalidades mais recentes destaca-se o CascadeEvaluator, para encadear avaliações sequenciais, e o XFinder, uma ferramenta de pós-processamento que melhora a extração de respostas em tarefas de matemática e raciocínio. O OpenCompass suporta backends HuggingFace, vLLM e LMDeploy, além de avaliação por “LLM como juiz”.
A grande vantagem do OpenCompass sobre correr o harness sozinho é a gestão centralizada: em vez de escreveres um script de comparação como o do Passo 9, defines um único ficheiro de configuração com a lista de modelos e datasets, e a ferramenta trata do agendamento das execuções, incluindo a possibilidade de distribuir o trabalho por vários nós de um cluster. Para equipas que avaliam dezenas de modelos com regularidade (por exemplo, ao testar cada checkpoint de um processo de fine-tuning), esta gestão centralizada compensa a curva de aprendizagem adicional face ao harness sozinho.
O LMSYS Chatbot Arena (agora alojado em lmarena.ai) segue uma lógica diferente: em vez de métricas automáticas, usa votação humana às cegas entre respostas de dois modelos, o que o torna um dos benchmarks mais objetivos para qualidade conversacional. Na atualização de março de 2026 da Code Arena, o modelo chinês Kimi K2.5 alcançou o 9º lugar global com uma pontuação Elo de 1809, enquanto os modelos de topo pontuaram entre 1941 e 2002, uma diferença de 130 a 190 pontos Elo. Dados de abril de 2026 sobre o mesmo modelo mostram 76,8% no SWE-Bench Verified, 85,0% no LiveCodeBench e 50,2% no HLE com uso de ferramentas, o que ilustra como os benchmarks modernos já avaliam tarefas de engenharia de software reais, e não só perguntas de escolha múltipla.
Vale notar que uma pontuação Elo, ao contrário de uma percentagem de acerto do MMLU, só faz sentido em comparação relativa dentro do mesmo leaderboard e no mesmo período de tempo. Um Elo de 1809 hoje não é diretamente comparável a um Elo de 1809 medido seis meses antes, porque a base de modelos concorrentes muda constantemente. Isto reforça o mesmo princípio já visto no Passo 5 sobre o stderr: números isolados, sem contexto sobre como e quando foram medidos, dizem menos do que parecem dizer à primeira vista. Consultar a documentação de leaderboards da Hugging Face ajuda a perceber como cada plataforma normaliza os seus resultados antes de os publicar.
Quem já testou vários motores locais com o Promptfoo vai reconhecer a filosofia: nenhuma ferramenta isolada dá o quadro completo. O harness dá o rigor académico e a reprodutibilidade, o Chatbot Arena dá o sinal humano, e o OpenCompass junta ambos numa única plataforma de gestão.
| Ferramenta | Tipo de avaliação | Cobertura | Ponto forte |
|---|---|---|---|
| lm-evaluation-harness | Automática, académica | 60+ benchmarks, centenas de subtarefas | Padrão de facto, reprodutibilidade, plugins |
| OpenCompass | Automática, multi-modelo | 100+ datasets | Plataforma única para muitos modelos e backends |
| LMSYS Chatbot Arena | Votação humana às cegas | Conversação geral e código | Sinal humano real, difícil de manipular |
| Promptfoo | Testes funcionais e regressão | Casos de uso específicos e prompts próprios | Integração em pipelines de CI/CD |
Erros comuns ao fazer benchmark de LLMs
Estes são os erros que mais se veem em avaliações mal feitas, e que costumam levar a conclusões erradas sobre qual modelo é “melhor”. Nenhum destes problemas é exclusivo de principiantes: até equipas experientes voltam a cair neles quando têm pressa para publicar um número antes de um lançamento.
- Comparar modelos com números de few-shot diferentes. Um modelo avaliado com 5-shot e outro com 0-shot não são comparáveis, mesmo que a tarefa seja a mesma.
- Ignorar o stderr. Uma diferença de 1 ponto percentual dentro da margem de erro estatística não prova nada sobre qual modelo é superior.
- Usar só benchmarks académicos. MMLU e HellaSwag não dizem nada sobre como o modelo se comporta com os teus dados reais, no teu idioma e no teu domínio.
- Misturar versões de dataset. Atualizações silenciosas a tarefas (como as adicionadas em agosto de 2026) podem mudar ligeiramente os números entre execuções feitas em datas diferentes.
- Não fixar a semente aleatória (seed). Sem isso, repetir o mesmo benchmark duas vezes pode dar resultados ligeiramente diferentes, dificultando a deteção de regressões reais.
- Avaliar só a versão quantizada e assumir que representa o modelo completo. A quantização pode custar vários pontos percentuais em tarefas de raciocínio complexo.
- Publicar um único número sem contexto do hardware usado. O mesmo modelo, com backends diferentes (HuggingFace puro versus vLLM), pode produzir pequenas variações de precisão devido a diferenças de arredondamento numérico entre implementações.
Resolução de problemas: erros frequentes e soluções
Estes são os problemas mais reportados por quem começa a usar o harness, com a respetiva causa provável e a correção. Guarda esta lista à mão: a maioria destes erros aparece logo nas primeiras execuções, antes de o fluxo de trabalho estar bem rodado.
- Erro “CUDA out of memory”: reduz o
batch_sizedeautopara um número fixo (por exemplo, 4 ou 8) ou baixa ogpu_memory_utilizationno vLLM. - O comando
lm_evalnão é reconhecido: confirma que o ambiente virtual está ativo e que a instalação compip install -e .terminou sem erros. - Resultados de 0% de precisão numa tarefa: normalmente indica um problema no chat template ou na flag
--apply_chat_templateem falta, fazendo o modelo receber um prompt em formato errado. - Descarregamento de dataset falha com erro de rede: alguns datasets do HuggingFace Hub exigem autenticação. Corre
huggingface-cli loginantes de repetir o benchmark. - Avaliação extremamente lenta em CPU: é esperado. Modelos acima de 3B em CPU pura podem demorar horas por tarefa, e vale usar quantização GGUF via llama.cpp nesses casos.
- Erro de incompatibilidade de versão do PyTorch com o CUDA instalado: reinstala o PyTorch com o comando específico da tua versão de CUDA a partir do site oficial, em vez de usar o pip genérico.
- A tarefa personalizada não é encontrada: confirma que passaste corretamente a flag
--include_patha apontar para a pasta onde está o YAML. - Números diferentes em execuções repetidas do mesmo modelo: fixa a semente aleatória com
--seed 1234e desativa amostragem com temperatura, se a tarefa permitir controlo desse parâmetro. - O processo trava sem mensagem de erro clara ao carregar um modelo grande: normalmente falta de RAM do sistema (não confundir com VRAM da GPU) durante o carregamento inicial dos pesos. Fecha outras aplicações pesadas ou usa a flag
low_cpu_mem_usage=Truenosmodel_args.
Dicas avançadas para resultados mais fiáveis
Depois do básico a funcionar, estas práticas separam um benchmark amador de um relatório que resiste a escrutínio técnico.
Corre cada configuração pelo menos duas vezes com seeds diferentes e reporta a média com o desvio padrão, não apenas um único número. Usa sempre o mesmo hardware e a mesma versão do harness ao comparar modelos ao longo do tempo, já que atualizações ao motor de avaliação (como as adicionadas na v0.4.13) podem alterar ligeiramente como os prompts são construídos. Guarda os ficheiros JSON de resultados num repositório versionado, junto com o commit exato do harness usado, para conseguires justificar um número seis meses depois se alguém questionar. Por fim, combina sempre pelo menos um benchmark automático com uma amostra de avaliação humana manual: mesmo 20 a 30 exemplos revistos à mão costumam revelar problemas que nenhuma métrica automática apanha, como respostas gramaticalmente corretas mas factualmente erradas.
Se trabalhas com modelos quantizados através do llama.cpp, vale a pena correr o mesmo conjunto de benchmarks na versão original em FP16 e na versão quantizada, para documentares exatamente quanta precisão perdes em troca da poupança de memória. Essa diferença costuma variar bastante consoante a tarefa: raciocínio matemático tende a sofrer mais com a quantização do que classificação de texto simples.
Uma última prática que compensa em equipas maiores é automatizar o benchmark como parte do próprio pipeline de integração contínua, correndo o script de comparação sempre que um novo checkpoint de fine-tuning é publicado. Isto transforma o benchmark de uma tarefa manual, feita “quando alguém se lembra”, num controlo de qualidade automático que bloqueia a promoção de um modelo para produção se a pontuação cair abaixo de um limiar definido. Basta adicionar o script comparar_modelos.sh a um passo do teu workflow de CI, comparando o JSON de saída com o resultado da versão anterior e falhando o build se a diferença ultrapassar, por exemplo, dois pontos percentuais em qualquer tarefa crítica.
Perguntas frequentes
O lm-evaluation-harness funciona sem GPU?
Sim, mas com limitações. Em CPU pura consegues avaliar modelos pequenos (até 1-3 mil milhões de parâmetros) em tempo razoável. Para modelos maiores, o tempo de execução torna-se impraticável e vale mais a pena usar uma versão quantizada em GGUF ou avaliar via API, como mostrado no Passo 7.
Quanto tempo demora um benchmark completo?
Depende do modelo, do hardware e do número de tarefas. Um modelo de 7-8 mil milhões de parâmetros numa GPU de 24 GB com vLLM costuma demorar entre 20 minutos e 1 hora para as três tarefas do Passo 4. Sem GPU, o mesmo processo pode facilmente ultrapassar as 6 horas.
Posso usar o harness para avaliar modelos em português?
Sim. A maioria das tarefas nativas está em inglês, mas o formato de tarefa personalizada em YAML mostrado no Passo 10 permite criar benchmarks inteiramente em português, com o teu próprio dataset e vocabulário.
Qual a diferença entre o lm-evaluation-harness e o OpenCompass?
O harness é mais leve e focado em reprodutibilidade académica, com forte adoção em leaderboards da comunidade. O OpenCompass funciona como uma plataforma mais ampla, com gestão de múltiplos modelos e datasets numa única interface e ferramentas de pós-processamento como o XFinder. Muitas equipas usam os dois em conjunto.
É preciso criar conta ou pagar para usar o lm-evaluation-harness?
Não. É um projeto open-source e gratuito. Os únicos custos possíveis vêm do hardware que usas (GPU própria ou alugada na nuvem) ou de créditos de API, caso avalies modelos comerciais em vez de modelos locais.
Os resultados do harness coincidem sempre com os leaderboards públicos?
Aproximam-se, mas não são garantidamente idênticos. Pequenas diferenças na versão do harness, no número de few-shot ou no template de chat usado podem alterar os números em um ou dois pontos percentuais. Por isso é boa prática documentar sempre a versão exata usada, como referido nas dicas avançadas. Se o objetivo é publicar um número para comparação pública, o mais seguro é replicar exatamente a metodologia descrita pelo leaderboard de referência, incluindo o mesmo número de few-shot e o mesmo template de prompt.
Vale a pena usar o Chatbot Arena em vez de benchmarks automáticos?
Não é “em vez de”, é complementar. O Chatbot Arena capta preferências humanas em conversação livre, algo que o MMLU ou o HellaSwag não medem. Para uma avaliação completa, o ideal é cruzar os dois tipos de sinal, como descrito na secção sobre ferramentas complementares.
