Thinking mode e sampling: come controllare la generazione

Uno dei punti di forza di DeepSeek V4 è la capacità di ragionare internamente prima di rispondere. ds4 espone questa funzionalità attraverso il flag --think (o /think nel CLI) e i parametri di campionamento ispirati all’API ufficiale. In questo capitolo capiamo come funzionano e quando usarli.

Le tre modalità di ragionamento

Modalità	Descrizione	Quando usarla
Non-thinking	Il modello risponde direttamente, senza generare un ragionamento interno.	Risposte semplici, chat veloci, basso consumo di token.
Thinking (normale)	Il modello genera un ragionamento nascosto (tra tag `<tr> think ...</tr>`), poi la risposta finale.	Problemi di ragionamento, matematica, coding complesso, tool calling.
Think Max	Versione più approfondita del thinking, con più token di ragionamento.	Problemi molto difficili (es. AIME, GPQA), ma richiede più contesto e tempo.

Attivazione nel CLI

# Non-thinking (risposta diretta)
./ds4 -p "Quanto fa 15 * 37?" --nothink

# Thinking (default)
./ds4 -p "Quanto fa 15 * 37?" --think

# Think Max (richiede contesto maggiore)
./ds4 -p "Risolvi questo problema di matematica..." --think --think-max

All’interno del CLI interattivo, puoi cambiare modalità al volo:

ds4> /nothink
ds4> /think
ds4> /think-max

Attivazione nel server API

OpenAI / Responses:

{
  "model": "deepseek-v4-flash",
  "messages": [...],
  "reasoning_effort": "max"   // "none" (non-thinking), "low"/"high" (thinking), "max" (think max)
}

Nota: reasoning_effort: "xhigh" (usato da alcuni client) viene mappato a thinking normale, non a Think Max.

Anthropic:

{
  "model": "deepseek-v4-flash",
  "messages": [...],
  "thinking": {"type": "enabled", "budget_tokens": 8000}
}

Il server mappa:

thinking.type = "disabled" → non-thinking
thinking.type = "enabled" → thinking (normale)
reasoning_effort = "max" + contesto sufficiente → think max

Think Max: quando viene attivato?

Secondo la raccomandazione del modello, Think Max viene applicato solo se il contesto disponibile è sufficiente. Se hai impostato --ctx 32768 ma il modello pensa di aver bisogno di almeno 100k token per un ragionamento approfondito, ds4 decade automaticamente a thinking normale.

Non esiste una soglia fissa; è una decisione euristica basata sulla complessità del prompt.

Parametri di campionamento

I parametri di campionamento controllano come il modello sceglie il prossimo token tra le probabilità calcolate.

Temperatura (`temperature`)

Controlla la creatività o casualità della generazione.

Valore	Effetto	Uso tipico
0	Deterministico (sceglie sempre il token più probabile)	Coding, fatti, risposte precise
0.5 - 0.7	Bassa creatività	Chat ragionevolmente prevedibili
1.0	Equilibrio	Default, buono per conversazione generale
> 1.0	Alta creatività, possibili allucinazioni	Poesia, brainstorming, idee creative

Tecnicamente: La temperatura ridistribuisce le probabilità. Con T<1, i token più probabili diventano ancora più probabili; con T>1, le probabilità si appiattiscono.

Top-p (nucleus sampling)

Seleziona il sottoinsieme più piccolo di token la cui probabilità cumulativa supera p, poi campiona solo tra quelli.

Valore	Effetto
0.9 - 1.0	Considera molti token (più varietà)
0.5 - 0.8	Riduce le scelte, più coerenza
0.1 - 0.3	Molto restrittivo, quasi deterministico

Esempio: Con top_p=0.9, vengono considerati i token fino a coprire il 90% della massa di probabilità.

Min-p (filtro per probabilità relativa)

min_p è un filtro meno comune ma molto utile. Scarta i token la cui probabilità è inferiore a min_p * (probabilità del token più probabile).

Valore	Effetto
0.0	Nessun filtro (equivale a `top_p=1`)
0.05 - 0.1	Rimuove token molto improbabili (default ds4)
0.2 - 0.3	Molto selettivo, solo token ragionevoli

Esempio: Se il token più probabile ha probabilità 0.8, e min_p=0.05, vengono mantenuti solo i token con probabilità > 0.04.

Vantaggio rispetto a top_p: min_p scala meglio con temperature diverse. A temperature basse, la massa di probabilità si concentra su pochi token e min_p li mantiene; a temperature alte, la massa si distribuisce e min_p permette più varietà. È il filtro predefinito nel server ds4.

Top-k

