# Protocolo: um corpus aceito antes de comparar o custo

Versão 1 — 24 de setembro de 2026. Esta ficha propõe um protocolo a preencher; ela não contém nenhum resultado medido nem conjunto de dados. O notebook associado usa um pequeno MLP sintético para aprender a registrar a memória. Ele não executa o protocolo de negócio abaixo.

## 1. Definir o trabalho útil antes dos testes

Exemplo de trabalho: classificar um corpus de **1.000 textos**. Monte você mesmo um conjunto autorizado, representativo do seu uso, com um identificador único e uma referência verificada por texto. Fixe a revisão do corpus, do modelo, do tokenizer, do código e a seed. Guarde separadamente a lista dos IDs esperados e as saídas individuais para permitir a auditoria.

Defina antes de qualquer medição: as classes, o formato de saída, a métrica principal (por exemplo macro-F1), seu limiar de aceitação e a degradação máxima permitida em relação a uma referência. Escolha uma tolerância pertinente para a sua aplicação; nenhum valor universal é fornecido aqui. Os dados de treinamento, de ajuste e de avaliação devem permanecer separados.

Um corpus é aceito somente se os 1.000 IDs esperados estiverem presentes exatamente uma vez, nenhuma resposta adicional constar nas saídas, o formato for válido e a regra de qualidade preestabelecida for satisfeita. Dois arquivos contendo cada um 1.000 linhas não provam por si só a igualdade dos IDs. Arquive a verificação dos conjuntos e das duplicatas.

## 2. Mudar apenas a variante anunciada

Para estudar o batch, prepare por exemplo as variantes 1, 4 e 8. Mantenha o mesmo corpus, ordem das entradas, modelo, tokenizer, precisão e limite de contexto. Se você estudar em seguida a precisão, crie uma experiência distinta e refaça o controle de qualidade. Descreva o truncamento: encurtar os textos muda o trabalho realizado.

Registre a GPU real, o número de GPUs efetivamente usadas, o device, o driver, o Python, o PyTorch e o runtime CUDA ou ROCm. Inscreva também a versão do seu código, as opções de geração eventuais e qualquer concorrência na máquina em `notes`. Um lote comercial de duas GPUs não implica que o programa use ambas.

## 3. Medir passagens comparáveis

Anuncie o que o cronômetro abrange: processamento apenas ou cadeia completa com leitura, tokenização e escrita. Separe carregamento, primeira passagem e passagens aquecidas. O script de memória mede apenas seu MLP e não cronometra uma cadeia de classificação completa.

Faça o aquecimento anunciado, depois cinco passagens medidas por variante em uma ordem alternada ou sorteada com antecedência. Guarde cada duração bruta. Relatar a mediana e a amplitude mín–máx permite ver a dispersão; cinco observações não justificam uma estimativa robusta do p95. Não descarte silenciosamente um erro ou uma passagem lenta: conserve sua linha e explique o incidente. Reinicie em um processo novo se quiser comparar as primeiras passagens em condições similares.

Para as medições de GPU no PyTorch, sincronize o device escolhido antes do registro inicial e depois da operação. Registre as baselines `allocated` e `reserved`, reinicialize as estatísticas de pico e depois conserve os picos absolutos da fase. `allocated` está incluído em `reserved`: somá-los contaria duas vezes uma parte da memória. Os dois máximos podem ser atingidos em instantes diferentes: a diferença entre eles não é uma medida do cache em um dado instante. As alocações de outros processos e as externas ao alocador do PyTorch não são cobertas.

## 4. Preencher resultats-bruts.csv

O CSV distribuído contém apenas os cabeçalhos. Escreva uma linha por passagem, com um ponto decimal e segundos para os tempos, bytes para a memória e centavos de USD para o forfait. Uma célula vazia significa "não registrado"; zero significa realmente zero. As vírgulas presentes em uma nota devem ser protegidas pelas regras CSV habituais.

| Campos | Sentido e preenchimento |
| --- | --- |
| `experiment_id`, `variant_id` | Identificadores estáveis do experimento e da variante. |
| `corpus_revision`, `model_revision`, `tokenizer_revision`, `seed` | Versões imutáveis ou hashes, e seed anunciada. |
| `gpu_model`, `gpu_count`, `device`, `driver_version`, `python_version`, `torch_version`, `runtime_version` | Hardware realmente utilizado e ambiente observado; não copie uma promessa de oferta. |
| `precision`, `batch`, `context` | Configuração realmente aplicada. |
| `phase`, `run_index`, `warmup_iterations` | Fase separada (`cold` ou `warm`, por exemplo), número da passagem, número de aquecimentos. Não misture as durações. |
| `expected_ids`, `observed_ids` | Quantidades de IDs esperados e observados; as listas detalhadas são mantidas junto com as saídas. |
| `ids_match`, `format_valid` | `true`/`false` após verificação real, incluindo duplicatas e respostas adicionais. |
| `quality_metric`, `quality_threshold`, `quality_tolerance`, `quality_value` | Nome, limite e tolerância preestabelecidos, depois valor medido. Especifique o sentido da tolerância e a referência em `notes`. |
| `corpus_accepted` | `true` somente se todas as condições de validação forem satisfeitas; caso contrário, `false`. |
| `elapsed_seconds` | Duração bruta do escopo anunciado, nunca um valor esperado. |
| `baseline_allocated_bytes`, `baseline_reserved_bytes`, `peak_allocated_bytes`, `peak_reserved_bytes` | Medições distintas para o único device medido. Deixe vazios se não medidos. |
| `duration_days`, `lots`, `package_total_usd_minor` | Pacote completo escolhido, lotes faturados e preço total em centavos de USD; uma única despesa não deve ser somada cinco vezes. |
| `accepted_unique_corpora` | Número de corpus úteis distintos aceitos para a análise econômica; este campo não deve ser somado entre repetições. |
| `notes` | Escopo, incidentes, decisões de qualidade, revisão do código e referências das peças mantidas. |

## 5. Calcular sem inventar produção

O preço a comparar é o pacote inteiro de 3, 7 ou 30 dias multiplicado pelos lotes. Para B200, um lote contém duas GPUs e a tarifa já cobre esse lote. `calcul_forfaits.py` aplica essa regra às tarifas fornecidas.

Se o trabalho útil escolhido for um corpus completo aceito, `--accepted-results` deve receber o número de corpus distintos efetivamente validados no período. As cinco repetições do mesmo corpus servem para medir a variabilidade: elas não criam cinco entregáveis úteis. Fixe a unidade antes da comparação e mantenha-a para todas as variantes. Sem quantidade medida e aceita, deixe esse parâmetro ausente: apenas o custo do pacote será calculado. Não projete automaticamente uma cadência para 3, 7 ou 30 dias.

Mantenha juntos o protocolo preenchido, as saídas individuais, os controles de qualidade, o CSV bruto e o cálculo econômico. Uma configuração mais rápida mas não aceita não cumpre o mesmo objetivo. Uma configuração que excede a memória continua sendo uma observação de falha, não um tempo a ser substituído por zero.