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

Ollama: come impostare num_ctx e la lunghezza del contesto

Ollama può troncare i prompt lunghi: num_ctx predefinito e valori dipendenti dalla VRAM cambiano tra build. Impostalo per richiesta o server e calcola la RAM KV.

Che cosa fa num_ctx e perché il prompt lungo è stato troncato

La lunghezza del contesto di Ollama è il numero di token che un modello caricato può mantenere in memoria contemporaneamente; num_ctx è l’opzione che la imposta. Ollama sceglie un valore predefinito molto inferiore al massimo dichiarato dal modello, quindi un prompt più lungo viene troncato prima ancora che il modello lo legga. La risposta non indica in alcun modo che questo sia avvenuto.

Nella libreria dei modelli Ollama, Llama 3.1 8B è indicato con una finestra di contesto di 128k. Un server con la configurazione predefinita non assegna questa capacità. La documentazione di Ollama riporta valori predefiniti diversi in pagine diverse: le FAQ indicano 4096 token, il riferimento a Modelfile indica che num_ctx ha come valore predefinito 2048 e la pagina sulla lunghezza del contesto afferma che il valore predefinito viene scelto in base alla VRAM disponibile (memoria video): 4k sotto 24 GiB, 32k da 24 GiB fino a 48 GiB e 256k a partire da 48 GiB. Ciascuno di questi valori era corretto per alcune build. La lezione utile è questa: leggete il valore dal server in esecuzione, invece di fidarvi di una pagina qualsiasi, inclusa questa.

Il troncamento non è evidente perché il modello risponde comunque e la risposta continua a essere ben scritta. Tuttavia, viene generata sulla parte finale dell’input. Un riepilogo che ignora la prima metà di un documento può far pensare a un modello poco efficace. Nella maggior parte dei casi, la causa è una finestra di contesto troppo piccola.

Verificare la lunghezza del contesto applicata dal server Ollama

Il controllo che funziona su qualsiasi build è prompt_eval_count, cioè il numero di token del prompt che il server dichiara di aver elaborato. Invia un prompt più lungo della capacità del contesto: il numero si arresta in corrispondenza del limite.

sudo apt update && sudo apt install -y jq
LONG=$(python3 -c "print('the quick brown fox jumps over the lazy dog. ' * 2000)")
jq -n --arg p "$LONG" '{model:"llama3.1:8b", prompt:$p, stream:false, options:{num_ctx:4096}}' |
  curl -s http://localhost:11434/api/generate -d @- |
  jq '{prompt_eval_count, prompt_eval_duration}'

Questo prompt contiene circa 18,000 parole, quindi supera ampiamente 4096 token. prompt_eval_count restituisce un valore vicino a 4096 anziché vicino al numero effettivo di token, perché il server ha scartato il resto. Eseguilo di nuovo con "num_ctx":16384: il conteggio aumenta. Se la tua build restituisce un errore invece di troncare il prompt, il risultato indica la stessa condizione, ma in modo più evidente.

ollama ps

La colonna CONTEXT, nelle build che la visualizzano, contiene la lunghezza del contesto con cui il modello caricato è attualmente in esecuzione. La colonna PROCESSOR adiacente indica dove è posizionato il modello. 100% CPU è normale su un VPS senza GPU. Una suddivisione come 30%/70% CPU/GPU su un sistema con GPU indica che i pesi e la cache non entrano più nella VRAM; un valore num_ctx più elevato è la causa abituale.

journalctl -u ollama --no-pager | grep -i n_ctx | tail -n 5

Il runner di inferenza stampa la dimensione del contesto in una riga contenente n_ctx. La formulazione esatta cambia tra le release, quindi considera una riga mancante come un possibile cambio di nome, non come una prova conclusiva.

Quattro punti in cui impostare num_ctx

Nella richiesta. Invia "options": {"num_ctx": 16384} a /api/generate o /api/chat. Questa impostazione ha la precedenza su tutte le altre e si applica solo a quella chiamata. Se il valore è diverso da quello utilizzato dal modello caricato, il server ricarica prima il modello. Questo è visibile in load_duration nella risposta: il valore passa da quasi zero a diversi secondi. Lo stesso tempo di attesa si verifica quando il modello è rimasto inattivo abbastanza a lungo da essere scaricato. Dopo aver scelto la dimensione del contesto, conviene quindi mantenere il modello residente con keep_alive.

Nella sessione interattiva. In ollama run, digita /set parameter num_ctx 16384. L'impostazione resta valida per la sessione corrente.

In un Modelfile. Il valore viene incorporato in un modello con nome. Ogni client lo utilizza senza modifiche lato client.

