Installazione e primo avvio

Ora che hai capito i concetti fondamentali, è tempo di mettere le mani sul codice. In questo capitolo imparerai a:

Scaricare i file GGUF corretti per DeepSeek V4 Flash/PRO
Compilare ds4 per il tuo hardware (Mac, Linux CUDA, ROCm)
Eseguire il primo comando e verificare che tutto funzioni

Prerequisiti hardware e software

Prima di iniziare, assicurati di avere:

Un computer supportato (vedi tabella sotto)
Almeno 64 GB di RAM (meglio 96/128 GB per eseguire il modello in RAM)
Almeno 100 GB di spazio libero su SSD (per i file GGUF)
Git, make, clang (o gcc) e curl installati
Su Linux con CUDA: driver NVIDIA e CUDA Toolkit (≥ 12.0)
Su ROCm: driver ROCm e runtime

Hardware	Backend consigliato	RAM minima	Comando `make`
Mac Apple Silicon (M3, M5, Ultra)	Metal	64 GB (96+ consigliati)	`make`
DGX Spark / GB10	CUDA (specializzato)	128 GB	`make cuda-spark`
Linux con GPU NVIDIA generica	CUDA (generico)	96+ GB	`make cuda-generic`
Strix Halo (Framework Desktop)	ROCm	96+ GB	`make rocm`
Qualsiasi (solo debug)	CPU	qualunque	`make cpu`

⚠️ Attenzione agli utenti macOS

Il backend CPU (make cpu) può causare il crash del kernel su macOS a causa di un bug di Apple non risolvibile da ds4. Usa esclusivamente il backend Metal per l’inferenza su Mac.

Passo 1: Clonare il repository

Apri il terminale e clona il progetto:

git clone https://github.com/antirez/ds4.git
cd ds4

Il repository contiene il codice sorgente (ds4.c, ds4_metal.m, ds4_cuda.cu), gli script di utility (download_model.sh), gli strumenti di benchmark e la documentazione.

Passo 2: Scaricare il modello GGUF

ds4 funziona solo con i file GGUF specifici per DeepSeek V4, disponibili su Hugging Face. Lo script download_model.sh automatizza il download.

Scelta del quant (modello)
Prima di scaricare, decidi quale versione usare in base alla tua RAM:

Modello	RAM necessaria	Quando usarlo
`q2-imatrix`	96–128 GB	MacBook/Desktop con 96/128 GB, bilancia qualità e memoria
`q2-q4-imatrix`	96–128 GB	Come sopra, ma gli ultimi 6 layer sono a 4 bit (qualità leggermente superiore)
`q4-imatrix`	≥ 256 GB	Mac Studio o workstation con molta RAM, qualità massima
`pro-q2-imatrix`	≥ 512 GB	Versione PRO (modello più grande) in 2 bit
`pro-q4-layers00-30 + pro-q4-layers31-output`	distribuito su 2 macchine	PRO in 4 bit su due Mac Studio
`mtp`	download aggiuntivo	Supporto sperimentale per speculative decoding (MTP)

Nota: Il target mtp scarica un GGUF aggiuntivo per il decoding speculativo (MTP). Non sostituisce il modello principale; va abilitato con --mtp. Al momento è sperimentale e fornisce solo un leggero speedup.

💡 Raccomandazione
Per la maggior parte degli utenti: se hai un Mac con 128 GB, usa q2-imatrix. È il compromesso migliore tra qualità e ingombro.

Download
Esegui il comando corrispondente:

# Per il modello q2-imatrix (consigliato per 128 GB)
./download_model.sh q2-imatrix

# Per altri modelli, sostituisci il target
./download_model.sh q4-imatrix

Lo script:

Scarica i file da https://huggingface.co/antirez/deepseek-v4-gguf
Li salva in ./gguf/
Crea/aggiorna il link simbolico ./ds4flash.gguf che punta al modello scelto

Se hai un token di Hugging Face (per download autenticati, non necessario per pubblico), puoi passarlo con --token TOKEN o impostare HF_TOKEN. Se nessuno dei due è presente, lo script cerca automaticamente il token nella cache locale di Hugging Face (~/.cache/huggingface/token).

Verifica che il file sia stato scaricato correttamente:

ls -lh gguf/
# Dovresti vedere un file .gguf di circa 80-90 GB

Passo 3: Compilare ds4

Il Makefile supporta diversi target. Scegli quello corrispondente al tuo hardware.

Su macOS (Metal, raccomandato)

make

Il binario prodotto si chiama ./ds4. La compilazione usa clang e il framework Metal. Richiede Xcode Command Line Tools installati.

Su Linux con DGX Spark / GB10 (CUDA ottimizzato)

make cuda-spark

