SSD Streaming: eseguire modelli più grandi della RAM

Nei capitoli precedenti abbiamo visto che DeepSeek V4 Flash in quantizzazione 2 bit occupa circa 81 GB. Su molti Mac (es. M3 Max con 64 GB) o su DGX Spark (128 GB ma con overhead di sistema), il modello potrebbe non entrare completamente in RAM. La soluzione è lo SSD streaming: una tecnica che sfrutta la velocità degli SSD moderni per tenere su disco la maggior parte dei pesi, caricando in RAM solo quelli necessari al momento.

Il problema: modello troppo grande per la RAM

Anche se hai 128 GB di RAM, il sistema operativo, la KV cache, i buffer di calcolo e altri processi riducono lo spazio disponibile per il modello. Potresti trovarti con soli 100-110 GB liberi, insufficienti per gli 81 GB del modello + overhead. Inoltre, se vuoi usare un contesto molto lungo (es. 200k token), la KV cache richiederà altri GB.

Lo SSD streaming risolve questo problema spostando la maggior parte dei pesi (gli esperti routed) su SSD, mantenendo in RAM solo i componenti critici e una cache degli esperti più usati.

Come funziona tecnicamente

ds4 divide i pesi del modello in tre categorie:

Pesi non routed (shared expert, proiezioni, layer di routing, output head) – sempre in RAM. Sono pochi (circa il 10-15% del totale) ma essenziali per ogni token.
Esperti routed – la stragrande maggioranza dei parametri (oltre l’80% del modello). Vengono letti dal file GGUF su SSD quando servono.
Cache degli esperti routed – una porzione di RAM (configurabile) dove vengono tenuti gli esperti più recentemente utilizzati (coda LRU). Se un esperto è in cache, non c’è bisogno di leggerlo dall’SSD.

Flusso di un token:

Il router decide quali esperti routed attivare (di solito 2-4 per token).
Per ogni esperto richiesto, ds4 controlla se è nella cache RAM.
Se sì (cache hit), lo usa immediatamente.
Se no (cache miss), lo legge dal file GGUF su SSD, lo inserisce in cache (eventualmente espellendo l’esperto meno recente), poi lo usa.

La latenza di lettura di un SSD NVMe moderno è di circa 10-50 microsecondi per un accesso casuale, più il trasferimento dei dati (un esperto può essere da pochi MB a decine di MB). Il calcolo del token richiede comunque decine di millisecondi, quindi il cache miss può essere tollerato.

📘 Perché funziona sull’architettura MoE

In un modello denso (non MoE), ogni token attiverebbe tutti i parametri, causando un cache miss continuo. In un MoE, invece, solo pochi esperti sono attivi per token, e la distribuzione degli esperti segue una legge di potenza: pochi esperti sono molto frequenti, la maggior parte sono rari. La cache LRU trattiene gli esperti caldi, riducendo drasticamente i miss.

Parametri per abilitare e configurare lo streaming

Parametro	Descrizione	Esempio
`--ssd-streaming`	Attiva la modalità streaming (altrimenti il modello viene caricato interamente in RAM)	`--ssd-streaming`
`--ssd-streaming-cache-experts N`	Dimensione della cache per esperti routed (es. `32GB`, `64GB`). Se non specificato, ds4 calcola automaticamente l’80% della memoria raccomandata da Metal meno i pesi non routed.	`--ssd-streaming-cache-experts 32GB`
`--ssd-streaming-cold`	Disabilita il pre-caricamento degli esperti “caldi” all’avvio (solo per test)	`--ssd-streaming-cold`
`--ssd-streaming-preload-experts N`	Numero di esperti da pre-caricare in cache all’avvio (default: tutti quelli che stanno nella cache)	`--ssd-streaming-preload-experts 100`

Modalità automatica vs manuale:

Automatica (solo --ssd-streaming): ds4 interroga Metal per conoscere la memoria consigliata (ad esempio 110 GB su una Mac con 128 GB), sottrae i pesi non routed (~15 GB) e usa il resto per la cache esperti. Su un Mac con 128 GB, automatico potrebbe riservare ~80 GB per la cache.
Manuale (con --ssd-streaming-cache-experts): imponi esattamente quanta RAM dedicare agli esperti routed. Utile se vuoi limitare l’uso della memoria per lasciare spazio alla KV cache o ad altri processi.

⚠️ Attenzione al lock della memoria

ds4 cerca di bloccare in RAM (con mlock) la cache degli esperti per evitare che il sistema operativo la scambi su disco. Se la cache richiesta è troppo grande, il lock può fallire e ds4 ridurrà automaticamente la cache a una dimensione bloccabile. Dai sempre un’occhiata ai log di avvio per vedere la cache effettiva.

Esempi pratici

Caso 1: MacBook con 64 GB di RAM (es. M3 Max 64 GB)

Obiettivo: far girare Flash q2-imatrix (81 GB) con contesto moderato (32k token).

./download_model.sh q2-imatrix
./ds4 -m ./ds4flash.gguf \
      --ssd-streaming \
      --ssd-streaming-cache-experts 32GB \
      --ctx 32768 \
      --nothink

Spiegazione:

--ssd-streaming: abilita la modalità.
--ssd-streaming-cache-experts 32GB: riserva 32 GB di RAM per gli esperti routed. I pesi non routed (circa 15 GB) e la KV cache (per 32k token, circa 5-10 GB) si sommano, totale intorno a 55-60 GB, entro i 64 GB.
Il resto degli esperti (81 - 15 - 32 = 34 GB) viene letto dall’SSD al bisogno.

