docs/METRICS.md

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

Onde são geradas

Em 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 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 — separador TensorBoard.

Script de análise automática

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

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, 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:

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

Equivalente manual:

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 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.