FROM llama3.1:8b
PARAMETER num_ctx 16384
ollama create llama3.1-16k -f ./Modelfile
ollama run llama3.1-16k

Sul server. OLLAMA_CONTEXT_LENGTH imposta il valore predefinito per ogni richiesta che non contiene un proprio num_ctx. Con systemd, aggiungi un drop-in invece di modificare il file dell'unità.

sudo systemctl edit ollama.service
[Service]
Environment="OLLAMA_CONTEXT_LENGTH=16384"
sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

La precedenza è particolarmente importante quando esegui il debug del client di un altro utente. Una richiesta che contiene num_ctx ha la precedenza sul valore predefinito del server. Di conseguenza, un'interfaccia di chat o un agent che invia autonomamente un valore ridotto può annullare senza segnalarlo la modifica apportata con systemd. Quando configuri un coding agent per usare il tuo server Ollama, controlla quale valore invia il client prima di attribuire il problema al server.

Perché non puoi semplicemente impostare num_ctx sul valore massimo supportato dal modello

L'attenzione fa sì che ogni token consideri tutti i token precedenti. Le chiavi e i valori calcolati per i token precedenti vengono conservati, così non devono essere ricalcolati per ogni nuovo token. Questo archivio è la KV cache (key/value cache). Viene allocato per l'intero num_ctx al caricamento del modello, non man mano che la conversazione cresce. Per questo un contesto ampio consuma memoria anche con un prompt di una sola riga.

Ogni layer conserva un vettore key e un vettore value per ogni testa key/value e per ogni token. Il calcolo può quindi essere espresso in una sola riga:

kv_bytes_per_token = 2 * layers * kv_heads * head_dim * bytes_per_value

Il valore 2 conta separatamente chiavi e valori. Ricava gli altri numeri dal tuo modello.

curl -s http://localhost:11434/api/show -d '{"model":"llama3.1:8b"}' |
  jq '.model_info | {ctx: ."llama.context_length", layers: ."llama.block_count", heads: ."llama.attention.head_count", kv_heads: ."llama.attention.head_count_kv", embed: ."llama.embedding_length"}'

Llama 3.1 8B indica 32 layer e 8 teste key/value. La dimensione della testa è embed diviso heads, quindi in questo caso 4096 / 32 = 128. Alcuni modelli pubblicano direttamente questo valore come llama.attention.key_length. La cache predefinita usa valori f16, quindi bytes_per_value è 2. Il calcolo 2 32 8 128 2 restituisce 131,072 byte. Sono 128 KiB di cache per ogni singolo token del contesto. Moltiplicando per la lunghezza del contesto, il costo diventa concreto.

GraficoLlama 3.1 8B at f16: KV cache and total RAM by context length, in GiB
I dati alla base di questo grafico
[
  {
    "label": "4k",
    "kv_cache_gib": 0.5,
    "total_ram_gib": 5.1
  },
  {
    "label": "8k",
    "kv_cache_gib": 1,
    "total_ram_gib": 5.6
  },
  {
    "label": "16k",
    "kv_cache_gib": 2,
    "total_ram_gib": 6.6
  },
  {
    "label": "32k",
    "kv_cache_gib": 4,
    "total_ram_gib": 8.6
  },
  {
    "label": "64k",
    "kv_cache_gib": 8,
    "total_ram_gib": 12.6
  },
  {
    "label": "128k",
    "kv_cache_gib": 16,
    "total_ram_gib": 20.6
  }
]

Le 6 righe sono il risultato del calcolo della formula precedente, non misurazioni. La colonna del totale aggiunge i 4.9 GB del download indicato dalla libreria Ollama per llama3.1:8b nell'ottobre 2026, pari a 4.6 GiB, ed esclude i buffer di calcolo e il processo server. Consideralo un valore minimo.

Il punto è l'andamento. Con 8k, la cache costa 1 GiB, una quantità trascurabile rispetto ai pesi. Con il contesto completo di 128k, costa 16 GiB, oltre tre volte i pesi, per un totale di circa 20.6 GiB. Di conseguenza, un VPS da 4 GB non può caricare questo modello con un contesto utile. Un VPS da 8 GB è adeguato a 8k. Un VPS da 16 GB può raggiungere 32k lasciando memoria sufficiente per il resto del sistema. Tutte queste soglie aumentano con i pesi. Se stai valutando un modello più grande rispetto a questo 8B, gli stessi calcoli eseguiti per il tag Qwen da 27B su un VPS con sola CPU mostrano quanto poco spazio resti per il contesto tra 8 e 64 GB.

Cosa succede quando la cache KV non entra in memoria

Su una VPS con solo CPU, il processo cresce semplicemente. Monitoralo durante il caricamento del modello e mentre viene elaborata una richiesta lunga.

