Ollama num_predict: come limitare i token generati

Cosa fa num_predict in Ollama

num_predict è l'opzione di Ollama che limita il numero di token che un modello può generare in una singola risposta. Conta solo i token dell'output, quindi il prompt non viene conteggiato. Quando il modello raggiunge il limite, la generazione si interrompe nel punto corrente, talvolta a metà di una parola, e la risposta restituisce done_reason impostato su length.

Questa è l'intera funzionalità. La difficoltà consiste nel fatto che Ollama consente di impostare il valore in tre punti distinti e che prevale l'impostazione più vicina alla richiesta. Quasi tutte le segnalazioni secondo cui «num_predict non fa nulla» dipendono dal fatto che un livello sovrascrive silenziosamente un altro.

num_predict non è num_ctx

Queste due opzioni vengono confuse più di qualsiasi altra coppia in Ollama, e la confusione fa perdere tempo nelle attività di troubleshooting.

num_ctx indica quanto il modello può leggere. È la dimensione della finestra di contesto, che contiene il prompt e tutto ciò che è stato prodotto fino a quel momento. Aumentarla richiede più memoria, perché la cache key/value che il modello mantiene per quei token cresce insieme alla finestra. Dimensionare num_ctx per l’hardware è un’attività separata, con modalità di errore specifiche.

num_predict indica quanto il modello può scrivere. È una regola di arresto, non un’allocazione. Aumentarla incide sul tempo di esecuzione, non sulla RAM, e non viene riservata memoria in anticipo.

Le due opzioni interagiscono in un punto. I token generati vengono inseriti nella finestra di contesto man mano che vengono prodotti. Di conseguenza, una risposta può terminare perché la finestra si è riempita, non perché è stato raggiunto il limite configurato. Ollama restituisce length in entrambi i casi. Il valore che consente di distinguerli è eval_count, descritto più avanti.

Impostarlo una volta con un Modelfile

Un Modelfile incorpora il valore in un modello che crei. Scrivi il file:

FROM qwen3:8b
PARAMETER num_ctx 8192
PARAMETER num_predict 512

Quindi crealo e rileggi ciò che hai creato:

ollama create qwen3-capped -f Modelfile
ollama show --parameters qwen3-capped

ollama show --parameters stampa una riga per ogni parametro memorizzato, con il relativo valore. Se nell'output manca num_predict, il modello non contiene alcun limite incorporato e viene applicato il valore predefinito di Ollama. ollama show --modelfile qwen3-capped stampa l'intera definizione ed è anche il modo più rapido per copiare i parametri già inclusi in un modello esistente.

Questo è il livello corretto per un valore che vuoi applicare a ogni chiamante. Non è il livello corretto se ti aspetti che il valore sia definitivo, perché non lo è.

Impostarlo per richiesta nell'oggetto delle opzioni

Ogni endpoint di generazione accetta un oggetto options e num_predict viene inserito al suo interno:

curl http://localhost:11434/api/generate -d '{
  "model": "qwen3:8b",
  "prompt": "Explain what a reverse proxy does.",
  "stream": false,
  "options": { "num_predict": 128 }
}'

/api/chat utilizza la stessa chiave options con lo stesso significato. Il valore specificato qui si applica solo a quella chiamata. Non si applica ad altro. Questo è il livello utilizzato dai tuoi strumenti: un'interfaccia chat, uno script, un wrapper SDK o un agente di coding. Tutti inviano un oggetto options, indipendentemente dal fatto che mostrino o meno un campo per impostarlo.

Impostalo per una sessione con /set parameter

All'interno di ollama run, la sessione interattiva imposta le opzioni per il resto della sessione:

>>> /set parameter num_predict 256
>>> /show parameters

/show parameters mostra ciò che la sessione invierà con il messaggio successivo. È quindi il modo più rapido per verificare che una modifica sia stata applicata. Il valore resta attivo finché non digiti /bye. Per conservarlo, /save qwen3-capped salva la sessione corrente, inclusi i parametri, come nuovo modello. Nessun elemento che /set imposti qui viene applicato agli altri client.

Quale impostazione prevale e perché la tua sembra ignorata

L'ordine è semplice. Le opzioni inviate con la richiesta prevalgono su tutte le altre. Una riga PARAMETER num_predict nel Modelfile del modello è il valore predefinito usato quando la richiesta non contiene alcun valore. Se non è presente nessuna delle due impostazioni, si applica il valore predefinito integrato in Ollama.

/set parameter non è una terza regola. La sessione interattiva è un client API, quindi il valore impostato in quella sessione viene inviato come options della richiesta. Per questo sovrascrive il Modelfile durante la sessione.

Questo spiega il problema. Aggiungi PARAMETER num_predict 512, ricrei il modello, ma le risposte continuano ad arrivare a migliaia di token. L'impostazione è presente, come dimostra ollama show --parameters. Tuttavia viene sovrascritta a ogni richiesta, perché il client invia un proprio oggetto options con un proprio valore numerico. Spesso è un valore inserito mesi prima in una schermata delle impostazioni e poi dimenticato. ollama show legge il modello memorizzato. Non può mostrarti ciò che arriva tramite HTTP.

