LÆRINGSLAB: TEKSTMODEL

1. Pak hele zip-filen ud i en mappe. Brug et Python-miljø med PyTorch installeret.
2. Åbn en terminal i mappen med train_text.py. Hvis du lavede .venv i et andet
   Python-projekt, skal du bruge det samme aktiverede miljø, når du skifter mappe.
   Learn the Machines tekstprojekt har en trinvis vejledning under "Hjælp: Find mappen og
   brug det samme Python-miljø" for macOS, Linux og PowerShell. Stierne dér er eksempler,
   som skal erstattes med dine egne mapper.

   Vil du først kontrollere Python og PyTorch, kan du køre:

   python check_environment.py

   Tjekket viser det aktive Python-program og tester én CPU-beregning. Det installerer intet.
   Derefter kører du træningen:

   python train_text.py

   Programmet opretter en ny mappe under text-transformer-runs med model.pt og text-result.json.
   Terminalen viser hele stien efter “Resultatfil til Learning Lab:”.
   Åbn den fil i Learn the Machine for at se tab, tekst før/efter, næste-tegn-fordelinger og optællinger af prompten i teksterne.
   Hvis du ikke kan finde resultatmappen, så kør i projektmappen:

   python find_runs.py

   Det viser den seneste færdige standardkørsel, dens resultatfil og en promptkommando.
   På Windows er de viste kommandoer til PowerShell, som i opsætningsvejledningen.
   Mapper oprettet med --output-dir vises ikke. Scriptet søger kun i den aktuelle mappe.
3. Kør eventuelt en ny træning med en anden læringsrate:

   python train_text.py --steps 200 --seed 7 --lr 0.01

   Sammenlign de to resultatfiler i Learn the Machine.
4. Prøv en prompt. Erstat DIN-MAPPE med navnet på en resultatmappe:

   python probe_text.py --run-dir text-transformer-runs/DIN-MAPPE --prompt "en kat "

   Åbn den nye text-probe-….json i Learn the Machine. Du kan kun bruge tegn fra det lille datasæt.
5. Undersøg et kausalt indgreb:

   python patch_text.py --run-dir text-transformer-runs/DIN-MAPPE

   Åbn den nye text-patch-….json i Learn the Machine. Prøv også --position 4 og sammenlign.
   Positioner tælles fra 1; uden valget bruges sidste position. I denne model bør et
   indgreb tidligere i det eneste lag ikke ændre sidste positions logits. Det er en
   arkitekturbestemt kontrol, ikke en regel for modeller med flere lag. Resultatet indeholder
   hashes for de tre programfiler og PyTorch-version; ældre filer kan mangle dem.

Modellen er en meget lille tegnmodel, trænet på få kunstige sætninger. Den er ikke en chatassistent.
For nye kørsler kontrolleres, om model.pt matcher hashen i text-result.json. Ældre resultater uden
modelhash kan stadig åbnes, men sammenhængen mellem filerne kan ikke bekræftes med denne kontrol.

SEPARAT TEST AF TEGNMODELLEN

Når du har valgt modellen, redigér text-test-eksempel.json. Testteksterne skal
have 25–2000 tegn og kun bruge tegn fra modellens ordforråd. Kør:

   python evaluate_text.py --run-dir text-transformer-runs/DIN-MAPPE --test text-test-eksempel.json

Erstat mappen. Kør evt. python find_runs.py --text-test min-tegntest.json
for en kommando med den seneste standardmodel. Brugte du egne træningsdata,
tilføj --data med den samme fil både her og ved evalueringen.
Programmet genmåler også validering på samme checkpoint. Åbn den gemte
text-test-…json på sammenligningstrinnet. Programmet afviser
identiske tekster og viser eksakt overlap, men kan ikke bevise uafhængighed.
Validering og test er gennemsnit over overlappende vinduer, ikke uafhængige observationer.

EGET DATASÆT

Åbn egne-tekster.json i en teksteditor. Ret listerne "train" og "validation" med dine egne
tekster, og gem som UTF-8. Du kan også hente mine-tekster.json fra Learn the Machines datasætbygger
og flytte den til denne mappe. Hver tekst skal være 25–2000 tegn; brug 1–20 tekster i hver liste.
Ingen hel tekst må være identisk på tværs af listerne. Resultatfilen tæller desuden præcise
12-tegns valideringsudsnit, der også findes i træning, samt tab for hver valideringstekst
før og efter træning; nul match beviser ikke uafhængighed.
Alle valideringstegn skal også findes
i træningsteksterne, fordi tegnordforrådet alene opbygges fra træningsdata. Samlede tekster
må højst være 12000 tegn og ordforrådet højst 256 forskellige tegn.

   python train_text.py --data egne-tekster.json --prompt "en model "

Hvis du bruger filen fra datasætbyggeren, kør i stedet:

   python train_text.py --data mine-tekster.json

Vælg en anden --prompt, hvis dens tegn ikke findes i dine træningstekster. Senere prompter
og tegn til indgreb skal ligeledes bruge det gemte ordforråd. Forskellige tekster er ikke
nødvendigvis uafhængige: tekst, der næsten er kopieret, kan gøre valideringen optimistisk.

