agentic-studio/network-poc/USER-README.md

Kipinä Agentic Network — Hajautettu AI-laskentaverkko

Kipinä Agentic Network on hajautettu tekoälylaskentaverkko, jossa selaimet ja natiivit solmut tarjoavat GPU-laskentatehoa yhteiseen käyttöön. Hub-palvelin koordinoi tehtäviä ja solmut suorittavat ne WebGPU:lla tai CPU:lla.

Miten se toimii

┌──────────┐     WebSocket     ┌──────────┐     WebSocket     ┌──────────────┐
│  Selain  │◄─────────────────►│   Hub    │◄─────────────────►│ Natiivi-node │
│  (Wasm)  │  tehtävät/tulokset│ (Axum)   │  tehtävät/tulokset│   (Rust)     │
│  WebGPU  │                   │ :3000    │                   │ NVML/sysinfo │
└──────────┘                   └──────────┘                   └──────────────┘
     │                              │
     └── CPU fallback (NdArray)     └── Dashboard + statistiikat
         jos WebGPU ei tuettu

Hub jakaa tehtäviä (tokenisointiparit, LLM-promptit, kooditehtävät) 10 sekunnin välein. Solmut käsittelevät vain valitsemansa tehtävätyypin mukaisia viestejä.

Kolme tapaa osallistua verkkoon

1. Selainsolmu — Laskentaverkko

• Avaa http://localhost:3000 | https://kipina.studio ja valitse tehtävä:
  • Tokenisointivertailu — EN/FI-kieliparien BPE-tokenisointitehokkuus (~7 MB lataus)
  • SmolLM 135M — kevyt LLM-inferenssi (~269 MB, ~1.2 tok/s)
  • Qwen2.5 0.5B — tehokkaampi LLM (~990 MB, ~0.4 tok/s)
  • Phi-3 Mini 3.8B — vain native-nodella
• WebGPU tunnistetaan automaattisesti, CPU-fallback jos ei tuettu
• Mallit ja tokenizerit cachetetaan IndexedDB:hen

2. Selainsolmu — Koodilaboratorio

• Erillinen välilehti: Qwen2.5-Coder koodigenerointi
• Valittavissa 0.5B (nopea) tai 3B (laadukas, 6.2 GB lataus)
• Oma promptti: kirjoita Python-ohjelmointitehtävä ja paina "Generate"
• Syntaksikorostettu koodivastaus

3. Natiivi-node (Rust + CUDA/CPU)

• Qwen2.5-0.5B-Instruct inferenssi CUDA:lla (~50-100 tok/s RTX 4090) tai CPU:lla (~11 tok/s)
• Kerää nvidia-smi-tason laitteistotiedot: GPU-nimi, VRAM, lämpötila, kuormitus
• Lataa mallin automaattisesti HuggingFace Hubista (~990 MB, cachetetaan)

Käynnistys

Docker Compose (suositeltu)

# Hub + selainsolmu
docker compose up

# Hub + selainsolmu + natiivi-node (vaatii nvidia-container-toolkit)
docker compose --profile native up

Dashboard avautuu osoitteessa http://localhost:3000 | https://kipina.studio

Ilman Dockeria

# 1. Rakenna Wasm-paketti (vaatii wasm-pack)
cd node && wasm-pack build --target web --out-dir ../static/pkg && cd ..

# 2. Käynnistä hub (terminaali 1)
cargo run -p hub

# 3. Avaa selain: http://localhost:3000 | https://kipina.studio

# 4. Valinnainen: natiivi-node LLM-inferenssillä (terminaali 2)
# Lataa Qwen2.5-0.5B automaattisesti HuggingFacesta (~990 MB, cachetetaan)
# Release-moodissa ~11 tok/s CPU:lla (32 ydintä)
CARGO_TARGET_DIR=target-native HUB_URL=ws://localhost:3000/ws ALLOCATED_GB=4 cargo run --release -p native-node


# Tai yhdistä tuotantopalvelimeen:
CARGO_TARGET_DIR=target-native HUB_URL=wss://kipina.studio/ws ALLOCATED_GB=4 cargo run --release -p native-node

CUDA-tuki

CUDA on oletuksena päällä native-nodessa. Vaatii nvidia-cuda-toolkit:n:

# Asenna (Ubuntu/Pop!_OS)
sudo apt install nvidia-cuda-toolkit

# Tarkista
nvcc --version

# Aja — tunnistaa CUDA:n automaattisesti, fallback CPU:lle
CARGO_TARGET_DIR=target-native HUB_URL=ws://localhost:3000/ws cargo run --release -p native-node

