docs/TROUBLESHOOTING.md

# Problemas comuns (Hugging Face EDA)

## Segurança: tokens

- **Nunca** commite `HF_TOKEN` nem cole tokens em README ou código versionado.
- Gere e revogue em `https://huggingface.co/settings/tokens`.
- Antes de `hf upload`, procure segredos: `grep -r "hf_" . --include="*.md" --include="*.py"` no diretório de upload.
- Script auxiliar: [`scripts/clean_tokens.sh`](../scripts/clean_tokens.sh) para limpar padrões antes de enviar ao Hub.

## 401 ao fazer `push_dataset_to_hub` / upload de dataset

- **Token:** tem de ser um [token com Write](https://huggingface.co/settings/tokens) (não uses só token de inferência).
- **Organização:** `beAnalytic/eda-training-dataset` só funciona se a conta do token for **membro da org** com permissão de escrita. Caso contrário, cria o dataset no teu utilizador e aponta o treino para esse repo:
  - `export DATASET_REPO=O_TEU_USER/eda-training-dataset`
  - Depois o mesmo valor em secrets do Space / `train.py`.
- Confirma quem está autenticado: `huggingface-cli whoami` (com o mesmo token).

## Space: `Invalid user token` / 401 em `whoami` / `login`

O secret **`HF_TOKEN`** no Space tem de ser um [token classico com permissao Write](https://huggingface.co/settings/tokens) (ou fine-grained com acesso de escrita aos repos necessarios). **Nao** uses `HF_INFERENCE_ENDPOINT_TOKEN` nem tokens so de leitura. Cola o valor **sem aspas**, uma linha, sem espacos a mais. Guarda e faz **Factory reboot** do Space.

Se o erro mostrar `train.py` numa linha com `login` e o teu ficheiro local for diferente, **faz upload** dos ficheiros deste repositorio para o Space (`hf upload` ou git), porque o codigo em `https://huggingface.co/spaces/...` pode estar desatualizado.

## Space: `CUDA out of memory` (T4 / ~15GB)

O modelo em **fp16** + **LoRA** com `max_length` alto e batch grande esgota VRAM no backward (a loss faz `logits.float()`, o que pesa com sequências longas).

**Predefinidos neste projeto (Dockerfile / `train.py`):** `MAX_SEQ_LENGTH=256`, `PER_DEVICE_TRAIN_BATCH_SIZE=1`, `GRADIENT_ACCUMULATION_STEPS=8`, **gradient checkpointing** ativo, **`device_map={"": 0}`** numa única GPU (evita offload para CPU com `device_map="auto"`). Ajusta no Space (Settings → Variables) ou no `Dockerfile` se tiveres GPU maior.

- Sobe `GRADIENT_ACCUMULATION_STEPS` em vez de `PER_DEVICE_TRAIN_BATCH_SIZE` para manter batch efetivo.
- Aumenta `MAX_SEQ_LENGTH` só se houver VRAM (ex.: 384) com **um único** processo de treino na GPU.
- `PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True` já está no Dockerfile.

## Space: `Process XXXXX has X GiB memory` (vários PIDs na mesma GPU)

O erro de OOM pode mostrar **vários processos** a usar VRAM ao mesmo tempo. Reinícios do Space sem libertar processos antigos podem acumular treinos. Faz **Factory reboot** do Space antes de voltar a treinar e, se ainda falhar, reduz `MAX_SEQ_LENGTH` ou aumenta a GPU no Hub.

O `app.py` usa um **lock em ficheiro** (`space_lock.py`, por defeito `/tmp/eda_training_single.lock`) para que só **um** `train.py` corra de cada vez: arranques em paralelo ficam em fila em vez de partilharem a mesma GPU.

## Space: `libnvJitLink.so.12` / `.13` / bitsandbytes

Este treino **não** usa quantização 4/8-bit; `requirements.txt` não inclui `bitsandbytes` e o `Dockerfile` faz `pip uninstall bitsandbytes` para evitar a imagem base a carregar uma wheel incompatível com `libnvJitLink`. Mantém-se `nvidia-cuda-nvjitlink-cu12` para outras dependências que possam precisar do linker. Se voltares a instalar `bitsandbytes` para QLoRA no futuro, alinha a versão CUDA com a imagem PyTorch.

## Space: `RuntimeError: operator torchvision::nms does not exist`

Acontece quando **torch** e **torchvision** ficam incompatíveis (por exemplo `pip` atualiza o PyTorch por causa de `torch>=...` em `requirements.txt` sem reinstalar **torchvision** alinhado). O `transformers` 5.x importa caminhos que carregam `torchvision`; o erro aparece já no `import transformers` / `import peft`.

**Neste repositório:** `requirements.txt` **não** fixa `torch` à parte (usa o PyTorch da imagem base); o `Dockerfile` corre `pip install --upgrade torchvision` depois das outras dependências. Faz **rebuild** do Space após atualizar.

Se ainda falhar, no `Dockerfile` alinha o par **torch+torchvision** ao CUDA da imagem, por exemplo:

```dockerfile
RUN pip install --no-cache-dir --upgrade torch torchvision --index-url https://download.pytorch.org/whl/cu121
```

(Ajusta `cu121` ou `cu124` conforme a variante CUDA da imagem `huggingface/transformers-pytorch-gpu`.)

## Space: log mostra TensorBoard na 7860 antes do `train.py`

Se vires mensagens como `Space de treinamento iniciado`, `Configuracao TensorBoard`, `TensorBoard ... 0.0.0.0:7860`, o `app.py` no Hub **nao** e o minimalista deste projeto (TensorBoard na porta publica do Space conflitua e pode causar `libgomp` / reinicios). Substitui pelo [`app.py`](../app.py) atual (so executa `train.py`) e volta a fazer build do Space.

## Space: TensorBoard na porta 7860 e reinicios em loop

No Hugging Face Space a porta **7860** e a porta **publica** da aplicacao. Nao arranques TensorBoard em `0.0.0.0:7860` no mesmo processo que o treino: conflita com o router do Space e pode reiniciar o container. O fluxo recomendado neste projeto e **sem** TensorBoard no `app.py` (so `train.py`); as metricas ficam em ficheiros em `results/` e analisas offline (ver [METRICS.md](METRICS.md)).

## Space: `Outro treino ja esta rodando (lock ativo)`

Indica um **ficheiro de lock** ou processo paralelo noutra versao do `app.py`. Remove o lock no repositorio do Space ou garante **um unico** processo de treino. Alinha o `app.py` do Space com o deste repositorio (`app.py` minimalista que so executa `train.py`).

## HF_TOKEN no Space

Sintomas: `HF_TOKEN não encontrado`, push desabilitado, checkpoints só locais.

1. Space → Settings → Repository secrets → `HF_TOKEN` (permissão write).
2. Reiniciar o Space após mudar secrets.
3. Com token: treino deve autenticar e `push_to_hub` conforme `train.py`. Sem token: treino corre; faça upload manual de `./results` depois.

## Erro 401 Unauthorized (Trainer / Hub)

Algumas versões do transformers tentam falar com o Hub mesmo com push desligado. Mitigações:

- Configurar `HF_TOKEN` válido no Space, ou
- Garantir treino sem push (variáveis e `train.py` coerentes com `push_to_hub=False`).

Se persistir: atualizar `transformers`/`huggingface_hub` e verificar que não há token inválido em cache (`huggingface-cli logout` local).

## Upload bloqueado: token detetado nos ficheiros

Mensagem do Hub sobre secrets em ficheiros.

1. Remover `hf_...` de README, `.env`, etc.
2. Editar no Hub ou novo commit sem o segredo.
3. Se o token expôs-se publicamente, **revogue-o** e crie outro.

## Cache / build do Space

Se o Space usar cache de build antigo e não refletir código novo:

- Settings → factory reboot ou rebuild; ou
- Commit que invalide cache (ex.: comentário no `Dockerfile`).

## Divergência Git (clone do Space)

```
Your branch and 'origin/main' have diverged
```

```bash
git fetch origin
git pull --rebase origin main
# resolver conflitos, git add, git rebase --continue
git push origin main
```

Evite `git push --force` salvo intenção explícita de sobrescrever o remoto.

## Variáveis de ambiente / `.env` no upload

Não envie `.env` para o Hub. Use `--exclude` no `hf upload` ou `.gitignore`.

## ImportError: huggingface-hub vs transformers

`transformers` 4.x exige `huggingface_hub<1`; ambiente com `huggingface_hub` 1.x precisa de `transformers>=5`. Ver `README.md` na pasta de config.

## `TypeError: ParquetWriter ... use_content_defined_chunking`

Versões recentes de `datasets` ao fazer `push_to_hub` exigem **PyArrow 21 ou superior**. Atualize no mesmo ambiente do treino:

```bash
pip install -U "pyarrow>=21.0.0"
```

O `requirements.txt` desta pasta já fixa essa dependência.

## Incompatibilidade numpy / pandas (sklearn)

Erro `numpy.dtype size changed` ao importar `transformers`/`peft`:

```bash
pip install --upgrade --force-reinstall numpy pandas scikit-learn
```

Ou ambiente virtual só para ML (`requirements.txt` desta pasta).

## Conflito com vLLM

`vllm` costuma fixar `transformers<5`. Use um venv separado para treino HF e outro para vLLM.

## Aviso no Hub: empty or missing yaml metadata

Aplica-se ao `README.md` do repositório (modelo, dataset ou Space): tem de existir um bloco no topo entre `---` e `---` com pelo menos metadados válidos (por exemplo `license`, `library_name` em repos de modelo criados após agosto de 2024). Para o LoRA EDA, copia o template [`README_MODEL_CARD.md`](../README_MODEL_CARD.md) para o README do repo de modelo no Hub. Para o Space Docker, o `README.md` do Space deve usar o frontmatter de [`SPACE_README.md`](../SPACE_README.md). Documentação: [Model Cards](https://huggingface.co/docs/hub/model-cards#model-card-metadata).

## Referência

Fluxo completo: [PIPELINE.md](PIPELINE.md). Métricas: [METRICS.md](METRICS.md).