# Protokół: zaakceptowany korpus przed porównaniem kosztu

Wersja 1 — 24 września 2026. Ta karta proponuje protokół do wypełnienia; nie zawiera żadnych zmierzonych wyników ani zbioru danych. Powiązany notebook używa małego syntetycznego MLP, aby nauczyć się mierzyć pamięć. Nie wykonuje poniższego protokołu biznesowego.

## 1. Zdefiniuj użyteczną pracę przed próbami

Przykład pracy: klasyfikacja korpusu **1 000 tekstów**. Samodzielnie przygotuj dozwolony zbiór, reprezentatywny dla Twojego zastosowania, z unikalnym identyfikatorem i zweryfikowanym odniesieniem dla każdego tekstu. Ustal rewizję korpusu, modelu, tokenizera, kodu i ziarno. Przechowuj osobno listę oczekiwanych identyfikatorów i pojedyncze wyniki, aby umożliwić audyt.

Przed jakimkolwiek pomiarem zdefiniuj: klasy, format wyjścia, główną metrykę (na przykład macro-F1), jej próg akceptacji i maksymalny dozwolony spadek względem referencji. Wybierz tolerancję odpowiednią dla swojego zastosowania; żadna uniwersalna wartość nie jest tu podana. Dane treningowe, dostrajające i ewaluacyjne muszą pozostać rozdzielone.

Korpus zostaje zaakceptowany tylko wtedy, gdy wszystkie 1 000 oczekiwanych identyfikatorów jest obecnych dokładnie raz, w wynikach nie ma żadnych dodatkowych odpowiedzi, format jest poprawny, a wcześniej ustalona reguła jakości jest spełniona. Dwa pliki zawierające po 1 000 wierszy same w sobie nie dowodzą równości identyfikatorów. Zarchiwizuj kontrolę zbiorów i duplikatów.

## 2. Zmieniaj tylko zapowiedziany wariant

Aby zbadać batch, przygotuj na przykład warianty 1, 4 i 8. Zachowaj ten sam korpus, kolejność wejść, model, tokenizer, precyzję i limit kontekstu. Jeśli następnie badasz precyzję, utwórz osobne doświadczenie i ponownie przeprowadź kontrolę jakości. Opisz obcinanie: skracanie tekstów zmienia wykonaną pracę.

Zarejestruj rzeczywisty GPU, liczbę faktycznie użytych GPU, device, sterownik, Python, PyTorch oraz runtime CUDA lub ROCm. Zapisz także wersję swojego kodu, ewentualne opcje generowania i wszelką konkurencję na maszynie w `notes`. Komercyjny pakiet dwóch GPU nie oznacza, że program używa obu.

## 3. Mierz porównywalne przebiegi

Zapowiedz, co obejmuje stoper: samo przetwarzanie czy pełny łańcuch z odczytem, tokenizacją i zapisem. Oddziel ładowanie, pierwszy przebieg i przebiegi rozgrzane. Skrypt pamięci mierzy tylko swój MLP i nie mierzy czasu pełnego łańcucha klasyfikacji.

Wykonaj zapowiedziane rozgrzewanie, a następnie pięć zmierzonych przebiegów na wariant w kolejności naprzemiennej lub wylosowanej z góry. Zachowaj każdy surowy czas. Podanie mediany i zakresu min–max pozwala zobaczyć rozproszenie; pięć obserwacji nie uzasadnia solidnego oszacowania p95. Nie pomijaj po cichu błędu ani wolnego przebiegu: zachowaj jego wiersz i wyjaśnij incydent. Uruchom ponownie w nowym procesie, jeśli chcesz porównać pierwsze przebiegi w podobnych warunkach.

Dla pomiarów GPU PyTorch zsynchronizuj wybrany device przed początkowym odczytem i po operacji. Zarejestruj baseline `allocated` i `reserved`, zresetuj statystyki szczytowe, a następnie zachowaj absolutne szczyty fazy. `allocated` zawiera się w `reserved`: dodanie ich liczyłoby część pamięci dwukrotnie. Oba maksima mogą zostać osiągnięte w różnych momentach: ich różnica nie jest pomiarem cache w danym momencie. Alokacje innych procesów i te poza alokatorem PyTorch nie są objęte.

## 4. Wypełnij resultats-bruts.csv