free -m
ps -eo rss,comm --sort=-rss | head -n 5

RSS (dimensione del set residente) viene mostrato in kilobyte. Se lo swap utilizzato in free -m inizia ad aumentare, riduci il contesto. Una cache KV che risiede nello swap fa rallentare la generazione fino a diversi secondi per token, perché ogni nuovo token legge l'intera cache.

Se la macchina esaurisce completamente la memoria, il kernel sceglie un processo da terminare, di solito quello che utilizza più memoria.

sudo dmesg | grep -i "killed process"

Una riga contenente Out of memory: Killed process 1234 (ollama) indica che Ollama era il processo scelto dal kernel, non necessariamente quello che aveva consumato la memoria. Su una macchina in cui Ollama è l'unico processo di grandi dimensioni, un contesto troppo grande per la memoria disponibile è la causa più probabile. Controlla cos'altro era in esecuzione prima di ridurre num_ctx. Spesso Ollama rifiuta la richiesta prima di arrivare a questo punto; la richiesta quindi fallisce con un messaggio che indica la memoria richiesta e quella libera.

Su una macchina con GPU, l'errore è meno evidente. Alcuni layer vengono spostati nella RAM di sistema, ollama ps mostra la suddivisione tra CPU e GPU e la velocità di elaborazione diminuisce nettamente. L'entità del calo dipende dall'hardware, quindi misura i token al secondo sulla tua macchina per ogni impostazione del contesto, invece di affidarti a un valore ottenuto sulla macchina di qualcun altro.

Il tempo di prefill cresce più rapidamente del prompt

Il prefill è il lavoro eseguito sull'input prima che venga visualizzato il primo token di output. Ogni token del prompt presta attenzione a tutti i token che lo precedono, quindi il lavoro complessivo cresce con il quadrato della lunghezza dell'input. Raddoppiare il prompt fa aumentare il tempo di attesa per il primo token di oltre il doppio.

La risposta contiene la misurazione, quindi non devi accettare questo dato senza verificarlo.

jq -n --arg p "$LONG" '{model:"llama3.1:8b", prompt:$p, stream:false, options:{num_ctx:16384}}' |
  curl -s http://localhost:11434/api/generate -d @- |
  jq '{tokens: .prompt_eval_count, prefill_seconds: (.prompt_eval_duration/1000000000)}'

Esegui la richiesta con un prompt breve e poi ripetila con uno lungo. In entrambi i casi, dividi il numero di token per i secondi impiegati. Su una VPS con sola CPU, il prefill è generalmente la fase più lenta nelle richieste con contesto lungo. Un valore di token al secondo calcolato su un prompt breve non consente di prevederne le prestazioni. Se il prefill supera il timeout configurato nel livello che lo precede, il prompt lungo restituisce in genere scadenza del contesto superata invece di una risposta. Prima di ridurre il contesto, individua quindi quale livello ha interrotto l'operazione.

Il problema è più evidente con la concorrenza. Ogni richiesta gestita richiede una propria cache, quindi la memoria indicata nel grafico precedente è riferita alla singola richiesta, non al server, e una richiesta lunga può occupare tutte le risorse della macchina mentre le richieste brevi restano in coda. Imposta OLLAMA_NUM_PARALLEL deliberatamente e consulta quanti utenti simultanei può gestire un LLM self-hosted prima di aumentare entrambi i valori contemporaneamente.

Recuperare contesto con una cache più piccola

bytes_per_value nella formula è un'impostazione sotto il tuo controllo. Le FAQ di Ollama documentano OLLAMA_KV_CACHE_TYPE, con f16 come valore predefinito, q8_0 con un consumo di memoria pari a circa la metà di f16 e q4_0 con un consumo pari a circa un quarto. Il valore esatto di q8_0 è leggermente superiore alla metà: llama.cpp memorizza ogni blocco di 32 valori come 32 valori da un byte più una scala da due byte, quindi 34 byte, mentre f16 ne richiede 64. Passando a q8_0, la riga da 32k richiede quindi circa 2.1 GiB invece di 4 GiB. La quantizzazione dei pesi libera memoria dall'altro lato dello stesso budget, e il tag GLM che entra effettivamente in una VPS viene analizzato quantizzazione per quantizzazione se preferisci adottare questo compromesso. La stessa FAQ specifica che la cache viene quantizzata solo quando Flash Attention è abilitato e documenta OLLAMA_FLASH_ATTENTION=1 per forzarlo.

[Service]
Environment="OLLAMA_FLASH_ATTENTION=1"
Environment="OLLAMA_KV_CACHE_TYPE=q8_0"

