Ollama num_predict: limita la lunghezza dell’output

Che 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 incide su questo limite. 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à è che Ollama consente di impostare il valore in tre punti distinti e 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 qualunque altra coppia in Ollama, e la confusione fa perdere molto tempo nel debugging.

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 il proprio hardware è un’attività separata, con modalità di errore proprie.

num_predict indica quanto il modello può scrivere. È una regola di arresto, non un’allocazione. Aumentarlo richiede tempo di esecuzione invece di RAM e non viene riservato nulla in anticipo.

Le due opzioni interagiscono in un solo punto. I token generati vengono inseriti nella finestra di contesto man mano che vengono prodotti, quindi una risposta può interrompersi anche perché la finestra si è riempita, non perché è stato raggiunto il limite impostato. Ollama segnala length in entrambi i casi, quindi il numero che permette di distinguerli è eval_count, descritto più avanti.

Impostalo 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 impostato:

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 la definizione completa. È anche il modo più rapido per copiare i parametri già presenti in un modello esistente. La creazione di un modello con limite in questo modo richiede pochissimo spazio aggiuntivo su disco, perché la nuova voce riutilizza i blob dei pesi già scaricati dal modello di base invece di copiarli. È utile sapere dove Ollama conserva questi blob prima che il disco root di un VPS si riempia.

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

Impostalo per richiesta nell’oggetto delle opzioni

Ogni endpoint di generazione accetta un oggetto options, al cui interno va inserito num_predict:

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. Un valore impostato qui si applica solo a quella chiamata e a nient’altro. Questo è il livello utilizzato dai tuoi strumenti: un’interfaccia chat, uno script, un wrapper SDK o un agente di programmazione. Tutti inviano un oggetto options, indipendentemente dal fatto che mostrino o meno un campo per impostarlo.

Impostarlo per una sessione con il parametro /set

In ollama run, la sessione interattiva imposta le opzioni per il resto della sessione:

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

/show parameters visualizza ciò che la sessione invierà con il messaggio successivo. È quindi il modo più rapido per verificare che una modifica sia stata applicata. Il valore rimane attivo finché non si digita /bye. Per conservarlo, /save qwen3-capped salva la sessione corrente, inclusi i parametri, come nuovo modello. Nessun elemento /set qui raggiunge 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 viene usata come fallback quando la richiesta non contiene alcun valore. Se non è presente nessuna delle due impostazioni, viene applicato il valore predefinito integrato di Ollama.

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

Questo spiega il problema. Aggiungi PARAMETER num_predict 512, ricrei il modello e le risposte continuano a contenere migliaia di token. L'impostazione è presente e ollama show --parameters lo conferma. Tuttavia, viene sovrascritta a ogni richiesta, perché il client invia un proprio oggetto options con un proprio valore numerico. Spesso è un numero 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 comportamento del server con un solo comando. Invia una richiesta che produrrà una risposta lunga, forza 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 con "length" e 32 indica che il server rispetta l'opzione e che l'applicazione ne invia una diversa. Per vedere come il server registra direttamente una 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 che non devi copiare

num_predict accetta anche valori negativi, che in questo caso sono sentinelle e non conteggi. Un valore negativo significa «non applicare questo limite e continua a generare». Un altro ha indicato «riempi il contesto rimanente». Ad agosto 2026, la documentazione di riferimento di Ollama per Modelfile indica -1 come valore predefinito, corrispondente alla generazione infinita; nelle versioni precedenti della stessa tabella compariva anche -2 per riempire il contesto.

Considera tutto questo dipendente dalla versione, perché i valori sono cambiati. Per molto tempo la documentazione ha indicato 128 come valore predefinito, prima che la voce venisse corretta alla fine del 2024. Per questo molte guide riportano ancora il numero precedente. Consulta la documentazione di riferimento dei parametri di Modelfile relativa alla versione che esegui, quindi conferma il comportamento con il controllo eval_count riportato 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 avviene in 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, generare un token costa molto più che valutare un token del prompt. Poiché il passaggio deve leggere tutti i pesi, il numero di byte occupati da ciascun peso determina il limite superiore della velocità di generazione. Per questo una build q4 decodifica più velocemente dello stesso modello in q8 o fp16.

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. Nel 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. Misurare i token al secondo sul tuo hardware è utile farlo una volta, prima di ottimizzare qualsiasi altro parametro. Questa velocità dipende dal modello tanto quanto dalla macchina. Se il costo principale sono le risposte lunghe, un modello progettato per una decodifica rapida, come Nemotron 3.5 Lightning su un VPS, può recuperare parte del tempo che altrimenti proteggeresti con un limite basso.

