> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monostate.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Métricas de Avaliação

> Como medir se seu modelo é bom

# Métricas de Avaliação

Você não pode melhorar o que não mede. Aqui está como dizer se seu modelo está realmente funcionando.

## Métricas de Classificação

### Accuracy

A métrica mais simples - qual porcentagem você acertou?

```
Accuracy = Previsões Corretas / Total de Previsões
```

Exemplo: 90/100 corretas = 90% de accuracy

**Problema**: Enganoso com dados desbalanceados. Se 95% dos emails não são spam, um modelo que sempre diz "não spam" obtém 95% de accuracy.

### Precision & Recall

**Precision**: Das que você previu como positivas, quantas eram realmente positivas?

**Recall**: De todas as positivas reais, quantas você encontrou?

Exemplo para detecção de spam:

* Precision: Dos emails marcados como spam, quantos eram realmente spam?
* Recall: De todos os emails spam, quantos você pegou?

### F1 Score

Combina precision e recall em um número.

```
F1 = 2 × (Precision × Recall) / (Precision + Recall)
```

Use quando você se importa igualmente com falsos positivos e falsos negativos.

## Métricas de Geração

### Perplexity

Quão surpreso o modelo está com os dados de teste. Menor é melhor.

* Modelo bom: Perplexity = 10-50
* Modelo ruim: Perplexity = 100+

### BLEU Score

Compara texto gerado com texto de referência. Usado para tradução, resumo.

* BLEU = 0: Sem sobreposição
* BLEU = 1: Correspondência perfeita
* BLEU > 0.3: Geralmente decente

### Avaliação Humana

Às vezes a melhor métrica é perguntar a humanos:

* Esta resposta é útil?
* Este resumo captura os pontos principais?
* Esta tradução é natural?

## Curvas de Loss

### Training Loss vs Validation Loss

Acompanhe ambos durante o treinamento:

**Padrão bom**:

* Ambos diminuem
* Permanecem próximos
* Estabilizam eventualmente

**Overfitting**:

* Training loss continua caindo
* Validation loss aumenta
* Gap se amplia

**Underfitting**:

* Ambos permanecem altos
* Pouca melhoria
* Precisa de mais capacidade ou dados

## Métricas Específicas por Tarefa

### Image Classification

* Top-1 Accuracy: Classe correta é a previsão principal
* Top-5 Accuracy: Classe correta nas top 5 previsões
* Confusion Matrix: Veja quais classes ficam confusas

### Object Detection

* mAP (mean Average Precision): Qualidade geral de detecção
* IoU (Intersection over Union): Quão bem as caixas se sobrepõem

### NER/Token Classification

* F1 em nível de entidade: Entidades completas corretas
* Accuracy em nível de token: Tokens individuais corretos

## Referência Rápida

| Tarefa                     | Métrica Principal | Boa Pontuação |
| -------------------------- | ----------------- | ------------- |
| Classificação Binária      | F1 Score          | > 0.8         |
| Classificação Multi-classe | Accuracy          | > 0.9         |
| Geração                    | Perplexity        | \< 50         |
| Tradução                   | BLEU              | > 0.3         |
| Resumo                     | ROUGE             | > 0.4         |
| Q\&A                       | Exact Match       | > 0.7         |

## Avaliação Aprimorada no AITraining

O AITraining suporta avaliação aprimorada com múltiplas métricas integradas e personalizadas.

### Habilitar Avaliação Aprimorada

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data.jsonl \
  --project-name my-model \
  --use-enhanced-eval \
  --eval-metrics "perplexity,bleu"
```

### Métricas Disponíveis

| Métrica      | Descrição                                |
| ------------ | ---------------------------------------- |
| `perplexity` | Incerteza do modelo (menor é melhor)     |
| `bleu`       | Sobreposição N-gram com referência       |
| `rouge`      | Avaliação orientada a recall para resumo |
| `accuracy`   | Accuracy de classificação                |
| `f1`         | F1 score para classificação              |

### API Python

```python theme={null}
from autotrain.trainers.clm.params import LLMTrainingParams

params = LLMTrainingParams(
    model="google/gemma-3-270m",
    data_path="./data.jsonl",
    project_name="my-model",

    use_enhanced_eval=True,
    eval_metrics=["perplexity", "bleu"],
)
```

### Métricas Personalizadas

Registre métricas personalizadas para avaliação especializada:

```python theme={null}
from autotrain.metrics import register_metric

@register_metric("my_custom_metric")
def compute_custom_metric(predictions, references):
    # Sua lógica de pontuação personalizada
    score = ...
    return {"my_custom_metric": score}

# Então use no treinamento
params = LLMTrainingParams(
    ...
    use_enhanced_eval=True,
    eval_metrics=["perplexity", "my_custom_metric"],
)
```

## Dicas Práticas

1. **Sempre use conjunto de validação** - Nunca avalie em dados de treinamento
2. **Considere a tarefa** - Accuracy nem sempre é melhor
3. **Acompanhe tendências** - Melhorar é mais importante que números absolutos
4. **Múltiplas métricas** - Nenhuma métrica única conta toda a história

## Sinais de Alerta

* Accuracy de treinamento 100%, validação 60% → Overfitting
* Todas as métricas presas → Learning rate pode estar errado
* Métricas pulando ao redor → Batch size muito pequeno
* Pontuações perfeitas imediatamente → Vazamento de dados ou bug

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Fine-tuning vs Treinamento Completo" href="/foundations/fine-tuning-vs-full-training">
    Escolha sua abordagem
  </Card>

  <Card title="Hyperparâmetros" href="/foundations/hyperparameters">
    Otimize suas configurações
  </Card>
</CardGroup>