Considera solo i k token con probabilità più alta, indipendentemente dalla loro probabilità cumulativa.

Valore	Effetto
1	Deterministico (equivale a temperatura 0)
40 - 100	Tipico, limita le scelte assurde
∞ (nessun top-k)	Considera tutti i token

In ds4, top_k non è impostato di default (usa solo top_p e min_p). Puoi passarlo esplicitamente.

Seed

Imposta un seme casuale per rendere la generazione riproducibile. A parità di seed, temperatura=0, top_p=1, min_p=0, la generazione è identica (deterministica).

./ds4 -p "Ciao" --seed 42 --temp 0

I parametri di default in ds4

Contesto	temperature	top_p	min_p	top_k
CLI (nessuna specifica)	0.8	0.9	0.05	nessuno
CLI con `--temp 0`	0	1	0	nessuno
Server API (thinking)	1	1	0.05	nessuno
Server API (non-thinking)	come da richiesta	come da richiesta	come da richiesta	come da richiesta

Nota importante: Quando il server è in modalità thinking, ignora i parametri di campionamento passati dal client e usa i suoi default (1, 1, 0.05). Questo perché l’API ufficiale di DeepSeek in modalità thinking ha un comportamento fissato. In modalità non-thinking, invece, rispetta i parametri del client.

Consigli pratici per agenti di coding

Per agenti che scrivono codice (Codex CLI, Claude Code, OpenCode), le raccomandazioni sono:

Temperatura = 0 (o 0.1 massimo) – Vuoi risposte deterministiche e riproducibili.
Thinking mode attiva (reasoning_effort: "low" o "high") – Il ragionamento aiuta a scrivere codice corretto.
Top_p = 0.9 o min_p = 0.05 – Un po’ di flessibilità, ma non troppa.
Seed fisso (es. 42) – Se vuoi riprodurre esattamente gli stessi output nei test.

Esempio di configurazione per Codex CLI (nel file di configurazione):

[model_providers.ds4]
temperature = 0.0
top_p = 0.95

Impatto sulla velocità e sul consumo di token

La modalità thinking consuma più token perché genera il ragionamento prima della risposta. Per un problema complesso, il ragionamento può essere lungo da centinaia a migliaia di token.

Modalità	Token generati (esempio problema medio)	Velocità relativa
Non-thinking	100	1x (più veloce)
Thinking	300 (200 ragionamento + 100 risposta)	0.5x
Think Max	800 (700 ragionamento + 100 risposta)	0.2x

Consiglio: Usa thinking solo quando serve. Per domande semplici (“Che ore sono?”, “Traduci questa frase”), non-thinking è più che sufficiente. Per problemi di matematica, debugging, pianificazione complessa, attiva il thinking.

Come verificare che il thinking stia funzionando

Nel CLI, vedrai il ragionamento visualizzato (di solito in un colore diverso o separato da marcatori). Nel server API in streaming, il reasoning viene inviato come eventi separati (es. reasoning chunk in Responses API, o thinking blocco in Anthropic).

Se vuoi disabilitare completamente il thinking (anche se il client lo richiede), puoi lanciare il server con:

./ds4-server --nothink   # forza non-thinking per tutte le richieste

Parametri avanzati: logprobs e dump

Per debug, puoi chiedere al modello di restituire le probabilità dei token (logprobs):

./ds4 -p "Ciao" --dump-logprobs /tmp/logprobs.json --logprobs-top-k 5 --temp 0

Questo produce un JSON con, per ogni token generato, i 5 token alternativi più probabili e i loro logprobs. Utile per verificare se il modello è incerto su certe scelte.

Conclusione

I parametri di campionamento e le modalità di thinking sono strumenti potenti per adattare il comportamento del modello al tuo caso d’uso. Per agenti di coding, la combinazione vincente è spesso: temperatura 0, thinking attivo, min_p=0.05. Per chat creative, temperatura 0.8, top_p=0.9, thinking disattivato.

Sperimenta e trova la configurazione che funziona meglio per i tuoi prompt.

💡 Il segreto del min_p
Molti utenti non conoscono min_p e continuano a usare solo top_p. Provalo: a parità di temperatura, min_p=0.05 spesso produce risultati più coerenti e meno allucinazioni di top_p=0.9, specialmente su modelli MoE come DeepSeek V4.

📘 Perché il server ignora i parametri di sampling in modalità thinking?

L’API ufficiale di DeepSeek, in modalità thinking, ha un comportamento fissato (temperatura=1, top_p=1, min_p=0.05). Cambiare questi parametri potrebbe interferire con la qualità del ragionamento o produrre output non validi. ds4 replica fedelmente questo comportamento per garantire compatibilità e qualità.