TRÆN TO TOKENIZERS (VALGFRIT)

Installér det ekstra bibliotek i dit Python-miljø:

   python -m pip install "tokenizers>=0.20,<0.22"

Kør derefter:

   python train_bpe.py --data egne-tekster.json

For filen fra datasætbyggeren bruger du i stedet:

   python train_bpe.py --data mine-tekster.json

Programmet træner to ByteLevel BPE-tokenizers kun på træningsteksterne. Kør eventuelt
python find_runs.py --data mine-tekster.json for at finde de nyeste standardmapper med samme datahash
og få den næste kommando. Det gælder tegnmodel, tokenizer og BPE-model hver for sig; de behøver
ikke være fra samme forsøg. Brug egne-tekster.json, hvis det var den fil, du trænede på. Åbn bpe-result.json
fra den nye bpe-runs-mappe i Learn the Machine. Du kan ændre de ønskede ordforrådsstørrelser med
--small og --large (mellem 256 og 512). Små datasæt giver ikke altid det ønskede antal tokens.
Valideringsresultatet kan afsløre forskelle i opdeling, men et lavere tokenantal beviser ikke,
at en sprogmodel bliver bedre. De to tokenizerfiler kan åbnes med Hugging Face Tokenizers.

TRÆN EN TRANSFORMER MED DIN BPE-TOKENIZER (VALGFRIT)

Vil du først tjekke både PyTorch og tokenizer-biblioteket i dette miljø, kør:

   python check_environment.py --bpe

Brug samme datafil og den mappe, som train_bpe.py oprettede. Udskift DIN-MAPPE:

   python train_bpe_model.py --data egne-tekster.json --tokenizer-dir bpe-runs/DIN-MAPPE

Hvis tokenizertræningen brugte mine-tekster.json, skal du også bruge den her:

   python train_bpe_model.py --data mine-tekster.json --tokenizer-dir bpe-runs/DIN-MAPPE

Uden --data viser find_runs.py de nyeste resultater uanset datasæt og foreslår eksempeldata
til tokenizerkommandoen. Med --data sammenlignes den gemte datahash for alle tre projekttyper;
redigerbare filer beviser ikke deres oprindelse.

Programmet træner en lille transformer på token-ID'er fra den store tokenizer. Vælg den lille
med --which small. Åbn bpe-model-result.json i Learn the Machine. Programmet kontrollerer de gemte
hashes for data og tokenizer, men redigerbare filer er ikke bevis for, hvordan de blev lavet.
Tab måles pr. token og kan ikke direkte sammenlignes mellem forskellige tokenizer-ordforråd.
Denne model har sit eget format og kan ikke åbnes med tegnmodellens probe- og patch-programmer.

SAMMENLIGNING PÅ TVÆRS AF TOKENIZERS

Nye BPE-modelkørsler gemmer også en valideringsscore i bits pr. UTF-8-byte. For hvert
valideringsdokument scores alle tokens i tokenizerens valgte opdeling én gang, fra et særligt
start-ID og med højst otte forudgående ID'er. Slut-ID scores ikke. Dette er ikke den eksakte
sandsynlighed for byteteksten, fordi alternative tokenopdelinger ikke summeres. Se de to
resultater i Learn the Machine; forskellige ordforråd ændrer både modelstørrelse og tekstmængden i
konteksten, så ét forsøg viser ikke en generelt bedre tokenizer.

UNDERSØG EN TRÆNET BPE-MODEL

Brug BPE-modelmappen fra train_bpe_model.py og den nyeste projektpakke:

   python probe_bpe_model.py --run-dir bpe-model-runs/DIN-MAPPE --prompt "en kat "

Åbn bpe-probe-….json i Learn the Machine. Vælg en position for at se attention-vægte;
START er det ekstra start-ID, så længe det er med i de seneste otte positioner. Modelfil,
tokenizer og arkitektur kontrolleres mod resultatfilens hashes. Hashes i redigerbare filer
beviser ikke kørslens oprindelse. Nye promptresultater kræver BPE-modeller med start-ID.

KAUSALT INDGREB I BPE-MODELLEN

Brug den gemte BPE-modelmappe og den nyeste projektpakke:

   python patch_bpe_model.py --run-dir bpe-model-runs/DIN-MAPPE

Tilføj --check-only for at se token-ID’er og kontrollere konteksterne uden indgreb.
Hvis du hentede bpe-promptpar.json fra Learn the Machine, læg filen i projektmappen og tilføj
--case bpe-promptpar.json. Filen indeholder tekster og hashes og må ikke kombineres med
--source, --target eller --candidate. Python kontrollerer model, tokenizer og tokenbetingelser igen.

Åbn bpe-patch-….json i Learn the Machine. A og B skal have lige mange positioner i den faktiske
kontekst og samme sidste token-ID. --source og --target ændrer prompterne; --candidate vælger
et stykke tekst, der skal blive præcis ét token, når det tokeniseres alene. Sammenlign med
identitetskontrollen og nulstillingen. I denne étlagsmodel er lighed med A's sidste output
forventet af arkitekturen; det er ikke en generel mekanistisk forklaring.

