Método
e erros

1 Por que esta apostila existe

Registrar só o que deu certo distorceria a leitura de tudo o que vem depois. E há também uma razão prática: metade das melhores decisões deste projeto veio de descobrir que estávamos errados. O regularizador de cosseno existe porque uma busca semântica falhou. A métrica de piso da Bússola (a primeira versão do leme, que só previa a direção do próximo estado; no código, compass) existe porque uma medida bonita se revelou vazia.

Esta apostila registra as regras e os erros. Quem repetir o projeto vai errar diferente — mas o tipo de erro se repete.

2 As cinco regras

Regra 1 — uma variável por vez, e o resto congelado

Toda comparação usa o mesmo treino.bin, o mesmo número de passos, o mesmo lote e a mesma semente 1337. O corpus do duelo está congelado em model/data/duelo_200mb/, com hash conferido.

E o script de empacotamento recusa sobrescrever dados existentes:

PARADO — ja existe um conjunto de dados aqui
    treino.bin          115.1 MB
Sobrescrever isso quebra a comparabilidade com todo treino ja feito.

Sem essa trava, um corpus trocado no meio de uma série invalidaria tudo em silêncio — os números continuariam saindo, só não significariam mais a mesma coisa.

Regra 2 — o melhor checkpoint, nunca o último

A validação oscila entre avaliações. No duelo, o modelo clássico piorou entre os passos 649 e 699 sem nenhuma causa real. Comparar o último passo de cada rodada compara ruído.

Regra 3 — o nome da pasta carrega a configuração

mini-moderno-reg1-lat1-duelo é feio e é certo: tamanho, arquitetura, regularizador, bússola, rodada. Seis meses depois, a pergunta "o que tinha nessa rodada?" se responde pelo rótulo, não pela memória.

Regra 4 — rodadas incompletas são marcadas, não escondidas

O relatório detecta rodadas que não gastaram o mesmo orçamento e escreve PARCIAL no lugar da diferença percentual. Uma rodada parada no passo 100 contra outras de 700 mostraria um número enorme que não diz nada.

Regra 5 — toda métrica viaja com a sua linha de base

Esta regra nasceu de um erro, contado na seção 4. Um número sozinho não significa nada: 0,534 é excelente ou é nada, dependendo do piso.

3 O catálogo

4 Quatro erros em detalhe

O instrumento que apagava o próprio sinal

Contado na apostila 03, mas vale a forma geral. A linha era:

Z = Z - Z.mean(0, keepdim=True)     # "normalizar"

Uma normalização de rotina. Só que a anisotropia que queríamos medir é um deslocamento da origem — e centrar remove deslocamentos. O instrumento apagava o sinal antes de medi-lo.

O treino não reclamava: a perda descia, o modelo aprendia. O erro só apareceu ao rodar o medidor contra distribuições cuja resposta certa já sabíamos.

A métrica sem piso

A Bússola prevê a direção do próximo estado. Medimos o cosseno entre a previsão e o alvo real: 0,534. Reportamos, por várias rodadas, como "0,534 contra ~0,00 do acaso".

Até alguém perguntar quanto daria sem preditor nenhum — só copiando o estado atual:

A correção foi estrutural, não editorial: o piso agora é calculado dentro do laço de treino e impresso ao lado da métrica, sempre. Não dá mais para reportar um sem o outro.

bussola 0.064 (piso 0.598 ganho -0.534)

Essa linha é de um modelo recém-inicializado: a bússola é pior que copiar o estado atual. Exatamente o que a métrica antiga esconderia.

O diagnóstico impossível

A validação do modelo clássico subiu no fim do duelo. "Começou a sobreajustar" é a leitura automática — e era impossível: 700 passos × 8 192 tokens = 5,7 M de tokens num corpus de 60,3 M. 0,09 época. Nenhum token foi visto duas vezes.

A lição não é sobre sobreajuste. É que a explicação mais familiar chega primeiro, e às vezes a aritmética a descarta em dez segundos.

A base de comparação errada

Por três avisos seguidos, comparei a rodada com bússola contra mini-moderno-duelo — o modelo sem regularizador. O controle correto era mini-moderno-reg1, que difere apenas pela bússola.

Nenhuma conclusão final mudou, mas três relatos intermediários estavam errados. Montar a tabela com as duas colunas lado a lado tornou o engano óbvio — o que não era, olhando um número por vez.

5 Os erros que o teste em CPU não pega

Três dos itens do catálogo não são de método: são de engenharia. O que os une é que nenhum deles falha — o programa roda, devolve números, e só a placa sabe que algo está errado.

Os três foram encontrados pelo mesmo gesto: ler o código que ia rodar, antes de rodá-lo. Nenhum apareceria em teste local — na CPU tudo funciona, só devagar.

6 Os princípios, destilados

1. Calibre o instrumento antes de usá-lo. Construa casos cuja resposta você já sabe. Um medidor errado não reclama.
2. Toda métrica viaja com seu piso. Se você não sabe quanto dá "não fazer nada", não sabe se o seu número é bom.
3. Desconfie da explicação que chega primeiro. "Sobreajuste" é familiar; a aritmética descartou em dez segundos.
4. Resultado negativo entra na tabela principal. O SigReg não ajudou e a Bússola rasa custa mais do que entrega — as duas linhas estão no mapa do projeto, no mesmo destaque dos resultados positivos.
5. Falha silenciosa é a pior espécie. Três erros aqui não produziram mensagem nenhuma. Prefira código que pare com um grito.
6. Meça antes de pagar. Vale para GPU alugada e para qualquer coisa cujo custo corra enquanto você descobre.

Com o método declarado, a apostila 07 faz a conta que decide o próximo passo:
quanto custa, de verdade, chegar à escala do GPT-3 — e por que o limite não é a placa.