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 tokenisointitehtäviä satunnaisesti 10 sekunnin välein. Solmut tokenisoivat syötteen Qwen2.5-Coder-tokenizerin avulla ja palauttavat tuloksen. Hub näyttää tulokset terminaalissa ja välittää ne dashboardiin.

Kaksi tapaa osallistua verkkoon

1. Selainsolmu (Wasm + WebGPU)

• Avaa http://localhost:3000 selaimessa ja klikkaa "Liity laskentaverkkoon"
• Selain tunnistaa automaattisesti WebGPU-tuen — jos ei löydy, käytetään CPU-fallbackia
• Tokenizer ladataan HuggingFacesta ensimmäisellä kerralla ja tallennetaan IndexedDB:hen
• GPU-kuormitusta voi säätää sliderilla (0–75 %)

2. Natiivi-node (Rust + NVML)

• Kerää nvidia-smi-tason laitteistotiedot: GPU-nimi, VRAM, lämpötila, kuormitus
• Raportoi järjestelmätiedot: CPU-malli, ytimet, RAM, OS
• Yhdistää hubiin ja vastaanottaa tehtäviä

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

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

# 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 (valinnainen)

Jos koneessa on NVIDIA GPU ja CUDA toolkit:

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

# Muokkaa native-node/Cargo.toml:
# candle-core = { version = "0.8", features = ["cuda"] }

# Aja — malli käyttää automaattisesti GPU:ta
CARGO_TARGET_DIR=target-native HUB_URL=ws://localhost:3000/ws cargo run --release -p native-node

WebGPU-asetukset selaimessa

WebGPU ei ole oletuksena päällä kaikissa selaimissa. Jos "Liity laskentaverkkoon" -nappi käynnistää CPU-fallbackin vaikka koneessa on näytönohjain:

Chrome / Brave (Linux + Wayland):

google-chrome --enable-unsafe-webgpu --enable-features=Vulkan --ignore-gpu-blocklist --use-angle=vulkan --ozone-platform=x11

Chrome / Brave (Windows / Mac):

1. Avaa chrome://flags
2. Ota käyttöön "WebGPU" ja "Vulkan"
3. Käynnistä selain uudelleen

Firefox: about:config → dom.webgpu.enabled = true

Safari: Develop → Feature Flags → WebGPU

Projektin rakenne

network-poc/
├── hub/                  # Keskuspalvelin (Rust + Axum)
│   └── src/main.rs       #   WebSocket-reititin, tehtävien jakelu, statistiikat
├── node/                 # Selainsolmu (Rust → Wasm)
│   └── src/
│       ├── lib.rs         #   WebGPU/NdArray-laskenta, tokenisaatio, WS-yhteys
│       └── storage.rs     #   IndexedDB-välimuisti (tokenizer)
├── native-node/          # Natiivi-solmu (Rust)
│   └── src/main.rs       #   NVML GPU-tunnistus, sysinfo, WS-yhteys
├── static/
│   ├── index.html        # Dashboard-käyttöliittymä
│   └── pkg/              # Wasm-build (generoidaan)
├── docker-compose.yml
├── Dockerfile.dev        # Hub + Wasm-build
└── Dockerfile.native-node

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)

Kehitysvaihe

Tämä on proof-of-concept. Toimivat osat:

• Hub-palvelin, WebSocket-viestintä, dashboard
• WebGPU-tensorilaskenta selaimessa (Burn + Wgpu)
• CPU-fallback selaimissa ilman WebGPU-tukea (Burn + NdArray)
• Natiivi-node nvidia-smi-tason laitteistotiedoilla
• Qwen2.5-Coder-tokenizer + IndexedDB-välimuisti
• GPU-kuormituksen säätö (duty cycle throttling)

Seuraavaksi: oikea LLM-inferenssi hajautetusti (mallin painojen lataus, transformer-arkkitehtuuri Wasm/WebGPU:lla).