Debug e test: strumenti per diagnosticare problemi e verificare la correttezza

Anche se ds4 è in beta, disporre di buoni strumenti di debug è fondamentale per capire cosa succede quando le cose non funzionano come previsto. In questo capitolo esploriamo i comandi di diagnostica e i test di regressione integrati.

Strumenti di diagnostica rapidi

1. `--dump-tokens`: visualizzare la tokenizzazione

Prima ancora di eseguire l’inferenza, puoi vedere come ds4 tokenizza un prompt. Utile per capire se il template di sistema o i tool vengono interpretati correttamente.

./ds4 --dump-tokens -p "Ciao, come stai?"

Output di esempio:

Tokenization of prompt (12 tokens):
[1]    1: <│begin▎sentence▎>
[2]   12: Ciao
[3]   34: ,
[4]  567: come
[5]  890: stai
[6]   23: ?
[7]    2: <│end▎sentence▎>

Utile anche per debug di tool call:

./ds4 --dump-tokens -p "<tool_calls>\n<get_weather>\n{}\n</get_weather>"

Vedrai come i caratteri speciali DSML vengono suddivisi in token.

2. `--dump-logprobs`: esportare le probabilità dei token

Genera una risposta (modalità greedy) e salva per ogni posizione i top-k token alternativi con le loro probabilità logaritmiche.

./ds4 --dump-logprobs /tmp/logprobs.json --logprobs-top-k 5 --temp 0 -p "Il cielo è"

Il file JSON contiene:

{
  "prompt": "Il cielo è",
  "generated_tokens": [
    {
      "token": " blu",
      "token_id": 1234,
      "logprob": -0.123,
      "top_alternatives": [
        { "token": " sereno", "token_id": 5678, "logprob": -1.234 },
        { "token": " nuvoloso", "token_id": 9012, "logprob": -2.345 }
      ]
    }
  ]
}

Questo aiuta a separare problemi di modello (logits errati) da problemi di sampling (scelta sbagliata del token).

3. `--dump-logits`: esportare i logits grezzi

Salva i logits (i punteggi prima della softmax) per ogni posizione. Utile per confrontare con l’API ufficiale.

./ds4 --dump-logits /tmp/logits.json --metal --nothink --prompt-file prompt.txt

Il file contiene un array di vettori di lunghezza vocab_size (circa 128k float32). Puoi confrontarlo con i logits ottenuti dall’API DeepSeek usando lo stesso prompt (con --dump-logprobs sull’API).

4. `--trace` nel server

Quando usi ds4-server, il flag --trace registra ogni operazione rilevante:

./ds4-server --trace /tmp/server-trace.txt --kv-disk-dir /tmp/ds4-kv

Il trace include:

Richieste ricevute (method, path, body troncato)
Decisioni della cache KV (hit/miss, SHA1, token count)
Testo renderizzato del prompt
Token generati (in streaming)
Eventi di tool call (DSML parsato, ID mappati)
Errori e warning

Esempio di trace:

[2026-06-10 14:32:15] REQUEST: POST /v1/chat/completions
[2026-06-10 14:32:15] KV cache: miss for sha1=abc123... (reason: not found)
[2026-06-10 14:32:15] Prefill 512 tokens, took 1.234s
[2026-06-10 14:32:16] Generated token 1: "Ciao" (id 12)
[2026-06-10 14:32:16] KV cache: cold save (512 tokens) -> /tmp/ds4-kv/abc123.kv

Test di regressione: `make test` e `ds4_test`

ds4 include una suite di test per verificare che modifiche al codice non rompano la correttezza dell’inferenza.

Esecuzione dei test

make test

Questo comando esegue:

ds4-eval --self-test-extractors (verifica gli estrattori di risposta)
./ds4_test --all (suite principale)

I test includono:

Test vettori logprob: Confronta i logits generati localmente con quelli ottenuti dall’API ufficiale di DeepSeek (greedy, thinking disabilitato). I vettori sono in tests/test-vectors/.
Test server: Verifica che gli endpoint API rispondano correttamente (status code, formato, streaming).
Test di correttezza KV cache: Controlla che salvataggio e ripristino della cache producano gli stessi token.

Test specifici

Puoi eseguire singoli test:

# Solo test dei vettori logprob
./ds4_test --logprob-vectors

# Solo test del server
./ds4_test --server

# Tutti i test
./ds4_test --all

Cosa significa un test fallito

Se make test fallisce, significa che l’ultima modifica ha alterato i logits prodotti da ds4 rispetto alla baseline ufficiale. Questo potrebbe essere:

Un miglioramento (se hai corretto un bug di implementazione)
Una regressione (se hai introdotto un errore)
Un cambiamento atteso (se hai modificato il modello o la quantizzazione, ma allora i vettori vanno rigenerati)

Per rigenerare i vettori di test (solo se sei sicuro che il cambiamento sia voluto), consulta tests/test-vectors/README.md.

Test vectors: confronto con l’API ufficiale

I file in tests/test-vectors/ contengono continuationi di prompt catturate dall’API ufficiale di DeepSeek V4 Flash (greedy, thinking disabilitato). Ogni vettore include:

Il prompt tokenizzato
I token generati (greedy)
I logprobs dei token generati e dei top alternativi

Il test verifica che ds4 produca esattamente gli stessi token (byte per byte) e logprobs entro una tolleranza (dovuta a floating point).

Come funziona il confronto

