SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor · Aggiornato 2026-10-26

Ollama num_predict: limita la lunghezza dell’output

Scopri come num_predict limita i token generati da Ollama, dove impostarlo, quale valore prevale e come interpretare done_reason nella risposta.

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 qualsiasi 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 conserva per questi token cresce insieme alla finestra. Dimensionare num_ctx per l'hardware è un'attività distinta, 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, non RAM, e non viene riservata memoria in anticipo.

Le due opzioni si incontrano in un solo punto. I token generati entrano nella finestra di contesto man mano che vengono prodotti. In Ollama v0.40.11 lo scorrimento del contesto è attivo per impostazione predefinita nella maggior parte dei modelli, quindi, quando la finestra è piena, i token più vecchi vengono rimossi e la generazione continua. Se lo scorrimento è disattivato, perché la richiesta invia "shift": false o perché il modello non supporta lo scorrimento, la risposta può interrompersi anche perché la finestra si è riempita, anziché perché è stato raggiunto il limite impostato. Ollama restituisce length in entrambi i casi, quindi il numero che li distingue è 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 tutto il resto. Una riga PARAMETER num_predict nel Modelfile del modello è il valore di fallback usato quando la richiesta non contiene alcun valore. Se non è presente neppure quella, si applica il valore predefinito integrato di Ollama.

/set parameter non è una terza regola. La sessione interattiva è un client API. Ciò che imposti nella sessione viene quindi inviato come options di quella richiesta. Per questo prevale sul Modelfile durante la sessione.

Questo spiega il problema. Aggiungi PARAMETER num_predict 512, ricompili il modello e 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 si tratta di 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 lato server con un solo comando. Invia una richiesta che produca 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'

Una risposta dettagliata supera ampiamente 32 token. Devi quindi aspettarti "length" e 32. Se manca, installa prima jq con sudo apt install -y jq. Il valore 32 non è garantito, perché eval_count è semplicemente il numero di token di output generati effettivamente dal server. Se il modello termina prima, ottieni "stop" e un conteggio inferiore. In questo caso devi usare un prompt che chieda una risposta più lunga. Quando ottieni "length" e 32, il valore della richiesta ha prevalso sul valore 512 memorizzato in qwen3-capped. Questo dimostra che il server rispetta le opzioni specificate per ogni richiesta. Non indica però che cosa invia la tua applicazione. La ricerca passa quindi al client. Per vedere il resoconto del server su 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 da non copiare

num_predict accetta anche valori negativi, che vengono interpretati come sentinel e non come conteggi. Un valore negativo significa «non applicare questo limite e continua a generare». Un altro ha indicato «riempi il contesto rimanente». A ottobre 2026, la documentazione di riferimento di Ollama per Modelfile indica -1 come valore predefinito, cioè generazione infinita, mentre le versioni precedenti della stessa tabella riportavano anche -2 per riempire il contesto.

Considera tutto questo dipendente dalla versione, perché i valori sono cambiati. Per molto tempo la documentazione indicava 128 come valore predefinito, prima di correggere la voce in -1. Per questo molte guide riportano ancora il numero precedente. Anche il comportamento è cambiato. Ollama v0.40.11, la versione corrente il 25 ottobre 2026, passa i modelli GGUF a un processo upstream llama-server che richiede un budget finito. Di conseguenza sostituisce qualsiasi valore negativo e qualsiasi limite superiore a dieci volte num_ctx con dieci volte num_ctx. Pertanto, per il modello qwen3-capped indicato sopra, «infinito» significa 81,920 token, mentre -2 non si comporta più diversamente da -1. Consulta la documentazione di riferimento dei parametri di Modelfile relativa alla versione in esecuzione, quindi verifica il comportamento con il controllo eval_count indicato sopra. Un valore verificato sul tuo sistema è più affidabile di un valore letto altrove, incluso questo articolo.

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

Ollama è gratuito da eseguire su una macchina che controlli, quindi la generazione locale non viene mai tariffata e una risposta lunga viene pagata in tempo. 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 sui pesi che utilizza. Su un VPS con sola CPU, questo passaggio è limitato dalla larghezza di banda della memoria, quindi un token generato costa molto più di un token del prompt. Poiché il passaggio deve leggere ogni peso utilizzato dal token (tutti i pesi in un modello denso, solo gli esperti instradati in un modello mixture-of-experts come Nemotron 3.5 Lightning, che attiva circa 3B dei suoi 30B parametri per token), il numero di byte occupati da ciascun peso stabilisce il limite superiore del numero di token al secondo. Per questo una build q4 decodifica più velocemente dello stesso modello a q8 o fp16.

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

"prompt_eval_count": 11,
"prompt_eval_duration": 13074791,
"eval_count": 18,
"eval_duration": 52479709

Le durate sono espresse in nanosecondi. In quel blocco, che corrisponde alla risposta di esempio pubblicata nella documentazione dell'API di Ollama a ottobre 2026 e non a una misurazione di un server specifico, 11 token del prompt hanno richiesto circa 0.013 secondi, mentre 18 token dell'output hanno richiesto circa 0.052 secondi. Si tratta di circa 1.2 millisecondi per token del prompt contro 2.9 millisecondi per token dell'output. Anche in una risposta di una sola riga, quindi, ogni token generato è costato più del doppio di ogni token letto; in una risposta lunga, è l'output a occupare la maggior parte del tempo. La tua velocità di generazione è eval_count diviso per eval_duration, convertita in secondi, e 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 le risposte lunghe sono il costo reale, un modello progettato per una decodifica rapida come Nemotron 3.5 Lightning su un VPS riduce parte del tempo che altrimenti un limite basso dovrebbe contenere.