TEST EN GEMT BPE-MODEL PÅ ANDRE TEKSTER

Når model og indstillinger er valgt, kan du redigere test-eksempel.json med egne tekster
og køre denne kommando i projektmappen. Brug den samme --data-fil som til træningen:

   python evaluate_bpe_model.py --run-dir bpe-model-runs/DIN-MAPPE --data egne-tekster.json --test test-eksempel.json

Du kan også køre python find_runs.py --data egne-tekster.json og kopiere den viste
testkommando for den nyeste BPE-model med matchende datahash. Brug mine-tekster.json,
hvis det er din datafil. Hjælperen finder kun standardmapper, ikke --output-dir-mapper;
kontrollér at det er den model, du har valgt, før du tester.

Åbn bpe-test-….json i Learn the Machine. Programmet ændrer ikke modellen og afviser hele
tekster, som er ens med træning eller validering efter normalisering. Næsten ens tekster,
indhold brugt til modelvalg og anden lækage opdages ikke. Resultatet viser desuden
overlap af 8-tegnsvinduer efter normalisering; små fælles tekststykker kan være almindelige
og manglende overlap beviser ikke uafhængighed. Test-eksemplet deler ord og indhold med
træningsdata; det er ikke en garanti for en uafhængig sluttest.

HVIS DU SIDDER FAST

Kan Python ikke finde train_text.py? Pak hele zip-filen ud, og aabn terminalen i mappen
med filen. Se terminalens aktuelle mappe med:

   python -c "import os; print(os.getcwd())"

Mangler PyTorch? Aktivér dit tidligere Python-miljoe og undersoeg hvilket Python-program
du bruger, samt om PyTorch er installeret i det:

   python -c "import sys; print(sys.executable)"
   python -c "import torch; print(torch.__version__)"

Hvis testen fejler, foelg Python og PyTorch-vejledningen i Learn the Machine for dit system.
Bruger du python3 eller py til miljoeet, saa brug den samme kommando paa alle trin.
Ved egne data skal alle tegn i validering og prompt findes i traeningsteksterne.
Laes den konkrete fejl; en anden fejl kan have en anden aarsag.

VALGFRIT: SAMMENLIGN KONTEKST PAA SAMME FACIT
Koer python train_text.py --compare-context for at traene og derefter maale samme valideringsfacit med forskellige kontekstlaengder. Den ekstra maaling kan tage tid og indgaar i text-result.json sammen med tre korte udsnit af valideringsteksterne. Brug ikke foelsomme tekster, og kontroller filen foer deling. Til egne data tilfoejes --data mine-tekster.json. Kortere kontekst aendrer ogsaa positionerne i modellen; vinduerne overlapper.

LILLE MOE-TEKSTMODEL (VALGFRIT)

Når du har trænet en BPE-tokenizer, kan du træne en separat transformer med
tre feed-forward-eksperter og en top-2-router:

   python train_bpe_moe.py --tokenizer-dir bpe-runs/DIN-MAPPE --which large --steps 100

Erstat mappen; tilføj --data med samme datafil som til tokenizertræningen. Åbn
moe-result.json på MoE-trinnet i Learn the Machine. Modellen er ikke kompatibel med
probe_bpe_model.py eller patch_bpe_model.py, som forventer en anden arkitektur.
Gemte filer kan indeholde prompt og genereret tekst.

UNDERSØG EKSPERTERNES EFFEKT (VALGFRIT)

Brug de samme data og den samme tokenizer, som til MoE-træningen:

   python analyze_bpe_moe.py --run-dir moe-runs/DIN-MODEL --tokenizer-dir bpe-runs/DIN-TOKENIZER

Erstat begge mapper og tilføj --data, hvis du brugte en anden datafil. Åbn først
moe-result.json og derefter den nye moe-ablation-...json på MoE-trinnet. Analysen
nulstiller én eksperts output ad gangen uden at ændre ruter eller genoptræne.

SAMMENLIGN TO MODELLER (VALGFRIT)

Træn en ny MoE-model med samme data og tokenizer og et andet --seed, kør
indgrebsanalysen på begge modeller med denne version af analyseprogrammet,
og åbn først model A og dens indgreb. Under sammenligningen vælger du derefter
indgrebsfilen fra model B. Ekspertnumre er lokale til hver model.

Den opdaterede analyse tæller også, hvor mange overlappende valideringsvinduer
der får højere, lavere eller næsten uændret gennemsnitstab ved hvert indgreb.
Det er ikke uafhængige målinger og beskriver ikke effekternes størrelse.

EKSTRA TESTTEKSTER TIL MOE-INDGREB (VALGFRIT)

Tilføj --test test-eksempel.json til analyze_bpe_moe.py for at måle det samme
indgreb på andre tekster. Filen må redigeres og skal indeholde en test-liste;
hver tekst skal give mindst otte tokens og må ikke være ens med træning eller
validering efter normalisering. Resultatet viser også overlap af otte tegn.
Det synlige eksempel er ikke en urørt test, og overlappende tekstvinduer er ikke
uafhængige observationer.