Verifica il lato server con un solo comando. Invia una richiesta che produca una risposta lunga, imposta un limite basso e leggi due campi:

curl -s http://localhost:11434/api/generate -d '{
  "model": "qwen3-capped",
  "prompt": "Describe the Linux boot process in detail.",
  "stream": false,
  "options": { "num_predict": 32 }
}' | jq '.done_reason, .eval_count'

Il comando dovrebbe stampare "length" e 32. Se manca, installa prima jq con sudo apt install -y jq. Una risposta "length" e 32 indica che il server applica l'opzione e che l'applicazione ne invia una diversa. Per vedere come il server registra la richiesta, riavvialo con OLLAMA_DEBUG=1 nell'ambiente e monitora journalctl -u ollama -f mentre l'applicazione comunica con il server.

I valori negativi e i numeri da non copiare

num_predict accetta anche valori negativi, che fungono da sentinel e non da conteggi. Un valore negativo significa «non applicare alcun limite e continua a generare». Un altro ha indicato «riempi il contesto rimanente». Ad agosto 2026 il riferimento di Ollama per il Modelfile indica -1 come valore predefinito per la generazione infinita; nelle versioni precedenti, la stessa tabella riportava anche -2 per riempire il contesto.

Considera tutto questo dipendente dalla versione, perché il comportamento è cambiato. Per molto tempo il riferimento ha documentato 128 come valore predefinito, prima che la voce venisse corretta alla fine del 2024. Per questo molte guide riportano ancora il numero precedente. Consulta il riferimento dei parametri del Modelfile relativo alla versione in esecuzione, quindi verifica il comportamento con il controllo eval_count indicato sopra. Un valore verificato sul tuo server è più affidabile di un valore letto altrove, incluso questo articolo.

Perché la lunghezza dell’output è il costo principale su un VPS con sola CPU

La generazione ha due fasi, con velocità molto diverse. I token del prompt vengono valutati in batch, molti alla volta. I token dell’output vengono prodotti uno alla volta e ciascuno richiede un passaggio completo sui pesi del modello. Su un VPS con sola CPU, questo passaggio è limitato dalla larghezza di banda della memoria. Per questo motivo, un token generato costa molto più di un token del prompt.

Richiedi una risposta senza streaming e i numeri sono immediatamente disponibili:

"prompt_eval_count": 26,
"prompt_eval_duration": 107345000,
"eval_count": 237,
"eval_duration": 4289432000

Le durate sono espresse in nanosecondi. In quel blocco, che contiene la risposta di esempio pubblicata nella documentazione dell’API di Ollama e non una misurazione eseguita su un server specifico, 26 token del prompt hanno richiesto circa 0.1 secondi, mentre 237 token dell’output hanno richiesto circa 4.3 secondi. La tua velocità di generazione è eval_count diviso per eval_duration, convertita in secondi. Vale la pena misurare i token al secondo sul proprio hardware una volta, prima di ottimizzare qualsiasi altro parametro. Questa velocità dipende dal modello tanto quanto dalla macchina. Se il costo reale è rappresentato dalle risposte lunghe, un modello progettato per la decodifica rapida, come Nemotron 3.5 Lightning su un VPS, recupera parte del tempo che altrimenti verrebbe protetto imponendo un limite basso.

Il resto deriva dall’aritmetica. A 8 token al secondo, una risposta di 2,000 token occupa la macchina per più di quattro minuti, mentre il modello non sa che volevi soltanto un paragrafo. Alcuni modelli possono anche entrare in un ciclo e ripetere una frase finché qualcosa non li interrompe. Senza un limite, quella singola richiesta mantiene occupato un core fino all’esaurimento della finestra di contesto. num_predict è l’impostazione che pone questo limite. È particolarmente importante su un piccolo VPS Ollama self-hosted, dove una singola richiesta lunga può occupare l’intera macchina.

L'output troncato è di solito il limite, non un modello guasto

I sintomi sembrano indicare un problema del modello. Una risposta che si interrompe a metà frase. JSON non analizzabile perché manca la parentesi graffa di chiusura. La reazione istintiva è dare la colpa al modello o alla quantizzazione. Leggi prima la risposta.

done_reason indica che il modello ha risposto direttamente alla domanda. stop indica che il modello ha terminato autonomamente, emettendo il proprio token end-of-sequence oppure trovando una delle stringhe nell'opzione stop. length indica che la generazione è stata interrotta perché non c'era più spazio disponibile. Quando vedi length, confronta eval_count con il tuo limite: una corrispondenza esatta significa che num_predict ha interrotto la generazione; un numero inferiore significa che la finestra di contesto si è riempita prima.