Questo target compila per l’architettura specifica del DGX Spark, senza esplicitare -arch (percorso più veloce su quel sistema).

Su Linux con GPU NVIDIA generica (CUDA)

make cuda-generic

Se hai bisogno di specificare un’architettura CUDA diversa (es. per una RTX 4090), puoi usare:

make cuda CUDA_ARCH=sm_89    # per Ada Lovelace
make cuda CUDA_ARCH=native   # rileva automaticamente l'architettura locale

Su Strix Halo / ROCm

make rocm

Richiede il runtime ROCm e le librerie corrispondenti.

Solo CPU (debug, non per produzione)

make cpu

⚠️ Non usare il backend CPU su macOS
Come anticipato, la modalità CPU su macOS può causare il crash del kernel. Usala solo su Linux per test diagnostici.

Dopo la compilazione, verifica che il binario esista:

./ds4 --help

Dovresti vedere una lunga lista di opzioni.

Passo 4: Primo comando di test

Esegui un prompt semplice per verificare che l’inferenza funzioni.

Backend Metal (macOS)

./ds4 -p "Spiega perché il cielo è blu in una frase." --metal --nothink

Backend CUDA (Linux)

./ds4 -p "Spiega perché il cielo è blu in una frase." --cuda --nothink

Cosa aspettarti:

Il programma caricherà il modello GGUF (ci vorranno 10-20 secondi la prima volta).
Poi eseguirà il prefill del prompt e genererà una risposta breve.
In output vedrai solo la risposta (grazie a --nothink).
Se tutto funziona, vedrai una frase come: “Il cielo è blu a causa della diffusione di Rayleigh, che disperde la luce solare più corta (blu) più efficacemente delle lunghezze d’onda più lunghe.”

💡 Primo avvio lento?
La prima esecuzione di un modello GGUF richiede tempo per il mapping in memoria e la creazione delle strutture interne. Le esecuzioni successive saranno più veloci. Inoltre, il backend Metal compila gli shader al primo utilizzo (cache nelle cartelle ~/Library/Caches/com.apple.Metal).

Passo 5: Modalità interattiva (CLI)

Se vuoi chattare con il modello, lancia il CLI senza -p:

./ds4

Apparirà il prompt ds4>. Puoi scrivere messaggi, e il modello risponderà. Comandi utili:

/help – mostra tutti i comandi
/think – attiva la modalità di ragionamento (default)
/nothink – disattiva il ragionamento
/ctx N – imposta la lunghezza massima del contesto
/read file.txt – legge un file e lo usa come prompt
/quit – esce

Esempio di conversazione:

ds4> Cosa è Redis?
Redis è un database in-memory open source, usato come cache, message broker e database NoSQL...
ds4> /nothink
ds4> Spiega in 10 parole.
Database veloce, strutture dati, persistenza opzionale.

Risoluzione dei problemi comuni

Problema	Possibile causa	Soluzione
`./ds4: command not found`	Non sei nella directory giusta o compilazione fallita	Esegui `make` e verifica che il file `ds4` esista
`Metal: failed to compile shader`	Xcode Command Line Tools non installato o versione vecchia	Installa/aggiorna con `xcode-select --install`
`CUDA: driver version insufficient`	Driver NVIDIA non aggiornato	Aggiorna i driver e CUDA Toolkit
`GGUF file not found`	`./ds4flash.gguf` non punta a un file valido	Esegui `./download_model.sh q2-imatrix` (o il modello che hai scelto)
`Out of memory`	RAM insufficiente per il modello + contesto	Usa `--ssd-streaming` (vedi capitolo 5) o riduci `--ctx`
Kernel panic su macOS	Hai usato `--cpu`	Non usare la CPU su macOS. Riavvia e usa `--metal`.

Prossimi passi

Ora che hai ds4 funzionante, puoi esplorare le funzionalità più avanzate:

Capitolo 4: Capire meglio i diversi quant e come scegliere il modello giusto.
Capitolo 5: Usare SSD streaming per far girare il modello su macchine con meno RAM.
Capitolo 7: Lanciare l’agente nativo (ds4-agent) per una chat persistente.
Capitolo 9: Avviare il server API per collegare Codex CLI o Claude Code.

Se qualcosa non ha funzionato, controlla la sezione di debug nel README ufficiale o apri una issue su GitHub.

📘 Perché il modello deve essere scaricato con lo script e non da Hugging Face direttamente?

I GGUF pubblici su Hugging Face hanno nomi e layout dei tensori specifici per ds4. Scaricando con lo script, ti assicuri di ottenere la versione esatta che il motore si aspetta. Inoltre, lo script imposta il link simbolico ./ds4flash.gguf che molti comandi usano come percorso di default.