Quantizzazione e modelli: quale GGUF scegliere

Dopo aver installato ds4 e scaricato il modello q2-imatrix, potresti chiederti: perché esistono tante varianti? E cosa significano q2, q4, imatrix? In questo capitolo analizziamo nel dettaglio le strategie di quantizzazione di ds4 e ti aiutiamo a scegliere il file GGUF più adatto al tuo hardware e ai tuoi scopi.

Perché la quantizzazione è fondamentale

I modelli come DeepSeek V4 hanno centinaia di miliardi di parametri. Anche solo caricarli in memoria a 16 bit (precisione nativa) richiederebbe oltre 1 TB di RAM. Per farli girare su computer personali (Mac con 96–128 GB, DGX Spark con 128 GB, ecc.) siamo costretti a comprimerli, cioè a quantizzarli a pochi bit per parametro.

La sfida è mantenere una qualità utile nonostante la forte compressione. ds4 adotta una strategia asimmetrica e sfrutta l’architettura MoE di DeepSeek V4 per concentrare la perdita di qualità nelle parti meno critiche.

Le quantizzazioni disponibili per Flash

Per DeepSeek V4 Flash (la versione “base”), ds4 offre quattro famiglie principali:

Nome del file	Quantizzazione	RAM richiesta	Qualità relativa	Uso consigliato
`q2-imatrix`	2 bit asimmetrici + imatrix	96–128 GB	Buona (quasi-frontier)	Default per Mac con 128 GB
`q2-q4-imatrix`	q2, ma ultimi 6 layer a q4	96–128 GB	Leggermente superiore a q2	Se hai un po’ di RAM extra
`q4-imatrix`	4 bit asimmetrici + imatrix	≥ 256 GB	Eccellente (quasi lossless)	Mac Studio / workstation con molta RAM
`q2` (senza imatrix)	2 bit, nessuna imatrix	96–128 GB	Inferiore a q2-imatrix	Solo per test (non raccomandato)

Nomenclatura:

q2 = quantizzazione a 2 bit (IQ2_XXS per up/gate, Q2_K per down)
q4 = quantizzazione a 4 bit (Q4_K)
imatrix = il file è stato calibrato con una importance matrix per migliorare la qualità
q2-q4 = ibrido: la maggior parte dei layer è a 2 bit, gli ultimi 6 layer (più vicini all’output) sono a 4 bit per preservare la qualità finale

Le quantizzazioni per PRO

DeepSeek V4 PRO è un modello molto più grande (circa 4 volte i parametri di Flash). Richiede hardware estremo, ma grazie alla quantizzazione 2 bit può essere eseguito su Mac Studio con 512 GB o in modalità distribuita su due Mac.

Nome del file	Quantizzazione	RAM necessaria	Note
`pro-q2-imatrix`	2 bit asimmetrici + imatrix	≥ 512 GB (su una macchina)	Per Mac Studio M3 Ultra 512 GB
`pro-q4-layers00-30` + `pro-q4-layers31-output`	4 bit, diviso in due file	distribuita su 2 macchine (ciascuna ≥ 256 GB)	Usare con inferenza distribuita

La strategia asimmetrica di ds4 (dettaglio tecnico)

A differenza di una quantizzazione uniforme (tutti i pesi allo stesso numero di bit), ds4 applica precisioni diverse a componenti diversi del modello, in base alla loro sensibilità.

Componente	Precisione nei quant q2	Precisione nei quant q4	Perché
Esperti routed (up/gate)	`IQ2_XXS` (2 bit)	`Q4_K` (4 bit)	Sono tantissimi, ma ognuno viene usato raramente → possono essere molto compressi
Esperti routed (down)	`Q2_K` (2 bit, migliore di IQ2_XXS)	`Q4_K`	Stessa logica
Shared expert	`Q8_0` (8 bit)	`Q8_0`	È usato a ogni token → serve alta precisione
Layer di routing	`F16` (16 bit)	`F16`	Il routing è delicato, si lascia in virgola mobile
Proiezioni (attenzione, MLP)	`Q8_0` o `F16` a seconda	`Q8_0`
Output head	`Q8_0`	`Q8_0`	Per la generazione finale

Questa strategia è possibile solo perché ds4 conosce esattamente l’architettura di DeepSeek V4 (non è un loader generico). Nei loader generici, dovresti quantizzare tutto allo stesso modo, con risultati peggiori a parità di bit.

Compatibilità MTP: Il GGUF aggiuntivo per lo speculative decoding (MTP) può essere usato con i quant q2-imatrix, q2-q4-imatrix e q4-imatrix. Si scarica con ./download_model.sh mtp e si abilita con --mtp. Al momento è sperimentale e lo speedup è minimo.

📘 Perché IQ2_XXS e Q2_K sono diversi?

IQ2_XXS è una quantizzazione a 2 bit molto aggressiva con una tabella di lookup non lineare, ottimizzata per tensori piccoli e rumore elevato. Q2_K è una quantizzazione a 2 bit “k-quant” con blocchi di scala, leggermente più precisa ma più costosa. ds4 usa IQ2_XXS per le matrici up/gate (grandi, molto sparse) e Q2_K per le matrici down (leggermente più critiche).