Il calcolo completa il quadro. A 8 token al secondo, una risposta di 2,000 token impegna la macchina per più di quattro minuti e il modello non sa che volevi un paragrafo. Un modello di ragionamento usa parte di quel budget per pensare prima di scrivere una parola richiesta, e anche questo ragionamento viene generato un token alla volta, come tutto il resto. Di conseguenza, il livello di ragionamento richiesto è un'altra leva sullo stesso costo. Alcuni modelli entrano anche in loop e ripetono una frase finché qualcosa non li interrompe. Senza un limite, quella singola richiesta mantiene occupata una CPU finché raggiunge dieci volte num_ctx token, perché il cambio di contesto impedisce che una finestra completa la interrompa. num_predict è l'impostazione che pone questo limite. È particolarmente importante su un VPS Ollama self-hosted di piccole dimensioni, dove una singola richiesta lunga può occupare l'intera macchina.

L'output troncato di solito dipende dal limite, non da un modello danneggiato

I sintomi fanno pensare a un problema del modello. Una risposta che si interrompe a metà frase. JSON che non può essere analizzato perché la parentesi graffa di chiusura non è mai arrivata. La reazione immediata è incolpare il modello o la quantizzazione. Prima leggere la risposta.

done_reason risponde direttamente alla domanda. stop indica che la generazione è terminata prima di raggiungere qualsiasi limite, perché il modello ha emesso il token di fine sequenza oppure perché l'output corrispondeva a una delle stringhe nell'opzione stop, che interrompe la risposta nel punto in cui viene trovata la corrispondenza. length indica che la generazione è stata interrotta perché lo spazio disponibile era esaurito. Quando si vede length, confrontare eval_count con il limite: una corrispondenza esatta significa che num_predict l'ha interrotta, mentre un numero inferiore significa che la finestra di contesto si è riempita prima. Questo può accadere solo con lo spostamento del contesto disattivato.

Quando si usa lo streaming, questi campi arrivano nell'ultimo blocco, quello che contiene "done": true. Molte librerie client scartano quel blocco e passano al codice soltanto il testo. Per questo la stessa troncatura appare inspiegabile all'interno di un'applicazione, ma è evidente in curl. Se una libreria nasconde queste informazioni, inviare una richiesta con curl per verificare che cosa ha realmente restituito il server.

Un altro aspetto evita di sprecare un pomeriggio. Aumentare num_predict non fa scrivere di più al modello. Rimuove soltanto un limite massimo. Se una risposta termina a 200 token con done_reason di stop, il modello ha deciso che la risposta era completa oppure una delle stringhe stop ha trovato una corrispondenza; un limite più alto non cambia nulla. Le risposte brevi con stop indicano un problema di prompt o di stringhe di arresto. 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 il modello può leggere: il prompt più 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 anziché memoria e non riserva spazio in anticipo. I token generati vengono conteggiati in entrambi i valori, quindi, con lo context shift disattivato, una risposta può essere interrotta da uno dei due limiti.

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 di chat o da un coding agent: il client invierà un proprio oggetto options, il cui valore numerico avrà la precedenza. ollama show --parameters continuerà a mostrare 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 un prompt che richieda una risposta lunga, quindi leggi done_reason e eval_count. Un length con un eval_count pari a 32 mostra il valore della richiesta al posto di quello memorizzato. Questo conferma che il server funziona correttamente e sposta la ricerca del problema nell'applicazione. Un stop con un conteggio più basso indica soltanto che il modello ha terminato prima. Ripeti quindi il test con un prompt che richieda una risposta più lunga.

Come posso capire se num_predict ha troncato l'output?

Invia la richiesta con "stream": false e leggi done_reason. Un valore stop indica che il modello ha terminato autonomamente oppure che una delle stringhe stop ha concluso la generazione. Un valore length indica che lo spazio disponibile è terminato. Confronta quindi eval_count con il tuo limite: se i valori coincidono esattamente, num_predict ha interrotto la generazione; se eval_count è più piccolo, la finestra di contesto si è riempita prima. Durante lo streaming, entrambi i campi arrivano nell'ultimo chunk insieme a "done": true. Molte librerie client lo eliminano prima che il codice possa leggerlo.

Qual è il valore predefinito di num_predict?

Leggilo dalla tua installazione invece di affidarti a un articolo. A ottobre 2026 la documentazione di riferimento del Modelfile di Ollama indica come valore predefinito -1. Questo significa che la generazione non è limitata. Questa voce è stata corretta dopo un lungo periodo in cui veniva documentato 128. In Ollama v0.40.11 questo valore predefinito senza limite, come qualsiasi valore negativo, si interrompe di fatto dopo dieci volte num_ctx. I valori negativi sono sentinel e non conteggi. Le versioni precedenti della stessa tabella indicavano anche -2 per utilizzare il contesto rimanente. Consulta la documentazione di riferimento dei parametri del Modelfile relativa 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 massimo. Se una risposta termina con done_reason di stop, il modello ha stabilito di aver concluso oppure una delle stringhe stop ha prodotto una corrispondenza; un limite più alto non cambia il risultato. In questo caso la lunghezza dipende dal prompt: richiedi una struttura specifica, un numero di sezioni oppure un livello di dettaglio esplicito. Aumenta num_predict solo quando done_reason restituisce length.

Questo articolo ti è stato utile?