v13.9.2-finetune-v4: update README.md

README.md

@@ -103,4 +103,76 @@ python scripts/train_from_v13_9_2.py \
   --tokenizer-path model_final/tokenizer/tokenizer.json \
   --datasets orion-research/translations-en_US-pt_BR,cnmoro/Instruct-PTBR-10M,strak2005/corpus-ptbr-v1 \
   --max-samples 200 --max-steps 50 --grad-accum 16 --lr 2e-5 --max-seq-len 64
-```
+```
+
+---
+
+## v13.9.2-finetune-v4 (2026-07-27)
+
+**4ª passagem de fine-tuning** nos 3 datasets PT-BR, com **2.5× mais amostras**
+(1500 vs 600 do v3) e **BUG-V4-1 corrigido** (empty HF_TOKEN causing auth
+header failure).
+
+### Mudanças desta versão
+
+- **BUG-V4-1 fix** (train_from_v13_9_2.py): `hf_token = os.environ.get('HF_TOKEN') or None`
+  — empty string `""` was being passed to huggingface_hub, causing
+  `Illegal header value b'Bearer '`. Public datasets don't need auth.
+- **Streaming timeout**: 180s → 600s (justificado por tool limitation para
+  carregar 500+ amostras de strak2005 em conexões lentas).
+- **NENHUMA mudança** de arquitetura, parâmetros, ou design do modelo.
+- **NENHUMA** renomeação de arquivos no HF (congelamento respeitado).
+
+### Treino
+
+| Parâmetro              | v3 (anterior) | v4 (atual)        |
+|------------------------|---------------|-------------------|
+| Samples por dataset    | 200           | 500               |
+| Total de amostras      | 600           | 1500 (2.5×)      |
+| Optimizer steps        | 50            | 40                |
+| Grad accum             | 16            | 16                |
+| Learning rate          | 2e-5          | 1e-5 (mais baixo) |
+| Micro-batches totais   | 800           | 640               |
+| Tempo                  | 5.3 min       | 4.0 min           |
+
+### Resultados
+
+| Métrica              | v3         | v4 (canonical)   | Δ              |
+|----------------------|------------|------------------|----------------|
+| Best loss (stage)    | 6.06       | 5.74             | -5.3%          |
+| Final loss (stage)   | 6.38       | 6.99 (step 40)   | (instabilidade)|
+| Canonical ppl        | 588.59     | 507.81           | **-13.7%**     |
+| Canonical source     | final      | step 20 best ckpt| (ver nota)     |
+| W8A8 mean error      | 0.49%      | 0.50%            | estável        |
+| W8A8 max error       | 1.51%      | 1.53%            | estável        |
+| Compression ratio    | 1.44×      | 1.44×            | estável        |
+
+**Nota sobre canonical source**: o script de treino salva o estado FINAL
+(step 40), não o BEST. Em v4, o modelo degradou após step 30 (spike de loss
+em step 35, provável bad batch no range cnmoro 500-1000). O **canonical
+model** enviado ao HF é o **checkpoint do step 20** (loss 6.23, ppl 507.81),
+que é melhor que o v3 final (ppl 588.59) em 13.7%.
+
+### Acumulado (4 passagens)
+
+- **15 stages** totais no training_report_v13_9_2.json
+- **390 optimizer steps** acumulados (300 anteriores + 40 v4 + 50 v3 = 390)
+
+  * 9 datasets v13.9.2 base (200 opt steps)
+  * + carolina finetune (50 opt steps)
+  * + 3 PT-BR datasets finetune-v2 (50 opt steps)
+  * + 3 PT-BR datasets finetune-v3 (50 opt steps, com format standardization)
+  * + 3 PT-BR datasets finetune-v4 (40 opt steps, 2.5× amostras, BUG-V4-1 fix)
+
+- **Format standardization** `### Instruction:\n...\n### Response:\n...`
+  aplicado a orion (tradução EN→PT) e cnmoro (instruções PT-BR).
+- strak2005 mantido como texto puro (corpus sem estrutura instruction/response).
+
+### Validação (inferência)
+
+- fp32 load: 0 missing, 0 unexpected ✓
+- Forward: 30.8 ms, sem NaN/Inf, logits shape (1, 64, 16384) ✓
+- Geração 3 prompts PT-BR: 0.61-0.85s, sem collapse ✓
+- W8A8 load: 0 missing, 0 unexpected ✓
+- W8A8 erro mean 0.065%, max 0.009 (vs fp32) ✓
+- Top-1 fp32 vs W8A8: **concordam** (token 17 = '.') ✓