# Príprava a spustenie experimentov na Perune

Postup pre dotrénovanie `ministral/Ministral-3b-instruct` na slovenskej časti Aya Collection metódou SFT s LoRA v LLaMA-Factory a Unslothe. Výsledky dokončeného behu sú v [dokumentácii experimentu](ministral_3b_aya/README.md). Príprava kontajnera aj vyhodnotenie v SK-bench sú v [návode pre SK-bench](SK_BENCH.md).

## 1. Pripojenie a cesty

Po pripojení na VPN Peruna je potrebné prihlásiť sa na uzol `login01` cez SSH.

```bash
ssh jascke919@login01.perun.tuke.sk
```

Príkazy predpokladajú, že priečinok `perun` z repozitára je v projektovom úložisku. Pri prvom prenose sa nasledujúci príkaz spúšťa v PowerShelli z koreňa lokálneho repozitára. Pri ďalších behoch sa používa existujúca kópia priečinka na Perune.

```powershell
scp -r .\perun jascke919@login01.perun.tuke.sk:/mnt/project/perun26012578/
```

Premenné je potrebné nastaviť na prihlasovacom uzle v relácii, z ktorej sa odosielajú joby.

```bash
export PROJECT=/mnt/project/perun26012578
export APPHOME=/mnt/home/jascke919/apphome
export TRAIN_ENV=/mnt/home/jascke919/aya_train_perun_managed
export PY="$TRAIN_ENV/bin/python"
cd "$PROJECT/perun"
mkdir -p logs
```

## 2. Príprava prostredia

