# Protocol: een corpus geaccepteerd voordat je de kosten vergelijk

Versie 1 — 24 september 2026. Deze fiche biedt een in te vullen protocol; ze bevat geen enkel gemeten resultaat of dataset. De bijbehorende notebook gebruikt een kleine synthetische MLP om te leren het geheugen af te lezen. Hij voert het onderstaande zakelijke protocol niet uit.

## 1. Het nuttige werk definiëren vóór de tests

Voorbeeld van werk: een corpus van **1 000 teksten** classificeren. Stel zelf een toegestane set samen, representatief voor jouw gebruik, met een unieke identificatie en een geverifieerde referentie per tekst. Leg de revisie vast van het corpus, het model, de tokenizer, de code en de seed. Bewaar afzonderlijk de lijst met verwachte IDs en de individuele uitvoer zodat een audit mogelijk is.

Definieer vóór elke meting: de klassen, het uitvoerformaat, de hoofdexponent (bijvoorbeeld macro-F1), de acceptatiedrempel en de maximaal toegestane verslechtering ten opzichte van een referentie. Kies een tolerantie die relevant is voor jouw toepassing; hier wordt geen universele waarde gegeven. De trainings-, afstel- en evaluatiedata moeten gescheiden blijven.

Een corpus wordt alleen geaccepteerd als de 1 000 verwachte IDs precies één keer aanwezig zijn, er geen extra antwoorden in de uitvoer staan, het formaat geldig is en aan de vooraf vastgestelde kwaliteitsregel is voldaan. Twee bestanden met elk 1 000 regels bewijzen op zichzelf niet dat de IDs gelijk zijn. Archiveer de controle op de sets en op duplicaten.

## 2. Alleen de aangekondigde variant wijzigen

Om de batch te bestuderen, maak je bijvoorbeeld varianten 1, 4 en 8. Behoud hetzelfde corpus, dezelfde volgorde van invoer, hetzelfde model, dezelfde tokenizer, dezelfde precisie en dezelfde contextlimiet. Als je daarna de precisie bestudeert, maak dan een apart experiment en voer opnieuw de kwaliteitscontrole uit. Beschrijf de truncatie: teksten inkorten verandert het verrichte werk.

Noteer de werkelijke GPU, het aantal daadwerkelijk gebruikte GPU's, het device, het stuurprogramma, Python, PyTorch en de runtime CUDA of ROCm. Vermeld ook de versie van je code, de eventuele generatie-opties en elke gelijktijdige belasting op de machine in `notes`. Een commercieel pakket van twee GPU's betekent niet dat het programma ze beide gebruikt.

## 3. Vergelijkbare runs meten

Kondig aan wat de stopwatch omvat: alleen de verwerking of de volledige keten met lezen, tokeniseren en schrijven. Splits het laden, de eerste run en de opgewarmde runs. Het geheugenscript meet alleen zijn MLP en meet niet de tijd van een volledige classificatieketen.

Voer de aangekondigde opwarming uit en doe daarna vijf gemeten runs per variant in een afwisselende of vooraf getrokken volgorde. Bewaar elke ruwe duur. De mediaan en het min–max-bereik rapporteren laat de spreiding zien; vijf observaties rechtvaardigen geen robuuste schatting van de p95. Laat een fout of een trage run niet stilzwijgend weg: bewaar de regel en verklaar het incident. Start opnieuw in een vers proces als je de eerste runs onder vergelijkbare omstandigheden wilt vergelijken.

Voor PyTorch GPU-metingen synchroniseer je het gekozen device vóór de initiële meting en na de bewerking. Lees de baselines `allocated` en `reserved` af, reset de piekstatistieken en bewaar vervolgens de absolute pieken van de fase. `allocated` is inbegrepen in `reserved`: ze optellen zou een deel van het geheugen dubbel tellen. De twee maxima kunnen op verschillende momenten worden bereikt: hun verschil is geen meting van de cache op één bepaald moment. De toewijzingen van andere processen en die buiten de PyTorch-allocator vallen hier niet onder.

## 4. resultats-bruts.csv invullen