Verifica invece di dare per scontato: riavvia il servizio, carica il modello con lo stesso num_ctx di prima e confronta l'RSS. Il supporto dipende dal modello e dal backend, quindi se un'impostazione non modifica nulla significa che la tua combinazione non è supportata. Il tipo di cache è un'opzione globale, quindi tutti i modelli presenti sul server la utilizzano. Per quanto riguarda la qualità, la FAQ indica che q8_0 di solito non produce effetti percepibili, mentre q4_0 perde più precisione, soprattutto con contesti più ampi; prova quindi q4_0 con i tuoi prompt prima di basarti su questa impostazione. Se stai leggendo questa sezione proprio per questi parametri, Ollama e llama.cpp li espongono in modo diverso.

Una procedura per scegliere num_ctx

  1. Leggi il contesto massimo del modello, il numero di layer e il numero di head key/value da /api/show.
  2. Calcola i byte per token con la formula, quindi moltiplica il risultato per il contesto desiderato.
  3. Aggiungi la dimensione dei pesi, confronta il totale con la RAM libera e lascia almeno 1 GiB per il resto del server.
  4. Imposta il valore, carica il modello e verifica il valore applicato con ollama ps e prompt_eval_count.
  5. Esegui il carico di lavoro reale monitorando free -m e dimezza il contesto se lo swap inizia a essere utilizzato.

La maggior parte dei carichi di lavoro richiede meno contesto di quanto venga assegnato. La sintesi di un report lungo rientra in 16k. Un front end di retrieval che inserisce cinque blocchi di documenti supera raramente 8k. Un agente di coding che legge file interi è il caso che richiede realmente 64k o più. In questo caso devi dimensionare la macchina in base al contesto, non il contrario. Se il server è ancora nuovo, parti da un'installazione funzionante di Ollama su un VPS e ottimizza il contesto dopo aver verificato che i modelli vengano caricati correttamente.

FAQ

Qual è la lunghezza del contesto predefinita in Ollama?

Dipende dalla build e dall’hardware, quindi è preferibile verificare invece di fare supposizioni. Le FAQ di Ollama indicano 4096 token, mentre la documentazione di riferimento di Modelfile indica un valore num_ctx predefinito di 2048. La pagina sulla lunghezza del contesto documenta invece un valore predefinito scelto in base alla VRAM disponibile: 4k sotto 24 GiB, 32k da 24 GiB fino a 48 GiB e 256k da 48 GiB in poi. Una VPS utilizzata soltanto con la CPU si colloca nella fascia più bassa. ollama ps stampa il contesto applicato nelle build che includono la colonna, mentre prompt_eval_count in una risposta API lo conferma in ogni build.

Perché Ollama ignora l'inizio del mio prompt lungo?

Perché il prompt era più lungo della finestra di contesto. Il server lo ha quindi troncato prima che il modello potesse elaborarlo e non ha restituito alcun errore. Invia di nuovo lo stesso prompt con un valore num_ctx maggiore e verifica che prompt_eval_count nella risposta aumenti. Se quel numero non cambia, un componente tra il client e il server sta impostando direttamente num_ctx. Questo comportamento è comune con le interfacce chat e i framework per agenti.

Quanta RAM aggiuntiva richiede un valore num_ctx maggiore?

Moltiplica la lunghezza del contesto per il costo della cache per token, che è 2 * layers * kv_heads * head_dim * bytes_per_value. Per Llama 3.1 8B a f16 il valore è 128 KiB per token. Di conseguenza, 32k token richiedono 4 GiB e 128k token completi richiedono 16 GiB oltre alla memoria occupata dai pesi. La cache viene allocata quando il modello viene caricato, quindi un valore num_ctx elevato consuma quella memoria anche se i prompt restano brevi.

Una finestra di contesto maggiore rende Ollama più lento?

Sì, per due motivi. Il lavoro di prefill cresce con il quadrato della lunghezza del prompt, quindi un input lungo ritarda il primo token più di quanto suggerisca la sua lunghezza. La cache più grande compete inoltre per la memoria: su un server con GPU sposta i layer nella RAM di sistema, mentre su un server con CPU spinge la macchina verso lo swap. Un valore num_ctx elevato che non viene mai utilizzato interamente consuma comunque memoria, anche se non aumenta il tempo di prefill.

Posso impostare num_ctx in modo permanente per un modello?

Sì. Scrivi un Modelfile contenente FROM llama3.1:8b e PARAMETER num_ctx 16384, quindi esegui ollama create llama3.1-16k -f ./Modelfile. Ogni client che richiede llama3.1-16k utilizzerà quel contesto senza inviare opzioni. Una richiesta che contiene un proprio num_ctx ha comunque la precedenza, quindi questa impostazione definisce un valore predefinito, non un limite massimo.

Questo articolo ti è stato utile?