Imatrix: cos’è e perché migliora la qualità

Importance Matrix è una tabella che assegna un peso di importanza a ciascun parametro del modello, calcolato su un dataset di calibrazione (un insieme di prompt rappresentativi). Quando si quantizza il modello, i parametri con importanza maggiore vengono preservati con più bit (o con una tabella di quantizzazione migliore).

In ds4:

I file con suffisso -imatrix sono stati calibrati usando un dataset di prompt di coding, conversazioni generali e tool calling.
La procedura di generazione dell’imatrix è descritta in gguf-tools/imatrix/README.md.
L’imatrix è particolarmente efficace per quant a 2 bit, dove il margine di miglioramento è sostanziale.

Consiglio: usa sempre la versione -imatrix a meno che tu non voglia sperimentare.

Come scegliere il modello giusto: un flusso decisionale

Ecco un diagramma (testuale) per aiutarti a scegliere:

Hai un Mac con:
└─ 96-128 GB RAM?
  └─ Sì → usi Flash q2-imatrix (default) o q2-q4-imatrix se vuoi un pelo di qualità in più.
  └─ No, ho 64 GB → usa Flash q2-imatrix con SSD streaming (capitolo 5).

└─ ≥256 GB RAM (es. Mac Studio M3 Ultra)?
  └─ Usa Flash q4-imatrix per la massima qualità.

└─ ≥512 GB RAM (Mac Studio top)?
  └─ Vuoi il massimo assoluto? → PRO q2-imatrix (ci sta in RAM su una macchina).
  └─ Hai due Mac Studio 256 GB? → PRO q4 in distribuito (capitolo 8).

└─ Sei su DGX Spark con 128 GB?
  └─ Flash q2-imatrix (ottimizzato per CUDA). Il PRO è troppo grande.

Scaricare un modello diverso da quello predefinito

Lo script download_model.sh accetta diversi target. Ecco i più comuni:

# Modelli Flash
./download_model.sh q2-imatrix          # default per 128 GB
./download_model.sh q2-q4-imatrix       # ibrido
./download_model.sh q4-imatrix          # per 256+ GB
./download_model.sh q2                  # senza imatrix (non raccomandato)

# Modelli PRO
./download_model.sh pro-q2-imatrix      # per 512 GB su una macchina
./download_model.sh pro-q4-layers00-30  # prima metà del PRO Q4 distribuito
./download_model.sh pro-q4-layers31-output # seconda metà

Per i modelli distribuiti, dopo il download otterrai due file GGUF separati. Dovrai poi lanciare ds4 con i flag --role coordinator e --role worker come spiegato nel capitolo 8.

Se hai già scaricato un modello e vuoi cambiarlo, il link simbolico ./ds4flash.gguf verrà aggiornato automaticamente dall’ultimo download. Puoi anche puntarlo manualmente:

ln -sf gguf/DeepSeek-V4-Flash-IQ2_XXS-w2Q2K-...-imatrix.gguf ./ds4flash.gguf

Verificare la qualità del modello scaricato

ds4 include uno strumento di valutazione rapida: ds4-eval. Puoi usarlo per verificare che il tuo modello si comporti come previsto su un piccolo insieme di domande.

./ds4-eval -m ./ds4flash.gguf --plain --questions 4 --temp 0 --seed 1

L’output dovrebbe mostrare i primi 4 test con i token generati che corrispondono a una baseline nota (descritta nel README). Questo ti garantisce che il GGUF sia integro e che la quantizzazione non abbia introdotto regressioni.

Limitazioni e note importanti

Non puoi usare GGUF di DeepSeek V4 da altre fonti (es. convertiti da te con llama.cpp). ds4 si aspetta un layout dei tensori specifico e una miscela di quantizzazioni precisa. Usa solo i file forniti da antirez/deepseek-v4-gguf.
I modelli q4-imatrix per Flash pesano circa 160 GB e richiedono una macchina con almeno 256 GB di RAM. Non tentare di eseguirli con SSD streaming: la cache degli esperti routed sarebbe enorme e le prestazioni crollerebbero.
Il modello PRO q2-imatrix pesa circa 320 GB. Anche se la RAM dichiarata è 512 GB, il sistema operativo e la KV cache riducono lo spazio disponibile. Usalo solo su Mac Studio con 512 GB e contesti non enormi (es. 32k token).

Riferimenti utili

Hugging Face repo dei GGUF – per esplorare tutti i file
gguf-tools/README.md – per rigenerare i GGUF o creare una imatrix personalizzata
gguf-tools/quality-testing/README.md – per misurare la qualità dei quant rispetto all’API ufficiale

💡 La scelta migliore per iniziare
Se hai un Mac con 128 GB di RAM (M3 Max, M5 Max), il file q2-imatrix è il punto di partenza ideale. Offre un ottimo compromesso tra qualità e velocità, e ti permette di usare contesti fino a 100k token senza problemi. Passerai poi a q4-imatrix solo se fai upgrade a una macchina con 256+ GB.