Dystrybuowany CSV zawiera wyłącznie nagłówki. Zapisz jeden wiersz na przebieg, z kropką dziesiętną i sekundami dla czasów, bajtami dla pamięci i centami USD dla stawki. Pusta komórka oznacza „nie zarejestrowano”; zero oznacza rzeczywiście zero. Przecinki obecne w notatce należy zabezpieczyć zwykłymi regułami CSV.

| Pola | Znaczenie i wprowadzanie |
| --- | --- |
| `experiment_id`, `variant_id` | Stabilne identyfikatory eksperymentu i wariantu. |
| `corpus_revision`, `model_revision`, `tokenizer_revision`, `seed` | Niezmienne wersje lub skróty oraz zadeklarowany seed. |
| `gpu_model`, `gpu_count`, `device`, `driver_version`, `python_version`, `torch_version`, `runtime_version` | Sprzęt faktycznie użyty i zaobserwowane środowisko; nie przepisuj obietnicy z oferty. |
| `precision`, `batch`, `context` | Konfiguracja faktycznie zastosowana. |
| `phase`, `run_index`, `warmup_iterations` | Oddzielna faza (`cold` lub `warm`, na przykład), numer przebiegu, liczba rozgrzewek. Nie mieszaj czasów trwania. |
| `expected_ids`, `observed_ids` | Liczby oczekiwanych i zaobserwowanych ID; szczegółowe listy są przechowywane razem z wynikami. |
| `ids_match`, `format_valid` | `true`/`false` po rzeczywistej weryfikacji, z uwzględnieniem duplikatów i dodatkowych odpowiedzi. |
| `quality_metric`, `quality_threshold`, `quality_tolerance`, `quality_value` | Nazwa, próg i tolerancja ustalone wcześniej, a następnie zmierzona wartość. W `notes` podaj kierunek tolerancji i punkt odniesienia. |
| `corpus_accepted` | `true` tylko wtedy, gdy spełnione są wszystkie warunki walidacji; w przeciwnym razie `false`. |
| `elapsed_seconds` | Surowy czas trwania zadeklarowanego zakresu, nigdy wartość oczekiwana. |
| `baseline_allocated_bytes`, `baseline_reserved_bytes`, `peak_allocated_bytes`, `peak_reserved_bytes` | Oddzielne odczyty dla jedynego mierzonego device. Pozostaw puste, jeśli nie zmierzono. |
| `duration_days`, `lots`, `package_total_usd_minor` | Wybrany pełny pakiet, rozliczone loty i cena łączna w centach USD; jednego wydatku nie wolno sumować pięć razy. |
| `accepted_unique_corpora` | Liczba odrębnych użytecznych korpusów zaakceptowanych do analizy ekonomicznej; tego pola nie należy sumować między powtórzeniami. |
| `notes` | Zakres, incydenty, decyzje jakościowe, rewizja kodu i odniesienia do zachowanych materiałów. |

## 5. Obliczaj, nie wymyślając produkcji

Ceną do porównania jest cały pakiet 3, 7 lub 30 dni pomnożony przez loty. Dla B200 jeden lot zawiera dwa GPU, a taryfa obejmuje już ten lot. `calcul_forfaits.py` stosuje tę regułę do podanych taryf.

Jeśli wybraną użyteczną pracą jest pełny zaakceptowany korpus, `--accepted-results` musi otrzymać liczbę odrębnych korpusów faktycznie zwalidowanych w danym okresie. Pięć powtórzeń tego samego korpusu służy do pomiaru zmienności: nie tworzą one pięciu użytecznych rezultatów. Ustal jednostkę przed porównaniem i zachowaj ją dla wszystkich wariantów. Bez zmierzonej i zaakceptowanej ilości pozostaw ten parametr nieobecny: obliczony zostanie tylko koszt pakietu. Nie rzutuj automatycznie tempa na 3, 7 lub 30 dni.

Przechowuj razem wypełniony protokół, pojedyncze wyniki, kontrole jakości, surowy CSV i obliczenia ekonomiczne. Szybsza, ale niezaakceptowana konfiguracja nie realizuje tego samego celu. Konfiguracja przekraczająca pamięć pozostaje obserwacją niepowodzenia, a nie czasem do zastąpienia zerem.