Il calcolo completa il quadro. A 8 token al secondo, una risposta di 2,000 token occupa la macchina per più di quattro minuti e il modello non sa che volevi un paragrafo. Un modello di ragionamento utilizza una parte di quel budget per elaborare la risposta prima di scrivere una parola. Anche questo ragionamento viene generato un token alla volta, come tutto il resto. Di conseguenza, il livello di ragionamento richiesto è un altro parametro che incide sullo stesso costo. Alcuni modelli possono anche entrare in un ciclo e ripetere una frase finché qualcosa non li interrompe. Senza un limite, la singola richiesta mantiene occupato un core finché non si esaurisce la finestra di contesto. num_predict è l'impostazione che pone questo limite. È particolarmente importante su un VPS Ollama self-hosted di piccole dimensioni, dove una sola richiesta lunga può occupare l'intera macchina.

L’output troncato di solito indica il limite raggiunto, non un modello difettoso

I sintomi fanno pensare a un errore del modello. Una risposta che si interrompe a metà frase. JSON non analizzabile perché manca la parentesi graffa di chiusura. La reazione immediata è incolpare il modello o la quantizzazione. Prima controllate la risposta.

done_reason indica che il modello ha risposto direttamente alla domanda. stop indica che il modello ha terminato autonomamente, emettendo il token di fine sequenza oppure trovando una delle stringhe definite nell’opzione stop. length indica che la generazione è stata interrotta perché non c’era più spazio disponibile. Quando vedete length, confrontate eval_count con il vostro limite: una corrispondenza esatta indica che num_predict ha interrotto la generazione, mentre un numero inferiore indica che la finestra di contesto si è riempita prima.

Durante lo streaming, questi campi arrivano nell’ultimo blocco, quello che contiene "done": true. Molte librerie client scartano questo blocco e restituiscono al codice soltanto il testo. Per questo, all’interno di un’applicazione, la stessa troncatura può sembrare inspiegabile, mentre sotto curl è evidente. Se una libreria nasconde queste informazioni, inviate una richiesta con curl per verificare la risposta effettiva del server.

Un ultimo aspetto evita di perdere tempo. Aumentare num_predict non fa scrivere di più al modello. Rimuove soltanto un limite superiore. Se una risposta termina a 200 token con done_reason di stop, significa che il modello ha deciso di aver concluso e un limite più alto non cambia nulla. Le risposte brevi con stop indicano un problema di prompting. Le risposte brevi con length indicano un problema di limite.

Scelta del valore

• Per una chat interattiva, lascia il limite non impostato e premi Ctrl+C per interrompere una risposta che non termina. In questo caso stai già controllando 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 processo batch, che dovrebbe durare dieci minuti, sia ancora in esecuzione la mattina successiva.
• Per l'output strutturato, imposta il limite sopra la dimensione del documento valido più grande previsto, quindi considera done_reason di length un errore definitivo e riprova invece di analizzare l'output ricevuto.
• Per un agente di codifica, il valore deve essere impostato nella configurazione dell'agente, perché l'agente invia le proprie opzioni a ogni richiesta. Configurare un agente di codifica per usare 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. Le famiglie di modelli utilizzano sistemi di tokenizzazione diversi, 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 può leggere il modello: il prompt più tutto ciò che ha prodotto fino a quel momento. Consuma memoria, perché la key/value cache cresce con questa dimensione. num_predict stabilisce quanti token il modello può scrivere in una singola risposta. Consuma tempo anziché memoria e non riserva spazio 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 continua a stampare 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 con "done": true, che molte librerie client eliminano prima che il codice possa leggerli.

Qual è il valore predefinito di num_predict?

Leggilo dalla tua installazione invece di affidarti a un articolo. Ad agosto 2026 il riferimento al 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 e non quantità di token; le versioni precedenti della stessa tabella indicavano anche -2 per riempire il contesto rimanente. Consulta il riferimento ai parametri del Modelfile relativo alla tua versione, quindi verifica il valore con ollama show --parameters e una richiesta curl.

Aumentare num_predict fa sì che il modello scriva risposte più lunghe?

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