Het gedistribueerde CSV-bestand bevat alleen de headers. Schrijf één regel per run, met een decimaalpunt en seconden voor de tijden, bytes voor het geheugen en USD-centen voor het forfait. Een lege cel betekent "niet gemeten"; nul betekent werkelijk nul. Komma's in een notitie moeten met de gebruikelijke CSV-regels worden beschermd.

| Velden | Betekenis en invoer |
| --- | --- |
| `experiment_id`, `variant_id` | Stabiele identificaties van het experiment en de variant. |
| `corpus_revision`, `model_revision`, `tokenizer_revision`, `seed` | Onveranderlijke versies of hashes, en de aangekondigde seed. |
| `gpu_model`, `gpu_count`, `device`, `driver_version`, `python_version`, `torch_version`, `runtime_version` | Werkelijk gebruikte hardware en waargenomen omgeving; neem geen belofte uit een aanbod over. |
| `precision`, `batch`, `context` | Werkelijk toegepaste configuratie. |
| `phase`, `run_index`, `warmup_iterations` | Aparte fase (`cold` of `warm`, bijvoorbeeld), nummer van de passage, aantal warmups. Meng de duurmetingen niet. |
| `expected_ids`, `observed_ids` | Aantallen verwachte en waargenomen IDs; de gedetailleerde lijsten worden samen met de uitvoer bewaard. |
| `ids_match`, `format_valid` | `true`/`false` na werkelijke controle, inclusief duplicaten en extra antwoorden. |
| `quality_metric`, `quality_threshold`, `quality_tolerance`, `quality_value` | Vooraf vastgestelde naam, drempel en tolerantie, en daarna de gemeten waarde. Vermeld de betekenis van de tolerantie en de referentie in `notes`. |
| `corpus_accepted` | `true` alleen als aan alle validatievoorwaarden is voldaan; anders `false`. |
| `elapsed_seconds` | Ruwe duur van het aangekondigde bereik, nooit een verwachte waarde. |
| `baseline_allocated_bytes`, `baseline_reserved_bytes`, `peak_allocated_bytes`, `peak_reserved_bytes` | Afzonderlijke metingen voor alleen het gemeten device. Laat leeg als ze niet zijn gemeten. |
| `duration_days`, `lots`, `package_total_usd_minor` | Gekozen volledig pakket, gefactureerde lots en totale prijs in USD-centen; één enkele uitgave mag niet vijf keer worden opgeteld. |
| `accepted_unique_corpora` | Aantal bruikbare, afzonderlijke corpora dat voor de economische analyse is geaccepteerd; dit veld mag niet tussen herhalingen worden opgeteld. |
| `notes` | Bereik, incidenten, kwaliteitsbeslissingen, coderevisie en referenties van de bewaarde stukken. |

## 5. Rekenen zonder productie te verzinnen

De te vergelijken prijs is het volledige pakket van 3, 7 of 30 dagen vermenigvuldigd met de lots. Voor B200 bevat één lot twee GPU's en het tarief dekt dat lot al. `calcul_forfaits.py` past deze regel toe op de aangeleverde tarieven.

Als het gekozen nuttige werk een volledig geaccepteerd corpus is, moet `--accepted-results` het aantal afzonderlijke corpora krijgen dat daadwerkelijk in de periode is gevalideerd. De vijf herhalingen van hetzelfde corpus dienen om de variabiliteit te meten: ze leveren geen vijf nuttige deliverables op. Leg de eenheid vast vóór de vergelijking en houd die aan voor alle varianten. Zonder gemeten en geaccepteerde hoeveelheid laat u deze parameter weg: alleen de kosten van het pakket worden berekend. Projecteer niet automatisch een tempo op 3, 7 of 30 dagen.

Bewaar het ingevulde protocol, de individuele uitvoer, de kwaliteitscontroles, de ruwe CSV en de economische berekening samen. Een snellere maar niet geaccepteerde configuratie vervult niet hetzelfde doel. Een configuratie die het geheugen overschrijdt, blijft een mislukte observatie, geen tijd die door nul moet worden vervangen.