lm-evaluation-harness - Benchmarking de LLM

Início rápido

lm-evaluation-harness avalia LLMs em mais de 60 benchmarks acadêmicos usando prompts e métricas padronizadas.

Instalação:

pip install lm-eval

Avalie qualquer modelo HuggingFace:

lm_eval --model hf \
  --model_args pretrained=meta-llama/Llama-2-7b-hf \
  --tasks mmlu,gsm8k,hellaswag \
  --device cuda:0 \
  --batch_size 8

Veja tarefas disponíveis:

lm_eval --tasks list

Fluxos de trabalho comuns

Fluxo de trabalho 1: Avaliação de benchmark padrão

Avalie o modelo em benchmarks principais (MMLU, GSM8K, HumanEval).

Copie esta lista de verificação:

Avaliação de Benchmark:
- [ ] Etapa 1: Escolha a suite de benchmark
- [ ] Etapa 2: Configure o modelo
- [ ] Etapa 3: Execute a avaliação
- [ ] Etapa 4: Analise os resultados

Etapa 1: Escolha a suite de benchmark

Benchmarks principais de raciocínio:

• MMLU (Massive Multitask Language Understanding) - 57 disciplinas, múltipla escolha
• GSM8K - Problemas de matemática de escola primária
• HellaSwag - Raciocínio de senso comum
• TruthfulQA - Veracidade e factualidade
• ARC (AI2 Reasoning Challenge) - Perguntas de ciência

Benchmarks de código:

• HumanEval - Geração de código Python (164 problemas)
• MBPP (Mostly Basic Python Problems) - Codificação Python

Suite padrão (recomendado para lançamentos de modelo):

--tasks mmlu,gsm8k,hellaswag,truthfulqa,arc_challenge

Etapa 2: Configure o modelo

Modelo HuggingFace:

lm_eval --model hf \
  --model_args pretrained=meta-llama/Llama-2-7b-hf,dtype=bfloat16 \
  --tasks mmlu \
  --device cuda:0 \
  --batch_size auto  # Detecta automaticamente o tamanho de lote ideal

Modelo quantizado (4-bit/8-bit):

lm_eval --model hf \
  --model_args pretrained=meta-llama/Llama-2-7b-hf,load_in_4bit=True \
  --tasks mmlu \
  --device cuda:0

Checkpoint customizado:

lm_eval --model hf \
  --model_args pretrained=/path/to/my-model,tokenizer=/path/to/tokenizer \
  --tasks mmlu \
  --device cuda:0

Etapa 3: Execute a avaliação

# Avaliação completa de MMLU (57 disciplinas)
lm_eval --model hf \
  --model_args pretrained=meta-llama/Llama-2-7b-hf \
  --tasks mmlu \
  --num_fewshot 5 \  # Avaliação 5-shot (padrão)
  --batch_size 8 \
  --output_path results/ \
  --log_samples  # Salva predições individuais

# Múltiplos benchmarks de uma vez
lm_eval --model hf \
  --model_args pretrained=meta-llama/Llama-2-7b-hf \
  --tasks mmlu,gsm8k,hellaswag,truthfulqa,arc_challenge \
  --num_fewshot 5 \
  --batch_size 8 \
  --output_path results/llama2-7b-eval.json

Etapa 4: Analise os resultados

Resultados salvos em results/llama2-7b-eval.json:

{
  "results": {
    "mmlu": {
      "acc": 0.459,
      "acc_stderr": 0.004
    },
    "gsm8k": {
      "exact_match": 0.142,
      "exact_match_stderr": 0.006
    },
    "hellaswag": {
      "acc_norm": 0.765,
      "acc_norm_stderr": 0.004
    }
  },
  "config": {
    "model": "hf",
    "model_args": "pretrained=meta-llama/Llama-2-7b-hf",
    "num_fewshot": 5
  }
}

Fluxo de trabalho 2: Rastreie o progresso do treinamento

Avalie checkpoints durante o treinamento.

Rastreamento de Progresso de Treinamento:
- [ ] Etapa 1: Configure avaliação periódica
- [ ] Etapa 2: Escolha benchmarks rápidos
- [ ] Etapa 3: Automatize a avaliação
- [ ] Etapa 4: Plote curvas de aprendizado

Etapa 1: Configure avaliação periódica

Avalie a cada N etapas de treinamento:

#!/bin/bash
# eval_checkpoint.sh

CHECKPOINT_DIR=$1
STEP=$2

lm_eval --model hf \
  --model_args pretrained=$CHECKPOINT_DIR/checkpoint-$STEP \
  --tasks gsm8k,hellaswag \
  --num_fewshot 0 \  # 0-shot para velocidade
  --batch_size 16 \
  --output_path results/step-$STEP.json

