Concetti fondamentali (glossario tecnico)

Prima di addentrarci nell’uso pratico, è utile familiarizzare con alcuni concetti chiave che compaiono ovunque nella documentazione di ds4. Non preoccuparti: ogni termine viene spiegato da zero, con esempi e collegamenti al funzionamento reale del motore.

1. Modelli MoE (Mixture of Experts)

Cosa sono
Un modello MoE non è un singolo blocco di neuroni, ma un insieme di molti “esperti” (sottomodelli) e un meccanismo di routing che decide, per ogni token, quali esperti attivare.

• Esperti routed (la maggioranza) – vengono attivati solo quando il router li seleziona. DeepSeek V4 ne ha centinaia, ma solo 2-4 sono attivi per token.
• Esperti condivisi – sempre attivi, indipendentemente dal routing.

Perché è utile
A parità di numero di parametri totali, un modello MoE è molto più efficiente in fase di inferenza: si calcola solo una frazione dei pesi. Questo permette di avere modelli da centinaia di miliardi di parametri che girano su hardware personale.

In ds4
La separazione tra esperti routed e condivisi è fondamentale per la quantizzazione asimmetrica e per lo SSD streaming: gli esperti routed (molto numerosi) possono essere quantizzati a 2 bit e tenuti su SSD, mentre gli esperti condivisi (pochi) restano in RAM a qualità più alta.

📘 Esempio concreto

Immagina un’azienda con 100 specialisti (esperti routed) e 5 manager (esperti condivisi). Per ogni problema, il router (un assistente) sceglie 2 specialisti più adatti. Gli specialisti cambiano a seconda del problema, ma i manager ci sono sempre. Questo sistema è molto più veloce che coinvolgere tutti i 105 dipendenti ogni volta.

2. GGUF (il formato dei pesi)

Cosa è
GGUF è un formato di file sviluppato da Georgi Gerganov per llama.cpp. Contiene:

• I pesi del modello (quantizzati)
• I metadati (configurazione, tokenizer, template di prompt)
• Opzionalmente, una “importance matrix” (imatrix)

Perché ds4 lo usa
ds4 non è un loader GGUF generico: accetta solo i file GGUF specifici per DeepSeek V4 prodotti da questo progetto. I tensori hanno un layout preciso e una miscela di quantizzazioni che il motore si aspetta.

Dove trovarli
I file sono su Hugging Face: antirez/deepseek-v4-gguf. Lo script download_model.sh li scarica nella cartella ./gguf/.

3. Quantizzazione asimmetrica

Il problema
I modelli hanno centinaia di miliardi di parametri. Per farli stare in RAM, li comprimiamo (quantizziamo) a pochi bit per parametro. Ma comprimere troppo fa perdere qualità.

La soluzione di ds4
Non tutti i parametri sono uguali. Alcuni componenti sono più sensibili alla quantizzazione. ds4 applica una strategia asimmetrica:

Componente	Precisione	Note
Esperti routed (up/gate)	IQ2_XXS (2 bit)	Sono moltissimi, ma poco attivati → la perdita di qualità è limitata
Esperti routed (down)	Q2_K (2 bit, migliorato)
Proiezioni (shared expert)	Q8_0 (8 bit)
Layer di routing	F16 (16 bit)
Output head	Q8_0 (8 bit)

Risultato
Il modello pesa circa 81 GB in 2 bit (per Flash), ma la qualità è sorprendentemente buona, al punto da essere utile per coding e tool calling.

💡 Perché funziona?

Gli esperti routed sono tanti ma ognuno viene usato raramente. Un errore di quantizzazione su un esperto che viene attivato una volta ogni 100 token ha un impatto minore rispetto a un errore su un layer condiviso usato per ogni token.

4. Imatrix (importance matrix)

Cosa è
L’imatrix è una tabella che assegna un “peso di importanza” a ogni parametro del modello, calcolato su un dataset di calibrazione (un insieme di prompt rappresentativi). Quando si quantizza il modello, i parametri più importanti vengono preservati con maggiore precisione.

In ds4
I file .gguf con suffisso -imatrix sono quelli calibrati. La procedura per generare l’imatrix è descritta in gguf-tools/imatrix/. Puoi anche crearne una tua su un dataset specifico, se vuoi ottimizzare per un dominio particolare.

Perché usare la versione imatrix
Per la quantizzazione a 2 bit, l’imatrix migliora notevolmente la qualità, specialmente nei contesti lunghi. La raccomandazione ufficiale è: preferisci i file con imatrix.

5. KV cache compressa (4:1)

Cos’è la KV cache
Durante la generazione, il modello calcola per ogni token una coppia di vettori (Key e Value) per ogni layer. Questi vettori vengono riutilizzati per i token successivi. Senza cache, il costo crescerebbe quadraticamente con la lunghezza del contesto.