Prestazioni attese:

Prefill (prima risposta): veloce, perché il modello legge in streaming sequenziale.
Generazione: lenta, con latenza per token aumentata dai cache miss. Su un Mac M3 con SSD veloce, potresti vedere 5-10 token/s invece dei 25+ token/s con modello in RAM.

Caso 2: MacBook con 128 GB (ma vuoi lasciare molta RAM alla KV cache)

Magari vuoi un contesto di 200k token (che richiede ~20 GB di KV cache compressa). Puoi ridurre la cache esperti per fare spazio.

./ds4 -m ./ds4flash.gguf \
      --ssd-streaming \
      --ssd-streaming-cache-experts 48GB \
      --ctx 200000

Qui 48 GB per esperti + 15 GB non routed + 20 GB KV cache = 83 GB, abbondantemente nei 128 GB. La generazione sarà più veloce rispetto al caso 64 GB perché la cache esperti è più grande e ci saranno meno miss.

Caso 3: PRO q2 su Mac Studio 512 GB (ma vuoi comunque streaming per risparmiare RAM)

Anche se il modello PRO q2 (320 GB) entra in 512 GB, potresti preferire lo streaming per lasciare più RAM alla KV cache o ad altri carichi di lavoro.

./download_model.sh pro-q2-imatrix
./ds4 -m gguf/DeepSeek-V4-Pro-IQ2XXS-...-imatrix.gguf \
      --ssd-streaming \
      --ctx 32768 \
      --think

In questo caso, usa la cache automatica. Su un Mac Studio M3 Ultra, il budget automatico potrebbe riservare ~200 GB per esperti routed, lasciando il resto per pesi non routed, KV cache e sistema.

Prestazioni: cosa aspettarsi

Le prestazioni variano molto in base a:

Velocità dell’SSD (NVMe PCIe 4.0/5.0 vs SATA)
Dimensione della cache esperti (più è grande, meno miss)
Lunghezza del contesto (la KV cache consuma RAM, riducendo lo spazio per gli esperti)
Pattern di routing (alcuni prompt attivano esperti più dispersi, causando più miss)

Dati riportati da antirez (Mac M5 Max 128 GB, Flash q2, SSD interno):

Configurazione	Prefill (t/s)	Generazione (t/s)
Modello in RAM (nessuno streaming)	463	25.9
Streaming, cache automatica (~80 GB)	~450	~22
Streaming, cache 32 GB	~430	~15
Streaming, cache 16 GB	~400	~8

Come vedi, la generazione degrada significativamente con cache piccola, ma il prefill rimane veloce perché la lettura è sequenziale.

Limitazioni e avvertenze

Non tutti gli SSD sono uguali – Gli SSD SATA o i vecchi NVMe con latenze elevate (es. >100 µs) renderanno la generazione inutilizzabile. Richiedi un SSD NVMe moderno (MacBook 2021+, PC con NVMe PCIe 3.0/4.0).
La cache esperti è in RAM, non su SSD – Non confondere: i pesi degli esperti vengono letti dall’SSD, ma la cache che li tiene è in RAM. Se la cache è troppo piccola, continui a leggere dall’SSD.
Non adatto per contesti enormi con streaming – Con streaming attivo, la RAM disponibile per la KV cache si riduce. Se hai bisogno di contesti da 500k token, forse è meglio avere abbastanza RAM per tutto il modello.
Supportato su tutti i backend – Lo streaming SSD è disponibile per Metal (macOS), CUDA (NVIDIA/DGX Spark) e ROCm (Strix Halo). Le prestazioni e le caratteristiche specifiche possono variare leggermente tra backend. Su macOS resta il percorso più maturo e testato.
Non usare con modelli q4 – I modelli q4 hanno esperti routed più grandi (4 bit invece di 2), quindi la quantità di dati da trasferire dall’SSD è doppia. Le prestazioni crollerebbero.

Diagnosticare lo streaming

All’avvio, ds4 stampa un report sulla cache:

SSD streaming: enabled, expert cache 32.0 GB (254 experts)
Non-routed weights: 14.2 GB, KV cache size: 1.2 GB
Lockable memory: 58.3 GB, using 32.0 GB for expert cache

Durante l’inferenza, puoi attivare il debug per vedere i miss:

./ds4 --debug --ssd-streaming ...

Vedrai messaggi come:

[expert cache] miss expert 124, loading from SSD (4.2 MB, 0.34 ms)
[expert cache] hit expert 87

Conclusione

Lo SSD streaming è una funzionalità innovativa che trasforma il limite della RAM da un “o funziona o non funziona” a uno spettro di velocità. Se hai una macchina con 64 GB, puoi comunque eseguire Flash q2, accettando una generazione più lenta. Se hai 128 GB, puoi decidere quanto velocezza sacrificare per lasciare più RAM alla KV cache.

Regola pratica:

Vuoi massima velocità → modello in RAM (no streaming). Richiede RAM sufficiente.
La RAM è un po’ scarsa → streaming con cache grande (es. 70-80% della RAM disponibile).
RAM molto scarsa (es. 64 GB) → streaming con cache piccola (es. 32 GB), accettando generazione lenta.

💡 Prova prima con la cache automatica
La prima esecuzione con —ssd-streaming (senza specificare la cache) ti darà un’idea delle prestazioni. Poi modifica la dimensione della cache per bilanciare velocità e utilizzo di RAM. Tieni d’occhio i log per vedere se ci sono troppi miss.