./ds4_test --logprob-vectors

Per ogni vettore:

Carica il prompt.
Esegue l’inferenza con --temp 0 --nothink.
Confronta i token generati con quelli attesi.
Se corrispondono, confronta i logprobs (differenza media < 1e-4).
Riporta successo/fallimento.

Perché i test vectors sono importanti

Garantiscono che ds4 sia allineato con il modello originale e che modifiche future non introducano regressioni nascoste. Senza questi test, sarebbe facile rompere la qualità del modello senza accorgersene.

Debug di problemi comuni

1. Il modello non risponde o risponde con ripetizioni

Possibili cause:

Temperatura troppo alta (prova --temp 0 o --temp 0.5)
top_p o min_p troppo restrittivi (prova --top_p 0.9 --min_p 0.05)
KV cache corrotta (cancella i file .kv e riprova)

Diagnostica:

./ds4 --dump-logprobs /tmp/debug.json --temp 0 -p "Il tuo prompt"
cat /tmp/debug.json | jq '.generated_tokens[].token'

Vedi se i token generati hanno senso.

2. La generazione è molto lenta

Possibili cause:

SSD streaming con cache piccola (usa --ssd-streaming-cache-experts più grande)
Contesto troppo lungo (riduci --ctx)
Backend CPU (usa --metal o --cuda)

Diagnostica: guarda i log all’avvio. Se vedi molti miss nella cache esperti, aumenta la cache.

3. Errore “Out of memory” o “Kernel panic” su macOS

Cause:

Hai usato --cpu (non farlo mai su macOS)
Modello troppo grande per la RAM (usa SSD streaming)
Cache KV troppo grande (riduci --ctx)

Soluzione: Non usare mai la CPU su macOS. Se il modello non entra, usa --ssd-streaming.

4. Tool calling non funziona

Diagnostica:

# Abilita trace sul server
./ds4-server --trace /tmp/trace.txt

# Cerca nel trace "DSML" o "tool call"
grep -i "dsml\|tool" /tmp/trace.txt

Verifica che:

Il modello stia effettivamente generando DSML (dovresti vedere tag <tool_calls> nel trace).
Il client stia inviando l’ID corretto nella risposta.

5. La cache KV su disco non viene riutilizzata

Diagnostica: Guarda nel trace se c’è “KV cache: hit” o “miss”. Se miss, controlla:

La directory --kv-disk-dir è quella giusta?
Il prompt è identico byte per byte? (spazi, newline, maiuscole contano)
Il modello (quant) è lo stesso? (usa --kv-cache-reject-different-quant se vuoi rifiutare quant diversi)

Strumenti aggiuntivi: `ds4-eval` per valutazione rapida

Come accennato nel capitolo 4, ds4-eval può essere usato anche per debug, eseguendo un sottoinsieme di domande e confrontando i token generati con una baseline.

# Esegui le prime 4 domande in modalità plain (non TUI)
./ds4-eval --plain --questions 4 --temp 0 --seed 1

Se i token generati non corrispondono alla baseline attesa, c’è una regressione.

Tabella di riferimento per il test deterministico

Per le prime 4 domande, i token generati attesi sono:

Domanda	Stato atteso	Token generati	Risposta data/corretta
1	PASSED	2048	B / B
2	PASSED	438	C / C
3	PASSED	666	70 / 70
4	FAILED	2048	A / C

Categorie delle domande eval

ds4-eval include 92 domande embeddate, divise in:

25 GPQA Diamond – domande di livello graduate in scienze, risposta multipla
25 SuperGPQA – conoscenze specialistiche e transfer tra domini
25 AIME 2025 – problemi di matematica olimpica, senza suggerimenti
17 COMPSEC – identificazione di vulnerabilità in funzioni C/C++ reali

`--regrade-trace`: rivalutare un trace senza ricaricare il modello

Se hai modificato l’estrattore di risposte o lo scorer, puoi riprocessare un trace salvato senza dover eseguire di nuovo l’inferenza:

./ds4-eval --regrade-trace /tmp/ds4-eval.txt

Mostra per ogni domanda: risposta precedente, nuova risposta, e pass/fail. Utile per audit delle modifiche agli evaluator.

Conclusione

I tool di debug e i test di regressione sono una delle caratteristiche più sottovalutate di ds4. Ti permettono di:

Diagnosticare problemi di tokenizzazione, sampling, tool calling.
Verificare che modifiche al codice non rompano la correttezza.
Confrontare il comportamento locale con l’API ufficiale.

Consiglio: Prima di aprire una issue su GitHub, esegui sempre make test e allega il trace (per problemi di server) o il dump dei logprobs (per problemi di generazione). Questo aiuterà antirez a diagnosticare molto più velocemente.

💡 Combinare dump e trace
Per problemi complessi, usa più strumenti insieme: ./ds4-server —trace /tmp/trace.txt e, quando il server genera una risposta sospetta, usa —dump-logprobs su uno snippet simile nel CLI isolato.

⚠️ I test vectors sono specifici per Flash e per il quant non-quantizzato?

I test vectors sono stati catturati dall’API ufficiale (modello originale, non quantizzato). ds4 testa i logits del modello quantizzato contro questi vettori. L’assunzione è che una buona quantizzazione preservi i logits sufficientemente da passare il test. Se un nuovo quant peggiora troppo i logits, il test fallirà – e questo è un buon segnale che il quant non è adatto.