Etapa 2: Escolha benchmarks rápidos

Benchmarks rápidos para avaliação frequente:

• HellaSwag: ~10 minutos em 1 GPU
• GSM8K: ~5 minutos
• PIQA: ~2 minutos

Evite para avaliação frequente (muito lento):

• MMLU: ~2 horas (57 disciplinas)
• HumanEval: Requer execução de código

Etapa 3: Automatize a avaliação

Integre com script de treinamento:

# No loop de treinamento
if step % eval_interval == 0:
    model.save_pretrained(f"checkpoints/step-{step}")

    # Execute avaliação
    os.system(f"./eval_checkpoint.sh checkpoints step-{step}")

Ou use callbacks do PyTorch Lightning:

from pytorch_lightning import Callback

class EvalHarnessCallback(Callback):
    def on_validation_epoch_end(self, trainer, pl_module):
        step = trainer.global_step
        checkpoint_path = f"checkpoints/step-{step}"

        # Salve checkpoint
        trainer.save_checkpoint(checkpoint_path)

        # Execute lm-eval
        os.system(f"lm_eval --model hf --model_args pretrained={checkpoint_path} ...")

Etapa 4: Plote curvas de aprendizado

import json
import matplotlib.pyplot as plt

# Carregue todos os resultados
steps = []
mmlu_scores = []

for file in sorted(glob.glob("results/step-*.json")):
    with open(file) as f:
        data = json.load(f)
        step = int(file.split("-")[1].split(".")[0])
        steps.append(step)
        mmlu_scores.append(data["results"]["mmlu"]["acc"])

# Plote
plt.plot(steps, mmlu_scores)
plt.xlabel("Training Step")
plt.ylabel("MMLU Accuracy")
plt.title("Training Progress")
plt.savefig("training_curve.png")

Fluxo de trabalho 3: Compare múltiplos modelos

Suite de benchmark para comparação de modelos.

Comparação de Modelos:
- [ ] Etapa 1: Defina a lista de modelos
- [ ] Etapa 2: Execute avaliações
- [ ] Etapa 3: Gere tabela de comparação

Etapa 1: Defina a lista de modelos

# models.txt
meta-llama/Llama-2-7b-hf
meta-llama/Llama-2-13b-hf
mistralai/Mistral-7B-v0.1
microsoft/phi-2

Etapa 2: Execute avaliações

#!/bin/bash
# eval_all_models.sh

TASKS="mmlu,gsm8k,hellaswag,truthfulqa"

while read model; do
    echo "Evaluating $model"

    # Extraia nome do modelo para arquivo de saída
    model_name=$(echo $model | sed 's/\//-/g')

    lm_eval --model hf \
      --model_args pretrained=$model,dtype=bfloat16 \
      --tasks $TASKS \
      --num_fewshot 5 \
      --batch_size auto \
      --output_path results/$model_name.json

done < models.txt

Etapa 3: Gere tabela de comparação

import json
import pandas as pd

models = [
    "meta-llama-Llama-2-7b-hf",
    "meta-llama-Llama-2-13b-hf",
    "mistralai-Mistral-7B-v0.1",
    "microsoft-phi-2"
]

tasks = ["mmlu", "gsm8k", "hellaswag", "truthfulqa"]

results = []
for model in models:
    with open(f"results/{model}.json") as f:
        data = json.load(f)
        row = {"Model": model.replace("-", "/")}
        for task in tasks:
            # Obtenha métrica primária para cada tarefa
            metrics = data["results"][task]
            if "acc" in metrics:
                row[task.upper()] = f"{metrics['acc']:.3f}"
            elif "exact_match" in metrics:
                row[task.upper()] = f"{metrics['exact_match']:.3f}"
        results.append(row)

df = pd.DataFrame(results)
print(df.to_markdown(index=False))

Saída:

| Model                  | MMLU  | GSM8K | HELLASWAG | TRUTHFULQA |
|------------------------|-------|-------|-----------|------------|
| meta-llama/Llama-2-7b  | 0.459 | 0.142 | 0.765     | 0.391      |
| meta-llama/Llama-2-13b | 0.549 | 0.287 | 0.801     | 0.430      |
| mistralai/Mistral-7B   | 0.626 | 0.395 | 0.812     | 0.428      |
| microsoft/phi-2        | 0.560 | 0.613 | 0.682     | 0.447      |

Fluxo de trabalho 4: Avalie com vLLM (inferência mais rápida)

Use backend vLLM para avaliação 5-10x mais rápida.

