Upload training/NOTES.md with huggingface_hub

training/NOTES.md

@@ -6,6 +6,45 @@ Fase 1 ("quick"): 2 épocas nos ~3.9k clipes do `mega_curated` para validar o pi
 Fase 2: treino com o dataset completo (`loopcut_000..005`, ~49 GB) ou o que couber.
 Foco de uso: image2video (primeiro frame → vídeo). Task de treino: `i2va`.
 
+## RUNBOOK — caminho das pedras (para o próximo agente/treino)
+
+Sequência exata que funcionou, com os custos medidos. Scripts em `scripts/`, configs em `configs/`.
+
+1. **Ambiente**: usar /venv/main (torch 2.10.0+cu130 — NÃO troque torch; nightly quebra CUBLAS).
+   `uv pip install -e .` no fork Akane commit c4b84fa. `uv pip install tensorboard` (não vem).
+   Se o venv der Permission denied: `sudo chown -R claude:claude /venv/main`.
+2. **Downloads** (hf CLI com xet, muito rápido): pesos Comfy-Org/MiniMax-H3 (DiT bf16 66 GB +
+   TE nvfp4 15 GB + 2 VAEs) e dataset. TE bf16 (48 GB) é desnecessário — nvfp4 funciona em
+   Blackwell para cache E sampling do trainer.
+3. **Análise quantitativa do dataset ANTES de tudo** (ffprobe em paralelo): fps real, SAR/DAR
+   (DVDs 720×480 são anamórficos!), nb_frames, áudio. Sem isso o treino sai distorcido/errado.
+4. **Normalização** (`normalize_videos.py`, ~30 jobs, ~15 min/4k clipes): 24 fps CFR + setsar=1
+   + scale por SAR. Nunca treinar fonte com fps misto (uncanny motion) ou pixel anamórfico.
+5. **Extensão de loops** (`extend_loops.py`): tiling do ciclo até escada 124/90/73/56
+   (canvas do H3 começa em ~124f; treinar 22f não é validado por ninguém). Loops = tiling limpo.
+6. **Buckets multi-res** (`assign_buckets.py`): 3 áreas (512×288 / 640×384 / 832×480, 55/28/17),
+   symlinks, sem upscale. Multi-res é OBRIGATÓRIA no H3 (RoPE por área) + jitter 0.2 no treino.
+7. **Smoke test** (`smoke_train.sh`): 10 steps + sampling + checkpoint + resume (leg 2 com
+   --max_train_steps 15 valida autoresume de verdade). Incluir os itens MAIS PESADOS por bucket.
+8. **Cache** (`cache_quick.sh`): batch 24 + workers 16, SERIAL (latents → TE). Medido na 5090:
+   latents ~4,5 h + TE ~1,5 h para 3.885 itens ≈ 31,7 GB. NUNCA rodar TE em paralelo com latents
+   na mesma GPU (medido: piora ambos). Batch >24 não ajuda (VAE é o gargalo, GPU 100%).
+9. **Treino** (`train_quick.sh` via tmux + tee log): receita anti-destilação completa (ver seção
+   Receita). ~13 s/it na 5090 no regime 124f multi-res. Sampling+checkpoint a cada 500 steps.
+10. **Uploader HF** (`hf_uploader.py`) ativo DESDE o smoke; repo gated manual, nunca "minimax" no nome.
+11. **Monitorar**: loss média SOBE com preservation ligada — é normal, olhar val/loss de vídeo;
+    watchdog de stall (freeze silencioso near-OOM = step 10x mais lento, não crasha).
+
+**Armadilhas que já custaram tempo aqui:**
+- ffmpeg pesado em paralelo durante CARGA do DiT → 6× mais lento (carga é CPU-bound); durante
+  steps de treino, ok.
+- Jupyter cria `.ipynb_checkpoints` root-owned dentro de output/ quando o usuário navega —
+  `rm -rf` falha; usar `sudo rm` ou ignorar.
+- Nunca `pkill -f` com padrão que casa com o próprio comando composto; matar por PID exato.
+- Nunca apagar cache com processo de treino/cache vivo apontando para ele.
+- Cache TOML separado do train TOML (batch alto só no cache; treino EXIGE batch_size=1).
+- `--save_last_n_steps_state 1500` limita states em disco (cada state = 859 MB).
+
 ## Ambiente (medido em 2026-08-10)
 - Vast.ai, RTX 5090 32 GB (sm_120), 124 GB RAM, 32 vCPU, disco 600 GB (overlay, **não persistente**)
 - Python 3.12.13 em `/venv/main`, torch 2.10.0+cu130 (combinação validada pela comunidade)
@@ -96,7 +135,7 @@ folga de VRAM protege contra freeze near-OOM, e o custo do swap no H3 é ~5% —
   no início dos steps (dimensionado pelos itens mais pesados nos smoke buckets)
 - Sampling 124f: 35s (512×288) / 62s (640×384) / 108s (832×480) de denoising por vídeo;
   pico 16,7 GiB; ~3,5 min por evento de sampling (a cada 500 steps → overhead ~1%)
-- 05:42 lançado tmux `h3quick`: cache completo (3.885 itens, batch 4) → treino 2 épocas encadeado
+- 05:42 lançado tmux `h3quick`: cache completo (3.885 itens; batch final 24) → treino 2 épocas encadeado
 - Log: /workspace/logs/quick_pipeline.log
 
 ## Medições de cache (10/08 06:00-06:40)