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

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

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

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:

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:

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 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. Documentação: Model Cards.

Referência

Fluxo completo: PIPELINE.md. Métricas: METRICS.md.