docs/METRICS.md

# Métricas de treino (TensorBoard e relatórios)

## Onde são geradas

Em [`train.py`](../train.py) o `TrainingArguments` usa `report_to=["tensorboard"]` e `logging_dir` aponta para `./results` (junto com `output_dir`). Os eventos ficam em ficheiros `events.out.tfevents.*` dentro de `results/` (e subpastas de checkpoints).

O [`app.py`](../app.py) do Space **não** arranca um processo TensorBoard à parte; no Hugging Face Space com Docker só a porta da app é exposta publicamente. Para inspecionar curvas, use análise **offline** (script abaixo), descarregue os event files, ou carregue os `events.out.tfevents.*` para um repositório de modelo no Hub.

### TensorBoard no Hub (repositório de modelo)

Se os ficheiros de eventos estiverem versionados no repositório (por exemplo após `hf upload`), o Hugging Face mostra o TensorBoard em `https://huggingface.co/<org>/<repo>/tensorboard`. Exemplo: [beAnalytic/eda-llm-model](https://huggingface.co/beAnalytic/eda-llm-model) — [separador TensorBoard](https://huggingface.co/beAnalytic/eda-llm-model/tensorboard).

## Script de análise automática

[`scripts/analyze_training_metrics.py`](../scripts/analyze_training_metrics.py) lê os event files, extrai escalares (loss, learning rate, etc.) e gera:

- `training_metrics_report.txt` (legível)
- `training_metrics.json` (programático)

**Requisito:** `tensorboard` instalado (`pip install tensorboard`, também listado em `requirements.txt`).

### Uso

```bash
cd ml/configs/huggingface_training_config
pip install -r requirements.txt

# Diretório com events (típico após treino local)
python scripts/analyze_training_metrics.py ./results

# Diretório atual
python scripts/analyze_training_metrics.py .
```

### Obter eventos do Space

No container do [Space de treino](https://huggingface.co/spaces/beAnalytic/Training), os eventos ficam por defeito em **`/app/results`** (equivalente a `./results` no código do `train.py`). Podem aparecer na raiz de `results/` ou em subpastas (ex.: `runs/<run_name>/`).

1. Abra o Space no Hub → **Files** (ou **Files and versions** no repositório Git do Space, se fizer commit dos artefactos).
2. Descarregue a pasta `results/` completa (ou pelo menos os ficheiros `events.out.tfevents.*`).
3. No PC, use essa pasta como `--logdir` do TensorBoard (ex.: `tensorboard --logdir=./results`) ou corra o script de análise na pasta que contém os eventos.

### Treino local

Os eventos ficam em `./results/` por defeito; pode haver também `./logs/` conforme configuração.

## Métricas típicas

| Série | Significado |
|-------|-------------|
| `train/loss` | Loss de treino |
| `eval/loss` | Loss de validação (se avaliação por steps estiver ativa) |
| `train/learning_rate` | LR efetiva |

O relatório calcula estatísticas (mínimo, máximo, melhoria percentual) e um **gap** entre eval e train para sinalizar overfitting/underfitting (heurística no script).

## Interpretação rápida

- **Train loss alto (> 2):** ainda a aprender; verificar dados e hiperparâmetros.
- **Train loss baixo (< 0.5):** convergência razoável (depende da tarefa).
- **Gap eval vs train:** gap grande e eval pior → possível overfitting; gap negativo estranho → rever split/validação.
- **Learning rate:** oscilações fortes podem indicar LR alta; estagnação longa pode indicar LR baixa ou poucos dados.

## TensorBoard interativo (local)

Se tiver a pasta `results/` (ou o valor de `TENSORBOARD_LOGDIR`) com eventos:

```bash
cd ml/configs/huggingface_training_config
python scripts/launch_tensorboard.py --logdir ./results
```

Equivalente manual:

```bash
tensorboard --logdir=./results --host=127.0.0.1 --port 6006
```

Abrir no browser o URL indicado (por defeito `http://127.0.0.1:6006`). No Space não assuma acesso à porta 6006 a partir do exterior.

### Variáveis de ambiente (treino)

| Variável | Efeito |
|----------|--------|
| `TENSORBOARD_LOGDIR` ou `LOGGING_DIR` | Diretório dos eventos TensorBoard (predefinido: mesmo que `TRAINING_OUTPUT_DIR` ou `./results`). |
| `TRAINING_RUN_NAME` | Nome da corrida no TensorBoard (predefinido: `eda-lora-UTC...`). |
| `TRAINING_OUTPUT_DIR` | Diretório de checkpoints e, por defeito, dos logs TB. |

O [`train.py`](../train.py) regista `train/loss`, `eval/loss`, `train/learning_rate`, etc., com `logging_first_step=True` e `metric_for_best_model=eval_loss`.

## Problemas

- **Nenhum arquivo de eventos:** confirmar que o treino já escreveu steps; `logging_steps` em `train.py`; pasta correta.
- **TensorBoard não disponível:** instalar `tensorboard`; sem ele o script pode limitar-se a extrair configurações dos eventos.
- **Nenhuma métrica de treino:** treino ainda no início ou `logging_steps` muito grande.

## CI/CD

Pode consumir `training_metrics.json` para gates (ex.: melhoria mínima de loss, status de overfitting). Ver estrutura no ficheiro gerado após uma execução bem-sucedida.