File size: 4,922 Bytes
d4a00b2 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 | # 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.
|