Slotstream: Draai Qwen3.8-Flash-Next op Mac via SSD-streaming

Prestaties op een 48 GB M5 Pro

  • Warm decode: ~12 tok/s
  • Opstarten engine: ~2 s (alleen de 3,8 GB trunk wordt geladen)
  • Piekgeheugen: 32 GB (automatisch geschaald; kan handmatig worden begrensd)
  • Gewichten op schijf: 104 GB

Systeemeisen

Om slotstream te gebruiken, heb je het volgende nodig:

  • Apple Silicon
  • macOS 14 of hoger
  • Ongeveer 110 GB vrije schijfruimte

Vanwege de omvang van het model is een Mac met minimaal 512 GB opslag een realistisch minimum.

Geheugenniveaus en verwachtte prestaties

De automatische schaling neemt nooit het volledige geheugen van de machine in beslag. Onderstaande tabel toont de verdeling per niveau:

Jouw MacSlotstream verbruikWarm decode
8 GB8,1 GB (ondergrens)~3 tok/s (waarschuwing voor paging)
16 GB10 GB~4 tok/s
24 GB16 GB~8 tok/s
32 GB22 GB~9 tok/s
48 GB en hoger33 GB (meer geheugen biedt geen extra snelheid)~12 tok/s

Opmerking: Deze gegevens zijn afkomstig uit slotstream doctor --sim-ram N. Alleen de 48 GB-meting is gedaan op echte hardware; de overige waarden zijn schattingen op basis van de curve. Kleinere Macs hebben vaak ook tragere SSD's. De middelste kolom gaat ervan uit dat er geen andere programma's geheugen verbruiken; bij een open browser zal de automatische schaling minder geheugen toewijzen.

Het wordt aangeraden om slotstream doctor uit te voeren vóór de download om het plan voor jouw machine en de beschikbare schijfruimte te controleren.

Installatie

Automatische installatie

Voer de volgende opdracht uit in de terminal:

curl -fsSL https://raw.githubusercontent.com/carloslfu/slotstream/main/install.sh | sh

Dit installeert de nieuwste release in ~/.slotstream/bin en voegt dit toe aan je PATH. Herhaal dezelfde regel om te upgraden. Voor de-installatie verwijder je ~/.slotstream en de wrapper in /usr/local/bin/slotstream of de PATH-regel.

Verificatie en handmatige bouw

Releases worden gebouwd via CI met ondertekende provenance. Je kunt een asset verifiëren in plaats van blind te vertrouwen op de download:

gh attestation verify slotstream-arm64.tar.gz --repo carloslfu/slotstream

Je kunt de main branch ook zelf bouwen. Command Line Tools zijn voldoende; Xcode is niet nodig:

git clone https://github.com/carloslfu/slotstream && cd slotstream
make build

Beheer van de modelgewichten (104 GB)

Het binaire bestand is klein, maar de gewichten zijn dat niet: 103,8 GB verdeeld over 24 bestanden. De commando's serve en run bieden de download aan bij het eerste gebruik, of je kunt slotstream pull direct gebruiken. Voordat er iets wordt gedownload, toont het programma de grootte, de bestemming en de beschikbare schijfruimte; het weigert de download als er onvoldoende ruimte is.

Belangrijke details over de download:

  • Snelheid: Een installatie nam in een test 35 minuten in beslag. Hugging Face beperkt transfers tot ongeveer 36–57 MB/s, ongeacht het aantal verbindingen.
  • Betrouwbaarheid: Onderbrekingen zijn veilig. pull gaat verder waar het stopte. Alle 24 bestanden worden gecontroleerd tegen sha256-hashes in het binaire bestand om corruptie te voorkomen.
  • Verificatie: Met pull --verify kan een bestaande kopie op elk moment opnieuw worden gehasht (duurt ongeveer 8 seconden).

Gebruik

Directe prompts

Voor een enkelvoudige vraag zonder server:

slotstream run --prompt "waarom is de lucht blauw?"

Als server gebruiken

Voor integratie met andere tools start je de server, die luistert op poort 11434 en een subset van de chat/generate API's van Ollama en OpenAI implementeert:

slotstream serve

Voorbeeld van een aanvraag via curl:

curl localhost:11434/api/chat -d '{
"model": "qwen3.8-flash-next:4bit",
"messages": [{"role": "user", "content": "hello"}]
}'

Open WebUI en de OpenAI SDK's zijn getest tegen deze subset. Streaming, CORS en gebruikelijke sampling-opties werken. Ondersteunde functies die niet werken (tools, afbeeldingen, JSON-schema output, logprobs) geven een duidelijke 400-foutmelding. Alle details staan in docs/API.md.

Snelheid en Context

Decodering en Prompting

Decodering is relatief snel (~12 tok/s warm op een 48 GB Mac). De vertraging zit in de prompt: alle tokens van de prompt worden verwerkt voordat het eerste token van het antwoord verschijnt. 8.000 tokens zorgen voor een wachttijd van ongeveer een minuut op een 48 GB Mac en meer dan drie minuten op een 16 GB Mac. De totale context (prompt plus voltooiing) is begrensd op 32.768 tokens (--max-context).

Binnen een gesprek hoeft dit proces slechts één keer volledig te gebeuren. Vervolgvragen maken gebruik van prefix-caching, waardoor de tijd tot het eerste token constant blijft terwijl de chat groeit. Voor exacte reproduceerbaarheid kan dit worden uitgeschakeld met --no-prefix-cache.