Na prípravu dát je potrebný obraz `$APPHOME/cuda.sif` a Python 3.13 s PyArrow v `$APPHOME/venv`. Postup prvotnej inštalácie je v [príprave kontajnera SK-bench](SK_BENCH.md#1-príprava-kontajnera).

Tréning a Aya test používajú samostatné prostredie s Pythonom 3.11. Na Perune fungovalo prostredie vytvorené cez `uv --managed-python`. Obsahuje hlavičku `Python.h`, ktorú potrebuje Triton. V existujúcom prostredí `aya_train_perun_managed` sa závislosti overia cez `"$PY" -m pip check`. Pri novej inštalácii sa nasledujúce príkazy spúšťajú z priečinka `perun` s dostupným `uv`.

```bash
uv venv --managed-python --python 3.11 --seed "$TRAIN_ENV"
"$PY" -c 'import pathlib, sysconfig; p = pathlib.Path(sysconfig.get_path("include")) / "Python.h"; assert p.is_file(), p; print(p)'

"$PY" -m pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 xformers==0.0.29.post3 \
  --index-url https://download.pytorch.org/whl/cu124
"$PY" -m pip install -r requirements/training.txt
"$PY" -m pip check
```

Pred prvým GPU jobom je potrebné stiahnuť základný model do cache Hugging Face. Príkaz vyžaduje prístup na internet a rovnaké nastavenie cache ako tréningový job.

```bash
"$PY" - <<'PYTHON'
from huggingface_hub import snapshot_download

snapshot_download(
    "ministral/Ministral-3b-instruct",
    revision="2c95908929198d6e69af8638f0dbbd9bc6b93f9e",
)
PYTHON
```

## 3. Príprava Aya dát na CPU

Zdrojový súbor je na Perune v `/mnt/project/perun26012578/raw/slovak_train.parquet`. Pripravené dáta sú v `data/aya_slovak_fixed`. Ak priečinok obsahuje pôvodný manifest a rozdelené dáta, pokračuje sa kontrolou tréningovej konfigurácie. Pri príprave od začiatku musí byť výstupný priečinok nový alebo prázdny.

Ak zdrojový Parquet na Perune chýba, po pripojení na VPN sa prenesie cez `scp`. Príkaz sa spúšťa z lokálneho priečinka so súborom.

```powershell
scp .\slovak_train.parquet jascke919@login01.perun.tuke.sk:/mnt/project/perun26012578/raw/
```

Kontrolný súčet pôvodného Parquetu sa overí cez `sha256sum "$PROJECT/raw/slovak_train.parquet"`. Očakávaný SHA-256 je `6a21c52b80549cbb8f9d13de981a2d8f65c273a17f651fd09c1efcc952821e82`.

```bash
sbatch --job-name=aya_prepare \
  --account=perun26012578 --partition=cpu_short \
  --nodes=1 --ntasks=1 --cpus-per-task=4 --mem=24G \
  --time=08:00:00 --output=logs/aya_prepare_%j.out \
  --wrap='apptainer exec --home "$APPHOME" \
    --bind "$PROJECT:$PROJECT" \
    --pwd "$PROJECT/perun" "$APPHOME/cuda.sif" \
    "$APPHOME/venv/bin/python" -u scripts/prepare_data.py \
    --local-parquet "$PROJECT/raw/slovak_train.parquet" \
    --output-dir data/aya_slovak_fixed --seed 42 --eval-size 1000 --test-size 1000'
```

Príprava odstráni neplatné riadky a duplicitné páry. Rovnaké normalizované zadania drží v jednej množine. Po pôvodnom jobe 145681 obsahoval [manifest](ministral_3b_aya/training/data_manifest.json) **3 490 041 tréningových, 1 000 validačných a 1 000 testovacích príkladov**. Skript uchováva celé texty a limit 4 096 tokenov sa uplatňuje pri tokenizácii konkrétneho behu.

## 4. Kontrola, pilot a plný tréning

Konfigurácia [`configs/ministral.yaml`](configs/ministral.yaml) používa nastavenia plného behu s learning rate `0.0002`. Skript spustí štyri tréningové procesy cez DDP. Slurm preto dostane jeden task a štyri GPU na jednom uzle.

```bash
export RUN="$PROJECT/perun/runs/ministral_aya_$(date +%Y%m%d_%H%M%S)"
"$PY" scripts/train.py configs/ministral.yaml --run-dir "$RUN" --dry-run
```

Po úspešnej kontrole dát sa spúšťa pilot s 30 tréningovými krokmi a samostatným výstupným priečinkom. Rovnaká kontrola GPU a Tritonu sa používa aj pri plnom behu.

```bash
sbatch --job-name=ministral_pilot \
  --account=perun26012578 --partition=gpu_short \
  --nodes=1 --ntasks=1 --gres=gpu:4 --cpus-per-task=32 --mem=128G \
  --time=02:00:00 --output=logs/ministral_pilot_%j.out \
  --wrap='set -e
    "$PY" -c "import torch; assert torch.cuda.device_count() == 4; assert all(\"H200\" in torch.cuda.get_device_name(i) for i in range(4)); from triton.runtime import driver; print(driver.active.get_current_target())"
    "$PY" -u scripts/train.py configs/ministral.yaml --run-dir "${RUN}_pilot" --pilot-steps 30'
```

Pri 300k pilote sa namiesto `--pilot-steps 30` použilo `--pilot-samples 300000 --pilot-steps 9375 --pilot-eval-steps 1875`. Plný beh sa odosiela po úspešnom pilote.

```bash
sbatch --job-name=ministral_full_lr020 \
  --account=perun26012578 --partition=gpu_long \
  --nodes=1 --ntasks=1 --gres=gpu:4 --cpus-per-task=32 --mem=256G \
  --time=2-00:00:00 --output=logs/ministral_full_lr020_%j.out \
  --wrap='set -e
    "$PY" -c "import torch; assert torch.cuda.device_count() == 4; assert all(\"H200\" in torch.cuda.get_device_name(i) for i in range(4)); from triton.runtime import driver; print(driver.active.get_current_target())"
    "$PY" -u scripts/train.py configs/ministral.yaml --run-dir "$RUN"'
```

V `$RUN` vzniknú `run.json`, `used_config.yaml`, `train.log` a `adapter/`. Pri pôvodnom jobe 148065 bol posledný checkpoint **109 064**. Export v samotnom `adapter/` zodpovedá validačne najlepšiemu checkpointu **109 000**.

## 5. Aya test posledného checkpointu

Nasledujúce cesty zodpovedajú testu pôvodného jobu 148065. Pri teste nového tréningu je potrebné nastaviť cestu k novému behu a k jeho poslednému checkpointu. Evaluácia vyžaduje pôvodný manifest dát daného behu.

```bash
export RUN="$PROJECT/perun/models/ministral-3b-instruct/runs/full_aya_lr_0p000200_epoch1"
export CHECKPOINT="$RUN/adapter/checkpoint-109064"
export EVAL_OUT="$RUN/evaluations/aya_test_last_109064_$(date +%Y%m%d_%H%M%S)"

sbatch --job-name=ministral_aya_test \
  --account=perun26012578 --partition=gpu_short \
  --nodes=1 --ntasks=1 --gres=gpu:1 --cpus-per-task=8 --mem=64G \
  --time=04:00:00 --output=logs/ministral_aya_test_%j.out \
  --wrap='set -e
    "$PY" -u scripts/evaluate.py "$RUN/used_config.yaml" \
      --adapter "$CHECKPOINT" --split test \
      --output-dir "$EVAL_OUT" --max-new-tokens 256'
```

Súbor `summary.json` obsahuje testovací loss, perplexitu, tokenové F1 a normalizovanú presnú zhodu. Stav jobov sa sleduje cez `squeue -u "$USER"` a výpisy Slurmu sú v `logs/`.