Avaliação com vLLM:
- [ ] Etapa 1: Instale vLLM
- [ ] Etapa 2: Configure backend vLLM
- [ ] Etapa 3: Execute avaliação

Etapa 1: Instale vLLM

pip install vllm

Etapa 2: Configure backend vLLM

lm_eval --model vllm \
  --model_args pretrained=meta-llama/Llama-2-7b-hf,tensor_parallel_size=1,dtype=auto,gpu_memory_utilization=0.8 \
  --tasks mmlu \
  --batch_size auto

Etapa 3: Execute avaliação

vLLM é 5-10× mais rápido que HuggingFace padrão:

# HF padrão: ~2 horas para MMLU em modelo 7B
lm_eval --model hf \
  --model_args pretrained=meta-llama/Llama-2-7b-hf \
  --tasks mmlu \
  --batch_size 8

# vLLM: ~15-20 minutos para MMLU em modelo 7B
lm_eval --model vllm \
  --model_args pretrained=meta-llama/Llama-2-7b-hf,tensor_parallel_size=2 \
  --tasks mmlu \
  --batch_size auto

Quando usar vs alternativas

Use lm-evaluation-harness quando:

• Benchmarking de modelos para artigos acadêmicos
• Comparação de qualidade de modelo em tarefas padrão
• Rastreamento de progresso de treinamento
• Relatório de métricas padronizadas (todos usam os mesmos prompts)
• Necessidade de avaliação reproduzível

Use alternativas em vez disso:

• HELM (Stanford): Avaliação mais ampla (fairness, eficiência, calibração)
• AlpacaEval: Avaliação de seguimento de instruções com juízes LLM
• MT-Bench: Avaliação multi-turno conversacional
• Scripts customizados: Avaliação específica de domínio

Problemas comuns

Problema: Avaliação muito lenta

Use backend vLLM:

lm_eval --model vllm \
  --model_args pretrained=model-name,tensor_parallel_size=2

Ou reduza exemplos fewshot:

--num_fewshot 0  # Em vez de 5

Ou avalie subconjunto de MMLU:

--tasks mmlu_stem  # Apenas disciplinas STEM

Problema: Sem memória disponível

Reduza tamanho do lote:

--batch_size 1  # Ou --batch_size auto

Use quantização:

--model_args pretrained=model-name,load_in_8bit=True

Ative offloading de CPU:

--model_args pretrained=model-name,device_map=auto,offload_folder=offload

Problema: Resultados diferentes dos relatados

Verifique contagem de fewshot:

--num_fewshot 5  # A maioria dos artigos usa 5-shot

Verifique nome exato da tarefa:

--tasks mmlu  # Não mmlu_direct ou mmlu_fewshot

Verifique correspondência de modelo e tokenizador:

--model_args pretrained=model-name,tokenizer=same-model-name

Problema: HumanEval não executa código

Instale dependências de execução:

pip install human-eval

Ative execução de código:

lm_eval --model hf \
  --model_args pretrained=model-name \
  --tasks humaneval \
  --allow_code_execution  # Necessário para HumanEval

Tópicos avançados

Descrições de benchmarks: Veja references/benchmark-guide.md para descrição detalhada de todas as 60+ tarefas, o que medem e interpretação.

Tarefas customizadas: Veja references/custom-tasks.md para criar tarefas de avaliação específicas de domínio.

Avaliação de API: Veja references/api-evaluation.md para avaliar modelos OpenAI, Anthropic e outras APIs.

Estratégias multi-GPU: Veja references/distributed-eval.md para avaliação data parallel e tensor parallel.

Requisitos de hardware

• GPU: NVIDIA (CUDA 11.8+), funciona em CPU (muito lento)
• VRAM:
  • Modelo 7B: 16GB (bf16) ou 8GB (8-bit)
  • Modelo 13B: 28GB (bf16) ou 14GB (8-bit)
  • Modelo 70B: Requer multi-GPU ou quantização
• Tempo (modelo 7B, single A100):
  • HellaSwag: 10 minutos
  • GSM8K: 5 minutos
  • MMLU (completo): 2 horas
  • HumanEval: 20 minutos

Recursos

• GitHub: https://github.com/EleutherAI/lm-evaluation-harness
• Documentação: https://github.com/EleutherAI/lm-evaluation-harness/tree/main/docs
• Biblioteca de tarefas: 60+ tarefas incluindo MMLU, GSM8K, HumanEval, TruthfulQA, HellaSwag, ARC, WinoGrande, etc.
• Leaderboard: https://huggingface.co/spaces/HuggingFaceH4/open_llm_leaderboard (usa este harness)