Durante lo streaming, questi campi arrivano nell'ultimo chunk, quello che contiene "done": true. Molte librerie client scartano questo chunk e passano al codice soltanto il testo. Per questo, all'interno di un'applicazione, la stessa troncatura sembra inspiegabile, mentre con curl è evidente. Se una libreria nasconde questo dato, invia una richiesta con curl per verificare la risposta effettiva del server.

Un ultimo aspetto evita di perdere un pomeriggio. Aumentare num_predict non fa scrivere di più al modello. Rimuove soltanto un limite massimo. Se una risposta termina dopo 200 token con done_reason di stop, il modello ha deciso di aver finito e un limite più alto non cambia nulla. Le risposte brevi con stop sono un problema di prompt. Le risposte brevi con length sono un problema di limite.

Scelta del valore

• Per la chat interattiva, non impostare alcun limite e premi Ctrl+C per interrompere una risposta che non termina. Stai comunque osservando lo schermo.
• Per tutto ciò che viene eseguito tramite script, impostalo. Una generazione senza limite all'interno di un ciclo può far sì che un job batch, che dovrebbe durare dieci minuti, sia ancora in esecuzione la mattina successiva.
• Per l'output strutturato, imposta il limite al di sopra del documento valido più grande previsto, quindi considera done_reason di length un errore irreversibile e riprova invece di analizzare ciò che è stato restituito.
• Per un coding agent, il valore deve trovarsi nella configurazione dell'agent, perché l'agent invia le proprie opzioni a ogni richiesta. Collegare un coding agent a Ollama spiega dove si trovano queste impostazioni.

Il limite conta i token, non le parole né i caratteri, quindi non stimarlo. Genera una risposta rappresentativa senza limite, leggi eval_count e imposta il limite con un margine adeguato al di sopra di quel valore. Le famiglie di modelli usano tokenizzazione diversa, quindi un valore sufficiente per un modello Llama può troncare la stessa risposta di un modello Qwen 3 sullo stesso VPS.

FAQ

Qual è la differenza tra num_ctx e num_predict in Ollama?

num_ctx indica la dimensione della finestra di contesto, quindi stabilisce quanto testo il modello può leggere: il prompt e tutto ciò che è stato prodotto fino a quel momento. Consuma memoria, perché la cache key/value cresce insieme a questo valore. num_predict stabilisce quanti token il modello può scrivere in una singola risposta. Consuma tempo invece di memoria e non viene riservato in anticipo. I token generati vengono conteggiati rispetto a entrambi i limiti, quindi una risposta può essere interrotta dall'uno o dall'altro.

Perché l'impostazione num_predict sembra essere ignorata?

Perché un valore inviato nella richiesta sovrascrive quello memorizzato nel modello. Inserisci PARAMETER num_predict 512 in un Modelfile, quindi usa quel modello da un'interfaccia chat o da un coding agent: il client invia un proprio oggetto options e prevale il valore contenuto nella richiesta. ollama show --parameters stampa comunque il tuo valore, perché legge il modello memorizzato e non può vedere ciò che arriva tramite HTTP. Invia una richiesta con curl usando "options": {"num_predict": 32} e verifica che eval_count restituisca 32. Questo conferma che il server funziona correttamente e sposta la ricerca del problema nell'applicazione.

Come posso capire se l'output è stato interrotto da num_predict?

Invia la richiesta con "stream": false e leggi done_reason. Il valore stop indica che il modello ha terminato autonomamente. Il valore length indica che ha esaurito lo spazio disponibile. Confronta quindi eval_count con il tuo limite: se coincidono esattamente, num_predict ha interrotto la generazione; se eval_count è inferiore, la finestra di contesto si è riempita prima. Durante lo streaming, entrambi i campi arrivano nell'ultimo blocco insieme a "done": true, che molte librerie client eliminano prima che il codice possa leggerlo.

Qual è il valore predefinito di num_predict?

Leggilo dalla tua installazione invece di basarti su un articolo. Ad agosto 2026 la documentazione di riferimento del Modelfile di Ollama indica come valore predefinito -1, cioè che la generazione non è limitata; questa voce è stata corretta alla fine del 2024, dopo anni in cui veniva documentato 128. I valori negativi sono sentinelle, non quantità, e nelle versioni precedenti della stessa tabella era indicato anche -2 per utilizzare il contesto rimanente. Consulta il riferimento dei parametri di Modelfile relativo alla tua versione, quindi verifica il valore con ollama show --parameters e una richiesta curl.

Aumentare num_predict fa scrivere risposte più lunghe al modello?

No. Rimuove soltanto un limite superiore. Se una risposta termina con done_reason di stop, il modello ha stabilito di aver concluso e un limite più alto non cambia il risultato. In questo caso, la lunghezza dipende dal prompt: chiedi una struttura specifica, un determinato numero di sezioni o un livello di dettaglio esplicito. Aumenta num_predict solo quando done_reason restituisce length.