Il problema
La KV cache occupa molta memoria. Per un modello grande e un contesto di 1 milione di token, la cache può richiedere decine di GB.

La soluzione di DeepSeek V4
DeepSeek V4 adotta una compressione 4:1 della KV cache, riducendo la memoria necessaria a circa un quarto. Questo è reso possibile da un meccanismo di “compressor” e “indexer” che aggrega più posizioni in un unico vettore compresso.

In ds4
Il motore gestisce nativamente questa compressione. I file di snapshot (.kv) contengono sia i tensori raw che quelli compressi. Durante l’inferenza, ds4 mantiene sia la cache compressa (per la maggior parte delle posizioni) che una piccola cache raw per la finestra scorrevole più recente.

📘 Impatto pratico

Senza compressione, un contesto da 1 milione di token su DeepSeek V4 richiederebbe circa 80 GB di sola KV cache. Con la compressione 4:1, si scende a circa 22 GB. Questo rende possibile contesti enormi anche su hardware con 128 GB di RAM.

6. SSD streaming

Il concetto
Quando il modello non entra completamente in RAM, ds4 può tenere su SSD la maggior parte degli esperti routed (che sono la parte più grossa) e caricarli nella cache al bisogno.

Come funziona

• I pesi non routed (shared expert, proiezioni, routing) restano fissi in RAM.
• Gli esperti routed sono letti dal file GGUF su SSD quando servono.
• Una cache LRU (Least Recently Used) in RAM tiene gli esperti più usati.
• Se l’esperto richiesto non è in cache, si genera un cache miss: ds4 lo legge dall’SSD (operazione da decine di microsecondi) e lo inserisce in cache.

Parametri

• --ssd-streaming attiva la modalità.
• --ssd-streaming-cache-experts 32GB imposta la dimensione della cache in RAM (qui 32 GB).

Performance

• Il prefill rimane veloce perché gli esperti vengono letti in streaming sequenziale.
• La generazione è più lenta (ogni token può causare cache miss), ma su SSD moderni è comunque utilizzabile.

⚠️ Attenzione

Lo streaming SSD richiede un SSD NVMe o Apple con latenze molto basse. Su SSD SATA tradizionali, la generazione può diventare troppo lenta.

7. MTP (Multi-Token Prediction) / Speculative decoding

Cosa è
Una tecnica per accelerare la generazione: un modello più piccolo (draft) propone N token futuri, poi il modello principale (target) li verifica in parallelo. Se sono corretti, si accettano tutti in una volta.

In ds4
È opzionale e attualmente sperimentale. Puoi scaricare un GGUF aggiuntivo per l’MTP con ./download_model.sh mtp, poi abilitarlo con --mtp MTP.gguf --mtp-draft 2.

Stato attuale
Il guadagno di velocità è minimo (o nullo) rispetto alla normale generazione. È più una prova di concetto che una feature pronta per l’uso.

8. Thinking mode e sampling

Thinking mode
DeepSeek V4 ha una modalità in cui prima genera un ragionamento interno (tra tag <think> e </think>) e poi la risposta finale. Questo migliora la qualità su problemi complessi, ma consuma più token.

• Modalità normale (non-thinking): risposta diretta.
• Thinking: ragionamento + risposta.
• Think Max (reasoning_effort=max): ragionamento più approfondito, richiede contesto più grande.

Parametri di sampling predefiniti (nel server API):

• temperature = 1
• top_p = 1
• min_p = 0.05

Il min_p è un filtro meno comune: considera solo i token la cui probabilità è almeno min_p * (probabilità del token più probabile). È un’alternativa a top_p che funziona bene con temperature basse.

In ds4

• Nel CLI, puoi usare /think, /nothink, /think-max.
• Nel server, la modalità thinking è attiva di default. Per disabilitarla, passa thinking: {"type":"disabled"} o usa un alias deepseek-chat.

9. Tool calling e DSML

Cos’è DSML
DeepSeek V4 utilizza un formato proprietario per le chiamate a function/tool, chiamato DSML (DeepSeek Markup Language). A differenza di altri modelli che usano JSON strutturato in un campo speciale, DeepSeek genera direttamente dei tag DSML nel flusso di testo.

Esempio di tool call generata dal modello (rappresentato come stringa)

<tool_calls>
<get_weather>
{"city": "Roma", "unit": "celsius"}

Il problema del tool calling “esatto”
Quando il server riceve la risposta del modello con la tool call, deve poi ricevere dal client il risultato dell’esecuzione del tool. Il client (es. un agente) rispedisce indietro una struttura JSON normalizzata (es. OpenAI format), non il DSML originale.

