trade-frontend/doc/vast-gpu-runbook.md

Vast GPU (kilka godzin) — runbook do trenowania + eksportu modelu

Cel: używać Vast (GPU) jako krótkiej sesji treningowej (kilka godzin), a wynik (wagi/adapter) zapisać trwałe i wersjonowane.

W tym projekcie Vast:

• nie dostaje sekretów tradingowych,
• nie ma dostępu do kluczy,
• zwraca tylko trade_intent/predykcje.

---

1) Najważniejsza zasada przy krótkim wynajmie

Vast jest “ephemeral”. Żeby nie stracić pracy:

• wszystko musi być reproducible (konfig + kod + seed),
• model output musi być mały i łatwy do przeniesienia (preferuj LoRA/adaptery),
• checkpointy i final artifacts muszą być uploadowane poza maszynę (Gitea packages/S3/scp).

---

2) Co potrzebujemy mieć gotowe przed startem sesji

2.1 Kod i entrypoint

W repo powinien istnieć “one command training”, np.:

• python -m train ... albo bash scripts/train.sh ...

Zasada: komenda sama:

• pobiera dataset (albo czyta lokalny plik),
• trenuje,
• zapisuje artifacts/,
• robi upload.

2.2 Dataset (krótki transfer)

Dla sesji “kilka godzin” unikaj wielkich transferów.

Rekomendacja:

• zbuduj dataset jako plik (np. jsonl/parquet) i spakuj (zstd),
• trzymaj wersję datasetu (hash) i loguj ją do metryk.

Źródło danych (rekomendowane u nas):

• Postgres/Timescale w k3s → eksport do pliku (offline), potem upload.

2.3 Bazowy model

Masz 2 ścieżki:

• pobierasz z internetu (HF) na Vast (szybko, ale zależy od sieci),
• albo trzymasz bazę w swoim storage i ściągasz kontrolowanie.

Na start preferuj LoRA na umiarkowanym modelu i krótkiej sekwencji.

---

3) Co uruchamiamy na Vast

3.1 Kontener

Najprościej: jeden Docker image z zależnościami (PyTorch + libs). Obraz powinien być pinned (digest) i gotowy do uruchomienia bez pip install w trakcie.

3.2 Konfiguracja treningu (config file)

Trzymaj config jako plik (np. YAML/JSON) i loguj go do artifactów:

• model_name, model_version
• dataset_version (hash)
• seq_len, batch_size, grad_accum, lr
• lora_r, lora_alpha, lora_dropout (jeśli LoRA)
• seed

3.3 Output

Preferowane outputy:

• LoRA adapter (mały): adapter.safetensors + config
• metryki treningu: metrics.json
• walidacja: eval_report.json

Opcjonalnie:

• export do ONNX/TensorRT jeśli planujesz inference poza GPU (zależne od modelu).

---

4) Gdzie trzymamy artefakty (żeby nie zniknęły)

Opcje (w kolejności prostoty):

1. scp na VPS/k3s (na start najprostsze)
2. Gitea Packages (jeśli chcesz wersjonować jako “package”)
3. S3/MinIO (najbardziej skalowalne)

Minimalne wymaganie: zawsze zapisuj model_version i dataset_version obok wag.

---

5) Jak to łączy się z executor / UI

Model na Vast zwraca trade_intent (patrz doc/drift-perp-contract.md). Executor w k3s:

• buduje features z DB,
• woła predictor,
• waliduje gates,
• loguje:
  • decision_id, model_version, features_hash, intent,
  • outcome (fill/exit).

Jeśli Vast jest niedostępny:

• executor przechodzi w observe/off (nie handluje),
• UI nadal pokazuje warstwy rynku (DLOB/ticki).

---

6) Checklist “kilka godzin” (operacyjnie)

• Vast instance: GPU + wystarczająco VRAM + szybki disk.
• Pull docker image (pinned).
• Download dataset (jedna komenda).
• Train (z logowaniem metryk co N kroków).
• Eval (krótki).
• Export adapter/weights.
• Upload artifacts (scp / packages / S3).
• Zapisz model_version do DB/config (k3s) przed użyciem.