Speculatieve Decodering (MTP)

Op machines met extra ruimte is er een versnelling mogelijk via een 'draft head' die het volgende token voorspelt. Met --mtp (standaard op auto sinds v0.2.0) worden tokens vooraf geschetst en in één batch geverifieerd.

  • De draft head is in 86% van de gevallen correct.
  • Dit is alleen effectief bij grotere caches (boven de ~26 GB target).
  • De head kost 1,6 GB extra bovenop de cache, waardoor het automatische plafond op 34,6 GB komt te liggen.
  • Er is een eenmalige conversie nodig die 4,9 GB downloadt en een mtp.safetensors bestand van 1,5 GB schrijft (zie Tools/mtp_convert.py).

Geheugenbeheer

Zonder vlaggen schaalt slotstream zichzelf automatisch. Een voorbeeld van een geheugenplan op een 48 GB Mac (die als 52 GB wordt gelezen door het gebruik van decimale GB):

slotstream memory plan (auto)
device: 52 GB RAM (36.0 GB reclaimable now), 40.2 GB Metal working set
target: 33.0 GB total for this process   (override: --memory-gb N | --max-ram-percent P)
cache:  ~152 of 512 experts per layer  (7280 global slots = 20.1 GB pool)
expect: ~32.0 GB peak, ~12 tok/s warm decode (est. from M5 Pro anchors)
prefill: 4096 tokens per pass (~125 tok/s here; costs ~5.3 GB of the target)
reuse:  up to 32768 tokens across 4 conversations (~1.2 GB), so a follow-up turn re-prefills only what is new

Logica van automatische schaling: Slotstream kiest de laagste van drie limieten: 33 GB, 70% van het RAM, of 2 GB onder de Metal working-set limiet. De limiet van 33 GB is gebaseerd op metingen; tussen 34 en 84 GB werd er geen snelheidswinst meer behaald in decodering of prefill.

Tijdens het draaien controleert slotstream elke 15 seconden het geheugen en past de cache aan: hij krimpt onder druk en groeit weer wanneer de druk afneemt. De output blijft byte-identiek, ongeacht de cachegrootte.

Handmatige configuratie:

  • --memory-gb G: stelt het totaal voor het proces in (minimaal 8,1 GB).
  • --max-ram-percent P: wijzigt het aandeel van 70%.
  • --experts-per-layer / --pool-gb: configureert de cache direct.

Technische Werking

Het grootste deel van het model bestaat uit:

  1. Routed experts: 68 GB (512 per laag, waarvan er 10 actief zijn per token).
  2. N-gram tabel: 32 GB.
  3. Dense trunk: 3,8 GB (blijft altijd in het geheugen resident).

De experts worden via pread gelezen in een vaste pool van cache-slots die gedeeld worden door alle 48 lagen. Hierdoor kunnen actieve lagen slots lenen van minder actieve lagen.

De cachegrootte beïnvloedt de snelheid, maar nooit de output. Greedy decoding is byte-identiek tussen een cache van 4 GB en 24 GB.

Waarom geen mmap? MLX (het ML-framework van Apple) kan geen deel van een memory-mapped tensor materialiseren. Een 'top-10 expert gather' evalueert alle 512 experts van die laag, waardoor een mmap-pad ongeveer 100 GB zou laden en crashen. De standaard mlx_lm.load() route leidde op een 48 GB machine tot 48 GB aan swap zonder dat er een token werd geproduceerd.

Status en Beperkingen

  • Getest op: M5 Pro met 48 GB. Kleinere tiers zijn schattingen.
  • Modelondersteuning: Alleen qwen3.8-flash-next:4bit. De engine is specifiek gebouwd rond deze geometrie.
  • Concurrency: Er kan slechts één modelproces tegelijk draaien via een per-user lock.
  • Compatibiliteit: macOS 14 en 15 zijn getest met de installer, maar de runtime is daar minder uitgebreid beproefd.
  • Ollama CLI: In versie 0.2.0 kan de Ollama CLI niet verbinden omdat de requests velden bevatten die de strikte validator van slotstream afwijst. Dit is opgelost in de main branch en zal in de volgende release verschijnen. curl, Open WebUI en de OpenAI SDK's werken momenteel wel.

Documentatie

  • docs/API.md: Endpoints, velden, sampling-standaarden en 400-fouten.
  • docs/TROUBLESHOOTING.md: Poortconflicten, paging, trage decodering en beheer van gewichten.
  • docs/CLI.md: Commando's, vlaggen, geheugeninstellingen en omgevingsvariabelen.
  • CHANGELOG.md: Wijzigingen per release.
  • PLAN.md: Ontwerp en milestone tracker.
  • MEASUREMENTS.md: Meetmethoden en resultaten van experimenten.
  • llms.txt / llms-full.txt: Kaarten van het project voor AI-agents.

Testen

  • Tools/verify.sh: De acceptatietest voor gewichten, vergelijking met Python-referentie, byte-gelijkheid bij verschillende cachematen en server-robuustheid.
  • Tools/e2e_release.sh: Test de installatie via curl | sh en het resulterende binaire bestand.

Licentie

Het project is gelicentieerd onder MIT.

  • Sources/SlotstreamCore/Vendored/GatedDelta.swift is geportte code uit mlx-swift-lm (MIT).
  • Tools/reference/ bevat de community qwen4_exp.py.
  • De gewichten zijn afkomstig van pipenetwork/Qwen3.8-Flash-Next-MLX-4bit en vallen onder de Qwen community-licentie.