Treinar ou escolher um modelo de linguagem é hoje a parte fácil. A parte difícil é saber se ele realmente funciona bem no que precisas dele para fazer, sem depender da palavra do fabricante. É exactamente esse o problema que o Lighteval, da Hugging Face, veio resolver: um conjunto de ferramentas open source que corre mais de 1000 testes padronizados contra qualquer modelo, esteja ele a correr localmente, numa GPU da tua empresa ou atrás de uma API paga. Neste tutorial mostramos, passo a passo, como instalar o Lighteval na versão 0.13.0, correr a primeira avaliação em minutos e construir um pipeline completo que qualquer equipa de engenharia ou segurança pode usar antes de pôr um modelo em produção. Este guia complementa outros artigos do hub de Inteligência Artificial do shattered.io, incluindo o nosso tutorial sobre o LM-Evaluation-Harness e o guia do Garak para testar a segurança de modelos. Toda a informação técnica deste artigo foi confirmada na documentação oficial do Lighteval e no repositório público do projecto.
O que é o Lighteval e porque a avaliação de LLMs importa agora
O Lighteval é mantido pela equipa de Leaderboard e Evals da Hugging Face, a mesma equipa por trás do Open LLM Leaderboard. Segundo a descrição oficial do repositório no GitHub, a ferramenta funciona como “your all-in-one toolkit for evaluating LLMs across multiple backends”, ou seja, um kit único para avaliar modelos independentemente de onde estejam a correr. O projecto nasceu em Janeiro de 2024 e já soma 2.540 estrelas e 554 forks no GitHub, com 409 issues abertas, um sinal de comunidade activa em vez de projecto abandonado. A licença é MIT, o que facilita o uso em produtos comerciais sem restrições pesadas.
A ficha de citação oficial do projecto, disponível no próprio repositório, credita o desenvolvimento a Nathan Habib, Clémentine Fourrier, Hynek Kydlíček, Thomas Wolf e Lewis Tunstall, todos ligados à equipa de investigação da Hugging Face. A versão actual, a 0.13.0, é já a 22ª publicada no PyPI desde o lançamento inicial, o que mostra um ritmo de actualização constante em vez de um projecto que ficou parado depois do anúncio inicial.
A razão para isto interessar em 2026 é simples: as equipas já não escolhem um único modelo e ficam com ele para sempre. Trocam de fornecedor, testam versões open source contra APIs pagas e precisam de números comparáveis para justificar essa escolha ao resto da empresa. Sem uma ferramenta de avaliação, essa comparação acaba por se basear em impressões subjectivas, o que é um risco tanto técnico como orçamental. O Lighteval resolve isto ao dar acesso a mais de 1000 tarefas de avaliação prontas a usar, cobrindo conhecimento geral, matemática, código, raciocínio e línguas diferentes do inglês.
Há ainda uma pressão adicional a empurrar equipas europeias nesta direcção: o enquadramento regulatório à volta da IA na União Europeia começou a exigir documentação e transparência sobre o comportamento de sistemas de IA, um tema que já cobrimos no artigo sobre a transparência exigida pelo AI Act. Ter um histórico de avaliações, com data, versão do modelo e pontuação obtida, deixou de ser um exercício apenas técnico para passar a ser também um activo de conformidade, útil sempre que um cliente empresarial ou um auditor perguntar como é que um determinado modelo foi validado antes de entrar em produção.
Casos de uso reais: quando vale a pena avaliar um modelo
Antes de entrar na parte técnica, vale a pena situar quando é que este trabalho compensa. O cenário mais comum é a troca de fornecedor: uma equipa que usa uma API paga há um ano quer perceber se um modelo open source recente já chega ao mesmo nível de qualidade, a um custo muito menor por token. Sem números comparáveis, essa decisão fica reduzida a “parece que responde bem”, o que não convence um director financeiro nem sobrevive a uma auditoria interna.
Outro cenário frequente acontece depois de um fine-tuning. A equipa ajusta um modelo aos dados da empresa e precisa de confirmar duas coisas ao mesmo tempo: se a nova versão melhorou mesmo na tarefa-alvo e se não piorou noutras capacidades gerais, um efeito conhecido como esquecimento catastrófico. Correr o mesmo conjunto de benchmarks antes e depois do fine-tuning, como descrevemos no artigo sobre fine-tuning de LLMs com Hugging Face, é a única forma fiável de apanhar essa regressão antes dos utilizadores finais.
Há ainda um terceiro caso, cada vez mais relevante para empresas que operam na União Europeia: documentar o desempenho de um modelo como parte da conformidade regulatória. Ter relatórios de avaliação guardados, com data e versão do modelo, ajuda a demonstrar diligência técnica caso um regulador ou um cliente empresarial peça essa informação.
Pré-requisitos: o que precisas antes de começar
Antes de instalar seja o que for, vale a pena confirmar que o teu ambiente cumpre os requisitos mínimos. O Lighteval assume Python 3.10 ou superior e, segundo a documentação, ainda não tem suporte testado para Windows, funcionando de forma fiável apenas em Mac e Linux. Se trabalhas em Windows, corre tudo dentro do WSL2.
| Requisito | Versão mínima | Finalidade |
|---|---|---|
| Python | 3.10 ou superior | Ambiente de execução do Lighteval |
| pip | Versão recente | Instalação do pacote e extras |
| Sistema operativo | macOS ou Linux | Windows não é suportado oficialmente |
| Conta Hugging Face | Gratuita | Autenticação e publicação de resultados |
| GPU (opcional) | CUDA compatível | Acelerar avaliações com Accelerate ou vLLM |
Não precisas de GPU para começar. É possível correr avaliações contra modelos servidos remotamente através de APIs, o que significa que o primeiro teste deste tutorial pode ser feito num portátil comum, sem placa gráfica dedicada. A GPU só se torna relevante quando quiseres avaliar modelos carregados localmente, algo que também cobrimos mais à frente.
Passo 1 – Instala o Lighteval
Cria primeiro um ambiente virtual limpo, para não misturares dependências com outros projectos Python que já tenhas no computador. Depois instala o pacote base a partir do PyPI, onde o Lighteval já vai na sua 22ª versão publicada, culminando na 0.13.0 actual.
python3 -m venv lighteval-env
source lighteval-env/bin/activate
pip install --upgrade pip
pip install lightevalEsta instalação base já permite avaliar modelos servidos remotamente. Se quiseres correr modelos localmente com Accelerate, vLLM ou SGLang, instala os extras correspondentes. Cada um traz dependências pesadas, por isso só instales o que realmente vais usar.
pip install "lighteval[accelerate]"
pip install "lighteval[vllm]"Confirma que a instalação correu bem executando o comando de ajuda. Se aparecer a lista de subcomandos disponíveis (eval, accelerate, vllm, sglang, endpoint, custom), está tudo pronto para o próximo passo. Repara que os extras de vLLM e SGLang trazem consigo bibliotecas de baixo nível pesadas, incluindo compiladores CUDA, o que pode adicionar vários gigabytes ao teu ambiente virtual. Se só precisas de avaliar modelos através de endpoints remotos, fica-te pela instalação base e poupa esse espaço em disco.
lighteval --helpPasso 2 – Autentica-te na Hugging Face Hub
Muitos benchmarks (como o GPQA ou variantes do MMLU) estão hospedados como datasets privados ou de acesso condicionado na Hugging Face Hub, e publicar os teus próprios resultados também exige uma conta autenticada. Cria um token de acesso na tua conta Hugging Face e autentica-te pela linha de comandos.
hf auth loginO terminal vai pedir o token. Cola-o e confirma. A partir daqui o Lighteval consegue descarregar datasets protegidos e, mais tarde, enviar os teus relatórios de avaliação directamente para o teu perfil ou para uma organização na Hub, o que facilita partilhar resultados com o resto da equipa sem andar a copiar ficheiros JSON manualmente. Se trabalhas numa equipa, cria o token com o âmbito mais restrito que a tarefa permitir, e evita reutilizar o mesmo token pessoal em vários projectos diferentes.
Passo 3 – Corre a primeira avaliação com um endpoint remoto
A forma mais rápida de ver o Lighteval em acção é apontá-lo a um modelo já disponível através dos fornecedores de inferência da Hugging Face, sem descarregar um único ficheiro de pesos. O comando abaixo avalia um modelo open source contra o benchmark GPQA Diamond, uma das tarefas de raciocínio mais exigentes disponíveis.
lighteval eval "hf-inference-providers/openai/gpt-oss-20b" gpqa:diamondO subcomando eval usa a biblioteca inspect-ai como motor por defeito, uma escolha da própria equipa da Hugging Face por ser mais simples de configurar do que os motores locais. Em poucos minutos, o terminal mostra uma tabela com a pontuação obtida, o tempo de execução e o número de amostras processadas. Guarda este resultado como referência antes de avançares para benchmarks mais específicos.
Passo 4 – Escolhe os benchmarks certos para o teu caso
Com mais de 1000 tarefas disponíveis, escolher o benchmark errado é fácil e desperdiça tempo de computação. A Hugging Face disponibiliza um índice de benchmarks pesquisável onde consegues filtrar por domínio e língua antes de decidires o que correr.
Antes de escolheres, vale a pena perceber a notação usada nos comandos deste tutorial: tarefa|shots|truncar. O número de “shots” indica quantos exemplos resolvidos são mostrados ao modelo antes da pergunta real, uma técnica chamada few-shot prompting. Zero shots testa a capacidade do modelo sem qualquer ajuda de contexto, enquanto cinco shots mede o desempenho quando o modelo tem exemplos para se guiar. Nenhuma das duas abordagens é “mais correcta”, mas precisas de manter a mesma configuração ao comparares dois modelos, ou o resultado deixa de ser comparável.
- Conhecimento geral: MMLU, MMLU-Pro, MMMU, BIG-Bench
- Matemática: GSM8K, MATH500, AIME24 e AIME25 para matemática de competição
- Código: LiveCodeBench (LCB)
- Seguir instruções: IFEval e a variante IFEval-fr
- Multilingue: XTREME, Flores200 (cobre 200 línguas), XCOPA, XQuAD
Se a tua equipa trabalha sobretudo em português, repara que o suporte multilingue nativo do Lighteval ainda é mais forte em francês, alemão e chinês do que em português europeu, algo a ter em conta ao escolher entre correr um benchmark existente ou construir um personalizado, tema que retomamos no Passo 10. Para quem já testou o FUSE Benchmark ou outras baterias de segurança, o Lighteval funciona bem como complemento, cobrindo qualidade técnica em vez de comportamento de risco.
Passo 5 – Avalia um modelo já carregado em memória com a API Python
Quando o modelo já está carregado no teu próprio código, por exemplo depois de um fine-tuning, não faz sentido exportá-lo para um endpoint só para o avaliar. O Lighteval expõe uma API Python que aceita directamente um objecto já instanciado da biblioteca Transformers.
from transformers import AutoModelForCausalLM
from lighteval.logging.evaluation_tracker import EvaluationTracker
from lighteval.models.transformers.transformers_model import TransformersModel, TransformersModelConfig
from lighteval.pipeline import ParallelismManager, Pipeline, PipelineParameters
MODEL_NAME = "meta-llama/Meta-Llama-3-8B-Instruct"
BENCHMARKS = "gsm8k"
evaluation_tracker = EvaluationTracker(output_dir="./results")
pipeline_params = PipelineParameters(launcher_type=ParallelismManager.NONE, max_samples=2)
model = AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map="auto")
config = TransformersModelConfig(model_name=MODEL_NAME, batch_size=1)
model = TransformersModel.from_model(model, config)
pipeline = Pipeline(
model=model,
pipeline_parameters=pipeline_params,
evaluation_tracker=evaluation_tracker,
tasks=BENCHMARKS,
)
results = pipeline.evaluate()
pipeline.show_results()
results = pipeline.get_results()Repara no parâmetro max_samples=2. Serve para correr um teste rápido com apenas duas amostras antes de lançares a avaliação completa, que pode levar de minutos a horas dependendo do benchmark e do tamanho do modelo. É uma prática que recomendamos sempre antes de qualquer avaliação em larga escala, para apanhar erros de configuração cedo.
Passo 6 – Avalia com Accelerate em CPU ou GPU
Para quem não quer escrever código Python e prefere a linha de comandos, o subcomando accelerate usa a biblioteca Accelerate da própria Hugging Face para distribuir a avaliação por uma ou várias GPUs, ou correr em CPU quando não há placa gráfica disponível.
lighteval accelerate \
"model_name=meta-llama/Meta-Llama-3-8B-Instruct" \
"mmlu|0|0,gsm8k|0|0" \
--output-dir ./resultadosA sintaxe tarefa|shots|truncar permite encadear várias tarefas no mesmo comando, separadas por vírgula, o que evita ter de correr o processo de arranque do modelo várias vezes. Este é o caminho mais usado em ambientes empresariais que já têm GPUs próprias e não querem depender de um fornecedor externo de inferência para os testes.
Passo 7 – Avalia em lote com vLLM
Quando o volume de avaliações cresce, por exemplo ao testar um modelo contra centenas de tarefas em simultâneo, o motor Accelerate torna-se lento. É aqui que entra o vLLM, um motor de inferência optimizado para débito elevado, já coberto no nosso guia sobre vLLM com Docker para o DeepSeek V4 Flash.
lighteval vllm \
"model_name=Qwen/Qwen2.5-7B-Instruct,dtype=bfloat16" \
"gsm8k|0|0,ifeval|0|0" \
--output-dir ./resultadosNos testes internos que a comunidade partilha em fóruns e repositórios, o motor vLLM costuma reduzir substancialmente o tempo total de avaliação em lotes grandes, por processar vários pedidos em paralelo dentro da mesma GPU. Se já usas vLLM para servir modelos em produção, reaproveitar o mesmo motor para avaliação evita manter duas pilhas de inferência diferentes.
Passo 8 – Lê e interpreta os resultados
Cada avaliação gera dois tipos de ficheiro dentro da pasta de output: um resumo agregado com a pontuação final por tarefa e métrica, e um ficheiro detalhado amostra-a-amostra, que mostra exactamente o que o modelo respondeu a cada pergunta e porque foi considerado correcto ou incorrecto. É este segundo ficheiro que costuma revelar os problemas reais, como um modelo que acerta a resposta mas falha no formato exigido pelo parser automático.
O EvaluationTracker grava tudo em formato estruturado, pronto a ser carregado com pandas ou qualquer outra ferramenta de análise. Antes de tirares conclusões de um resultado isolado, compara sempre com pelo menos um segundo modelo na mesma tarefa. Um número absoluto, como “62% no MMLU”, diz pouco sozinho, mas torna-se útil assim que colocado lado a lado com a alternativa que estás a considerar substituir.
Quanto tempo e recursos consome uma avaliação
Uma dúvida frequente de quem experimenta o Lighteval pela primeira vez é quanto tempo vai realmente demorar. A resposta depende de quatro factores que se multiplicam entre si: o tamanho do modelo, o número de amostras do benchmark, o motor de inferência escolhido e o hardware disponível. Um teste rápido com max_samples=2 contra um endpoint remoto, como o do Passo 5, costuma terminar em segundos. Já uma bateria completa de vários benchmarks grandes, como o MMLU-Pro combinado com o GSM8K inteiro, pode levar de dezenas de minutos a várias horas, especialmente correndo num único GPU de gama média com o motor Accelerate.
É por isso que recomendamos sempre começar pequeno. Corre primeiro uma amostra reduzida para confirmar que o prompt está bem formatado e que a métrica escolhida faz sentido para a tarefa, só depois lanças a avaliação completa. Esta sequência evita o cenário mais frustrante: descobrir, três horas depois, que um erro de configuração básico invalidou todo o processo. Se o tempo continuar a ser um obstáculo mesmo depois de optimizado, o motor vLLM do Passo 7 costuma ser o próximo passo lógico, por processar vários pedidos em paralelo em vez de um de cada vez.
Passo 9 – Publica os resultados no Hugging Face Hub
Depois de autenticado (Passo 2), podes configurar o EvaluationTracker para enviar automaticamente os relatórios para um repositório na Hugging Face Hub, público ou privado. Isto é particularmente útil em equipas distribuídas, onde nem todos têm acesso à mesma máquina que correu a avaliação.
from lighteval.logging.evaluation_tracker import EvaluationTracker
evaluation_tracker = EvaluationTracker(
output_dir="./resultados",
push_to_hub=True,
hub_results_org="a-tua-organizacao"
)A partir daí, qualquer colega com acesso ao repositório consegue ver a evolução das pontuações ao longo do tempo, algo essencial quando estás a comparar várias versões do mesmo modelo depois de sucessivas rondas de fine-tuning, um fluxo que descrevemos com mais detalhe no artigo sobre fine-tuning de LLMs com Hugging Face.
Passo 10 – Cria tarefas e métricas personalizadas
Os benchmarks públicos raramente reflectem o caso de uso exacto de uma empresa. Se o teu produto responde a perguntas sobre facturas ou contratos em português, nenhum dos 1000+ benchmarks prontos vai medir isso com precisão. O Lighteval permite criar tarefas e métricas próprias sem alterar o código-fonte da ferramenta.
Cria uma tarefa personalizada
Uma tarefa personalizada é essencialmente um ficheiro Python que define como carregar o teu dataset, como formatar a pergunta enviada ao modelo e que métrica usar para avaliar a resposta.
from lighteval.tasks.lighteval_task import LightevalTaskConfig
from lighteval.tasks.requests import Doc
def prompt_fn(line, task_name: str = None):
return Doc(
task_name=task_name,
query=f"Pergunta: {line['pergunta']}\nResposta:",
choices=[line["resposta_correta"]],
gold_index=0,
)
minha_tarefa = LightevalTaskConfig(
name="faturas-pt",
prompt_function=prompt_fn,
hf_repo="a-tua-organizacao/dataset-faturas-pt",
hf_subset="default",
metric=["exact_match"],
evaluation_splits=["test"],
)Cria uma métrica personalizada
Se a métrica exact_match for demasiado rígida, por exemplo porque aceitas pequenas variações de formatação numérica, podes escrever a tua própria função de pontuação e registá-la no Lighteval, seguindo o guia oficial de métricas personalizadas. Isto evita falsos negativos em que o modelo acertou mas foi penalizado por uma diferença cosmética na resposta, um problema comum quando se avalia geração de texto livre em vez de escolha múltipla.
Passo 11 – Automatiza avaliações num pipeline CI/CD
Correr avaliações manualmente funciona para experiências pontuais, mas uma equipa séria de MLOps quer estes testes a correr sempre que há uma alteração ao prompt de sistema, ao modelo base ou aos dados de fine-tuning. A forma mais simples de o fazer é integrar o Lighteval num workflow de GitHub Actions.
name: avaliacao-llm
on:
pull_request:
paths:
- "modelo/**"
jobs:
avaliar:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.11"
- run: pip install lighteval
- run: |
lighteval eval \
"hf-inference-providers/a-tua-organizacao/modelo-candidato" \
"gsm8k|0|0,ifeval|0|0" \
--output-dir ./resultados-ciCom isto, cada pull request que altera o modelo dispara automaticamente uma bateria de testes, e a equipa vê a pontuação directamente no relatório do CI antes de aprovar o merge. É o mesmo princípio de “shift-left” que já se aplica a testes de segurança de código, agora aplicado à qualidade dos modelos.
Passo 12 – Projeto completo: pipeline de avaliação ponta a ponta
Juntando tudo o que vimos até aqui, o projecto completo tem esta estrutura de pastas. Serve como ponto de partida real, não apenas como exemplo isolado.
avaliacao-llm/
├── .github/workflows/avaliacao-llm.yml
├── tarefas/
│ └── faturas_pt.py
├── scripts/
│ ├── avaliar_local.py
│ └── avaliar_remoto.sh
├── resultados/
└── requirements.txtO ficheiro requirements.txt fixa a versão exacta usada em produção, para evitar que uma actualização silenciosa do Lighteval mude os resultados sem aviso.
lighteval[accelerate,vllm]==0.13.0
transformers>=4.44
torch>=2.3O script avaliar_remoto.sh corre os testes rápidos contra um endpoint, útil para verificações diárias automáticas, enquanto o avaliar_local.py usa a API Python do Passo 5 para avaliações mais profundas em modelos já carregados localmente, tipicamente disparadas antes de uma release. Com este esqueleto, uma equipa pequena consegue ter avaliação contínua de modelos a funcionar em menos de uma tarde de trabalho.
Antes de ligares este pipeline ao GitHub Actions do Passo 11, corre-o localmente pelo menos uma vez de ponta a ponta. Confirma que a pasta resultados/ fica com os ficheiros esperados, que o script remoto não depende de segredos que só existem na tua máquina, e que o token usado no hf auth login tem as permissões certas. É muito mais simples depurar um pipeline destes no teu terminal do que a ler logs de um runner remoto que falhou a meio da noite.
Erros comuns ao usar o Lighteval
A maioria dos problemas reportados por quem começa a usar o Lighteval não vem de bugs na ferramenta, mas de suposições erradas sobre como um benchmark deve ser configurado. Antes de abrires uma issue no GitHub, vale a pena confirmar se o teu caso não se encaixa numa destas situações, todas evitáveis com um pouco de atenção à configuração inicial.
- Correr o dataset completo logo à primeira: sem usar
max_samplespara um teste rápido, um erro de configuração só aparece depois de a avaliação inteira terminar, desperdiçando tempo de GPU. - Ignorar o aviso sobre Windows: instalar directamente no Windows sem WSL2 costuma gerar erros de dependências nativas difíceis de depurar.
- Misturar extras a mais: instalar
accelerate,vllmesglangao mesmo tempo sem necessidade aumenta o risco de conflitos de versões entre bibliotecas de baixo nível como o CUDA toolkit. - Comparar pontuações de benchmarks diferentes: um MMLU de 0-shot não é comparável a um MMLU de 5-shot. Confirma sempre a configuração de “shots” antes de comparares dois modelos.
- Esquecer a autenticação antes de correr benchmarks protegidos: tarefas como o GPQA exigem acesso a datasets com condições de uso, e sem
hf auth logina avaliação falha a meio, depois de já ter gasto tempo de computação.
Resolução de problemas
A tabela seguinte junta os problemas mais reportados por quem começa a usar o Lighteval, com a causa mais provável e a correcção recomendada. Guarda-a como referência rápida para a próxima vez que uma avaliação falhar a meio, em vez de teres de procurar a resposta de raiz cada vez que o erro aparece.
| Sintoma | Causa provável | Como resolver |
|---|---|---|
| Erro “gated dataset” ao carregar uma tarefa | Não autenticaste com a Hugging Face Hub | Corre hf auth login e aceita os termos do dataset na página da Hub |
| Instalação falha em Windows | Dependências nativas sem suporte oficial | Usa WSL2 com Ubuntu ou uma máquina Linux/macOS |
| Erro de memória CUDA (OOM) | Batch size demasiado alto para a GPU disponível | Reduz o batch_size na configuração do modelo ou usa quantização |
| Avaliação extremamente lenta | A usar o motor Accelerate para lotes muito grandes | Muda para o motor vLLM, optimizado para débito elevado |
| Pontuação zero inesperada numa tarefa | Formato de prompt incompatível com o parser da métrica | Inspeciona o ficheiro de resultados amostra-a-amostra para ver a resposta bruta do modelo |
| Erro ao publicar resultados na Hub | Token sem permissão de escrita ou organização errada | Gera um novo token com permissão de escrita e confirma o nome da organização |
| Conflito de dependências no pip | Vários extras instalados em simultâneo (accelerate + vllm + sglang) | Usa ambientes virtuais separados por motor de inferência |
| Tarefa personalizada não é reconhecida | Caminho do ficheiro Python não foi passado correctamente ao comando | Confirma que o parâmetro --custom-tasks aponta para o ficheiro certo |
Dicas avançadas para equipas de segurança e MLOps
Para além do uso básico, há práticas que fazem a diferença quando a avaliação de modelos passa a ser parte do processo de produção e não apenas uma experiência isolada. A primeira é versionar os resultados junto com o código do modelo, não apenas guardá-los numa pasta solta, para conseguires responder facilmente à pergunta “este modelo ficou pior depois de que alteração?”.
A segunda é combinar o Lighteval com ferramentas de segurança dedicadas em vez de o tratar como suficiente sozinho. O Lighteval mede qualidade e capacidade, não comportamento malicioso. Para isso, vale a pena olhar para o Garak, focado em vulnerabilidades de segurança, ou para o Promptfoo, mais orientado a testes de prompts em produção. Os três resolvem problemas diferentes e complementam-se bem num pipeline maduro.
A terceira dica é usar o parâmetro de amostragem para controlar custos. Avaliações completas em benchmarks grandes como o MMLU-Pro podem levar horas e custar dinheiro real em créditos de inferência quando corridas contra endpoints pagos. Correr primeiro com uma amostra de 10% do dataset dá uma estimativa fiável da pontuação final, suficiente para decisões rápidas sobre se vale a pena continuar a investigar determinado modelo.
A quarta dica, menos óbvia mas igualmente importante, é documentar a configuração exacta usada em cada avaliação junto com o resultado, não só o número final. Guarda a versão do Lighteval, a lista de tarefas, o número de shots e o motor de inferência usados, de preferência no mesmo commit onde guardas o relatório de resultados. Seis meses depois, quando alguém perguntar porque é que a pontuação de um modelo mudou, essa informação evita ter de reconstruir tudo de memória, ou pior, concluir erradamente que um modelo piorou quando na verdade a configuração da avaliação é que mudou.
Segurança e privacidade dos dados durante a avaliação
Um detalhe que passa despercebido a muitas equipas: avaliar um modelo através de um endpoint remoto significa enviar as perguntas do benchmark, e por vezes dados internos usados em tarefas personalizadas, para um servidor de terceiros. Se estiveres a testar uma tarefa personalizada construída a partir de documentos reais da empresa, como o exemplo de facturas do Passo 10, essa informação sai da tua infraestrutura sempre que uses o subcomando eval contra um fornecedor externo.
Para dados sensíveis, sujeitos ao RGPD ou a cláusulas contratuais de confidencialidade, a alternativa mais segura é manter tudo dentro da tua própria infraestrutura, usando os motores Accelerate ou vLLM descritos nos Passos 6 e 7, que correm inteiramente em máquinas que controlas. Nenhum dado sai da rede da empresa, o que também simplifica a resposta a pedidos de auditoria sobre onde a informação foi processada.
Vale também a pena separar claramente ambientes de avaliação com dados reais de clientes dos ambientes usados só com benchmarks públicos. Misturar os dois num único script aumenta o risco de um dataset sensível acabar publicado sem querer, por exemplo ao correr o Passo 9 e enviar resultados para um repositório da Hugging Face Hub configurado como público em vez de privado.
Uma boa prática adicional é tratar os ficheiros de resultados amostra-a-amostra do Passo 8 com o mesmo cuidado que dás a logs de aplicação. Se o benchmark personalizado incluir excertos de conversas reais com clientes, esses ficheiros passam a conter dados pessoais, e devem seguir a mesma política de retenção e acesso que já aplicas a outros registos com informação identificável, em vez de ficarem esquecidos numa pasta local sem controlo de acesso.
Lighteval, LM-Evaluation-Harness e Promptfoo: como se distinguem
É comum a confusão entre estas três ferramentas, porque todas lidam com testar modelos de IA. Na prática, cada uma tem um foco diferente. O LM-Evaluation-Harness, da EleutherAI, foi uma das primeiras bibliotecas do género e continua a ser referência em benchmarks académicos clássicos. O próprio README do Lighteval reconhece o LM-Evaluation-Harness e o HELM da Universidade de Stanford como fontes de inspiração directa para o seu desenho.
O Lighteval diferencia-se por integrar nativamente múltiplos motores de inferência (Accelerate, vLLM, SGLang, Nanotron e inspect-ai) sob uma única interface, e por ligar-se directamente ao ecossistema da Hugging Face Hub para publicar resultados. Já o Promptfoo foca-se menos em benchmarks académicos e mais em testes de regressão de prompts e comparação entre fornecedores de API em cenários do dia a dia de produto. Escolher entre eles depende do objectivo: pesquisa e comparação técnica rigorosa apontam para o Lighteval, enquanto testes rápidos de prompt em produção encaixam melhor no Promptfoo.
Na prática, muitas equipas maduras acabam por usar mais do que uma destas ferramentas ao mesmo tempo, cada uma numa fase diferente do ciclo de vida do modelo. O Lighteval entra na fase de selecção e validação técnica, antes de um modelo ser aprovado para produção. O Promptfoo entra depois, já com o modelo escolhido, para garantir que alterações a prompts ou a versões da API não introduzem regressões silenciosas. Tratá-las como concorrentes directas, em vez de complementares, é um erro de avaliação tão comum quanto os listados mais acima neste artigo.
| Ferramenta | Foco principal | Motores suportados | Melhor para |
|---|---|---|---|
| Lighteval | Benchmarks académicos e técnicos | Accelerate, vLLM, SGLang, Nanotron, inspect-ai | Comparar capacidade real entre modelos |
| LM-Evaluation-Harness | Benchmarks académicos clássicos | Transformers, vLLM, APIs | Reprodutibilidade em investigação |
| Promptfoo | Testes de prompts e regressão | APIs de múltiplos fornecedores | QA contínuo de produtos em produção |
Alternativas ao Lighteval: quando talvez não seja a ferramenta certa
Nenhuma ferramenta serve todos os casos, e vale a pena dizer isto com clareza antes de terminares este tutorial. Se a tua equipa já tem um pipeline maduro construído em cima do LM-Evaluation-Harness, com tarefas personalizadas escritas e testadas ao longo de meses, migrar tudo para o Lighteval só por ser mais recente raramente compensa o esforço. A regra geral é simples: troca de ferramenta quando o problema que tens hoje é difícil de resolver com o que já usas, não porque uma alternativa parece tecnicamente mais elegante numa demonstração.
Da mesma forma, se o que precisas é testar como um chatbot em produção reage a variações de um prompt específico, ou comparar latência e custo entre fornecedores de API em cenários do dia a dia, o Promptfoo resolve isso de forma mais directa, sem exigires a configuração de tarefas académicas. O Lighteval brilha sobretudo quando precisas de números comparáveis contra benchmarks reconhecidos pela comunidade científica, algo que um teste de regressão de prompts não substitui.
Perguntas frequentes
O Lighteval é gratuito?
Sim. É um projecto open source sob licença MIT, gratuito para uso pessoal e comercial. Os únicos custos possíveis vêm da infraestrutura que usas para correr as avaliações, como GPU alugada na nuvem ou créditos de API de terceiros.
Preciso de GPU para usar o Lighteval?
Não, se avaliares modelos através de um endpoint remoto com o subcomando eval. A GPU só é necessária quando avalias modelos carregados localmente com Accelerate ou vLLM.
O Lighteval funciona em Windows?
Não de forma oficialmente suportada. A documentação avisa que a ferramenta está completamente por testar no Windows. A recomendação é usar WSL2 com Ubuntu ou correr directamente em Linux ou macOS.
Qual a diferença entre o Lighteval e o Open LLM Leaderboard?
O Open LLM Leaderboard é uma tabela pública construída pela Hugging Face para comparar modelos submetidos pela comunidade. O Lighteval é a ferramenta que corre por trás desse leaderboard, mas também podes usá-la de forma totalmente privada, sem submeter nada a um ranking público.
Consigo avaliar modelos em português com o Lighteval?
Sim, através de benchmarks multilingues como o Flores200 e o XQuAD, ou criando uma tarefa personalizada com o teu próprio dataset em português, seguindo o exemplo do Passo 10 deste tutorial.
O Lighteval substitui testes de segurança de IA?
Não. O Lighteval mede qualidade técnica e capacidade do modelo, não comportamento adversário. Para segurança, combina-o com ferramentas dedicadas como o Garak, mencionado no artigo sobre testes de segurança de modelos de IA.
Quantas tarefas de avaliação estão disponíveis?
Mais de 1000, segundo a documentação oficial, cobrindo conhecimento geral, matemática, código, raciocínio, diálogo e línguas diferentes do inglês, pesquisáveis através do índice de benchmarks da Hugging Face.
Como escolho entre os diferentes motores de inferência do Lighteval?
Para testes rápidos sem infraestrutura própria, usa o subcomando eval contra um endpoint remoto. Para avaliações locais em GPU própria com poucos modelos, o Accelerate chega. Para lotes grandes ou avaliações frequentes em produção, o vLLM oferece melhor débito.