# Tuotantoon
CARGO_TARGET_DIR=target-native HUB_URL=wss://kipina.studio/ws cargo run --release -p native-node

Jos CUDA:a ei ole, poista feature: candle-core = { version = "0.8" } (ilman features = ["cuda"]).

Kuinka saat WebGPU:n aktivoitua selaimessasi:

Jos käytät Chromea, Bravea tai Edgeä (Chromium-pohjainen):

• Kirjoita selaimen osoiteriville: chrome://flags (tai brave://flags / edge://flags)
• Etsi hakusanalla WebGPU tai Unsafe WebGPU (#enable-unsafe-webgpu).
• Vaihda asetus tilaan Enabled.
• (Linuxilla erityisesti saatat joutua käynnistämään selaimen terminaalin kautta komennoilla --enable-unsafe-webgpu --enable-features=Vulkan, aivan kuten olit tehnyt tämän kehityssession alussa!)

Jos käytät Firefoxia:

• Kirjoita osoiteriville: about:config
• Etsi dom.webgpu.enabled ja aseta se arvoon true.
• Etsi gfx.webgpu.force-enabled ja aseta se arvoon true.

Projektin rakenne

network-poc/
├── hub/                  # Keskuspalvelin (Rust + Axum)
│   └── src/
│       ├── main.rs       #   WebSocket-reititin, tehtävien jakelu, admin HTML, Basic Auth
│       └── db.rs         #   SQLite: node_sessions, pair_results
├── node/                 # Selainsolmu (Rust → Wasm)
│   └── src/
│       ├── lib.rs         #   Wasm-entrypoint, tehtävävalinta, WS-handler
│       ├── storage.rs     #   IndexedDB-välimuisti
│       ├── sampling.rs    #   Top-k sampling (EOS-penaltti)
│       ├── smollm.rs      #   SmolLM 135M inferenssi
│       ├── qwen.rs        #   Qwen2.5 0.5B inferenssi
│       ├── qwen_coder.rs  #   Qwen2.5-Coder 0.5B/3B koodigenerointi
│       └── phi3.rs        #   Phi-3 placeholder
├── native-node/          # Natiivi-solmu (Rust + CUDA)
│   └── src/
│       ├── main.rs       #   GPU-tunnistus, WS-yhteys, tehtäväkäsittely
│       └── inference.rs  #   Qwen2.5-0.5B Candle-inferenssi (CUDA/CPU)
├── static/
│   ├── index.html        # Dashboard + Koodilaboratorio
│   └── pkg/              # Wasm-build (generoidaan)
├── deploy.sh             # Lokaali build → palvelimelle
├── docker-compose.yml    # Kehitys
├── docker-compose.prod.yml # Tuotanto (Caddy + Hub)
├── docker-compose.client.yml # Client-nodejen Docker
├── Dockerfile.prod       # Tuotanto-image (cache mount)
└── Caddyfile.prod        # TLS + reverse proxy

Ympäristömuuttujat

Muuttuja	Oletus	Kuvaus
HUB_URL	ws://hub:3000/ws	Hub-palvelimen WebSocket-osoite (native-node)
ALLOCATED_GB	4	Solmun varaama muisti verkosta (GB)
ADMIN_PASSWORD	kipina	Admin-sivun ja API:n salasana (Basic Auth)
DATABASE_PATH	nodes.db	SQLite-tietokannan polku
STATIC_DIR	../static	Staattisten tiedostojen kansio

Admin-sivu

https://kipina.studio/admin (Basic Auth, salasana: ADMIN_PASSWORD)

Sisältää:

• Node-sessiot: IP, laitetiedot, GPU, WebGPU-tuki, tehtävätyyppi, uptime
• Tokenisointitulokset: EN/FI-vertailut, ylikustannus-%
• Yhteenvetotilastot: sessiot, WebGPU vs CPU, keskiarvot

Projektin tila

Toimivat ominaisuudet:

• Tokenisointivertailu (EN/FI, BPE, top-k sampling)
• SmolLM 135M inferenssi selaimessa (Candle + Wasm)
• Qwen2.5 0.5B inferenssi selaimessa (Candle + Wasm)
• Qwen2.5-Coder 0.5B/3B koodigenerointi (Koodilaboratorio-välilehti)
• Native node + CUDA (RTX 4090: ~50-100 tok/s)
• Admin-dashboard + SQLite + Basic Auth
• Deploy-skripti (lokaali build → palvelin)
• WebGPU + CPU fallback, GPU-tunnistus (NVIDIA/AMD/Apple)