Se il server, nel turno successivo, riformattasse il risultato in DSML in modo leggermente diverso (spazi, ordine dei campi, maiuscole), i byte del prompt non corrisponderebbero più a quelli della cache KV. Si perderebbe l’efficienza e si dovrebbe rieseguire il prefill.

La soluzione di ds4: exact replay
Il server memorizza in una mappa (in RAM e nei file KV su disco) l’esatta sequenza DSML che il modello ha generato per quella tool call, associata a un ID univoco.

Quando il client risponde con lo stesso ID, il server reinserisce i byte originali senza riformattare nulla. La cache KV rimane valida.

Backup: canonicalizzazione
Se l’exact replay non è disponibile (es. server riavviato senza cache), ds4 genera una forma canonica (deterministica) del DSML. In questo caso può esserci una ricomputazione parziale, ma la conversazione continua.

📘 Perché è importante
Senza exact replay, ogni tool call causerebbe una rottura della cache KV, rendendo il server molto più lento (dovrebbe rifare il prefill da capo). Con exact replay, le conversazioni con tool rimangono veloci anche dopo molti turni.

10. Context caching (cache KV su disco)

Cos’è
Una funzionalità del server ds4-server che salva su disco lo stato della KV cache per conversazioni già elaborate, usando come chiave lo SHA1 del testo renderizzato del prompt.

Quando serve
Gli agenti (Codex CLI, Claude Code, ecc.) rispediscono ogni volta l’intera cronologia della conversazione. Senza cache, ogni richiesta dovrebbe rifare il prefill da zero, con tempi lunghi.

Come funziona in ds4

1. Il server riceve una richiesta con un prompt (es. una lunga conversazione).
2. Calcola lo SHA1 del prompt renderizzato (tokenizzato e decodificato in testo).
3. Cerca un file .kv con quel nome nella directory --kv-disk-dir.
4. Se esiste, carica lo stato della KV cache da quel file: la conversazione è già pronta, serve solo fare il prefill dei nuovi token (quelli aggiunti dopo l’ultimo salvataggio).
5. Se non esiste, esegue il prefill completo e salva dei checkpoint (“cold save” dopo il primo prefill, “continued save” ogni N token).

Formato del file .kv (header semplificato)

1. Magic KVC + versione
2. Lunghezza e contenuto del testo renderizzato (in UTF-8)
3. Payload DS4: token IDs, logits dell’ultimo token, tensori KV raw e compressi per ogni layer
4. (Opzionale) Mappa tool ID → DSML esatto

Parametri utili

Parametro	Effetto
--kv-disk-dir /percorso	Abilita la cache su disco
--kv-disk-space-mb 8192	Limite massimo di spazio usabile (default 8192 MB)
--kv-cache-min-tokens 512	Salva solo conversazioni più lunghe di N token
--kv-cache-cold-max-tokens 30000	Taglia i checkpoint cold oltre questa lunghezza
--kv-cache-boundary-trim-tokens 32	Toglie N token dalla fine prima di salvare (evita problemi di confine BPE)

💡 Caso d’uso tipico
Lanci ./ds4-server —kv-disk-dir /tmp/ds4-kv. Il primo messaggio lungo impiega qualche secondo per il prefill, ma tutte le richieste successive che condividono lo stesso prefisso saranno istantanee.

11. Glossario riepilogativo (utile come riferimento rapido)

Termine	Significato sintetico
MoE	Architettura con esperti routed e condivisi. Solo pochi esperti attivati per token.
GGUF	Formato di file dei pesi quantizzati. ds4 usa file specifici, non generici.
Quantizzazione asimmetrica	Diversi componenti del modello usano precisioni diverse (2, 8, 16 bit).
Imatrix	Matrice di importanza per migliorare la quantizzazione (calibrata su dataset).
KV cache compressa	Riduzione 4:1 della memoria necessaria per la cache, grazie a compressor/indexer.
SSD streaming	Esperti routed tenuti su SSD e caricati in cache LRU a richiesta.
MTP / speculative decoding	Tecnica sperimentale per accelerare la generazione (draft + verify).
Thinking mode	Il modello genera un ragionamento interno prima della risposta.
min_p	Filtro di campionamento basato sulla probabilità relativa al token migliore.
DSML	Formato proprietario per tool calling (tag <tool_calls> … </tool_calls>).
Exact replay	Il server riutilizza i byte esatti della tool call generata, per non invalidare la cache.
Context caching	Salvataggio su disco della KV cache, chiavato con SHA1 del prompt renderizzato.

Ora che hai familiarità con i concetti fondamentali, sei pronto per mettere le mani sul codice.

👉 Capitolo 3: Installazione e primo avvio – Scaricare il modello, compilare ds4, eseguire i primi comandi.