Come aumentare num_ctx in Ollama per prompt lunghi

Cosa fa num_ctx e perché il tuo prompt lungo è stato troncato

La lunghezza del contesto in Ollama rappresenta il numero di token che un modello caricato può mantenere in memoria simultaneamente; num_ctx è l'opzione che definisce questo valore. Ollama seleziona un valore predefinito molto inferiore al massimo dichiarato dal modello, pertanto un prompt lungo viene troncato prima ancora che il modello possa leggerlo. Nessun messaggio nella risposta segnala che ciò è avvenuto.

Llama 3.1 8B è elencato nella libreria dei modelli di Ollama con una finestra di contesto da 128k. Un server con configurazione standard non ti fornirà tale valore. La documentazione ufficiale di Ollama riporta valori predefiniti differenti in pagine diverse: le FAQ indicano 4096 token, il riferimento al Modelfile afferma che num_ctx è impostato di default a 2048, mentre la pagina sulla lunghezza del contesto dichiara che il valore predefinito viene scelto in base alla VRAM (video RAM) disponibile: 4k sotto i 24 GiB, 32k tra 24 e 48 GiB, e 256k oltre tale soglia. Ognuna di queste informazioni è stata corretta in determinate versioni. Questa discrepanza è la lezione utile da apprendere: leggi il valore direttamente dal tuo server in esecuzione invece di fidarti di qualsiasi pagina, inclusa questa.

Il troncamento avviene in modo silenzioso perché il modello risponde comunque e la risposta appare coerente. Essa è stata generata a partire dalla parte finale del tuo input. Un riassunto che omette la prima metà di un documento fa sembrare il modello poco capace. Solitamente, la causa è una finestra di contesto troppo ridotta.

Verificare la lunghezza del contesto di Ollama effettivamente applicata dal server

Il controllo che funziona su qualsiasi build è prompt_eval_count, ovvero il conteggio dei token del prompt che il server dichiara di aver elaborato. Inviando una quantità di dati superiore alla capacità del contesto, tale numero si blocca al limite massimo.

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}'

Quel prompt è composto da circa 18.000 parole, quindi ben oltre i 4096 token. prompt_eval_count restituisce un valore vicino a 4096 anziché vicino al conteggio reale dei token, poiché il server ha troncato la parte eccedente. Eseguendo nuovamente il comando con "num_ctx":16384, il conteggio aumenta. Se la build restituisce un errore invece di troncare, il risultato è equivalente, ma con un segnale più evidente.

ollama ps

La colonna CONTEXT, nelle build che la visualizzano, contiene la lunghezza del contesto con cui il modello caricato sta operando in quel momento. La colonna PROCESSOR adiacente mostra dove risiede il modello. 100% CPU è la condizione normale su un VPS privo di GPU. Una suddivisione come 30%/70% CPU/GPU su una macchina dotata di GPU indica che i pesi e la cache non rientrano più nella VRAM; un valore di num_ctx elevato ne è solitamente la causa.

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

Il motore di inferenza stampa la dimensione del contesto in una riga contenente n_ctx. La dicitura esatta varia tra le diverse release, pertanto, in caso di riga mancante, si consideri un cambio di nomenclatura piuttosto che una prova di malfunzionamento.

Quattro posizioni per impostare num_ctx

Nella richiesta. Invia "options": {"num_ctx": 16384} a /api/generate o /api/chat. Questa impostazione prevale su tutte le altre e si applica solo a quella specifica chiamata. Se il valore differisce da quello con cui il modello caricato è in esecuzione, il server ricarica prima il modello; questo è visibile in load_duration nella risposta: il tempo passa da quasi zero a diversi secondi.

Nella sessione interattiva. All'interno di ollama run, digita /set parameter num_ctx 16384. L'impostazione è valida solo per quella sessione.

In un Modelfile. Questo incorpora il valore in un modello denominato, in modo che ogni client lo utilizzi 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 ne contenga uno proprio num_ctx. Con systemd, aggiungi un file di configurazione drop-in invece di modificare il file unit.

sudo systemctl edit ollama.service

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=16384"

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

La precedenza è fondamentale quando si esegue il debug del client di qualcun altro. Una richiesta che contiene num_ctx prevale sul valore predefinito del server; pertanto, un front-end di chat o un agente che invia un proprio valore ridotto annulla silenziosamente la modifica apportata in systemd. Quando configuri un agente di programmazione sul tuo server Ollama, verifica cosa invia il client prima di attribuire la colpa al server.

Perché non è possibile impostare semplicemente num_ctx al massimo del modello

Il meccanismo di attention fa sì che ogni token analizzi tutti i token precedenti. Le chiavi e i valori calcolati per i token iniziali vengono conservati per evitare di ricalcolarli a ogni nuovo token; questo archivio è la KV cache (cache di chiavi/valori). Viene allocata per l'intera estensione di num_ctx al caricamento del modello, non man mano che la conversazione cresce; pertanto, un contesto ampio occupa memoria anche con un prompt di una sola riga.

Il tutorial di DigitalOcean sui costi di inferenza riassume il calcolo in una riga:

kv_bytes_per_token = 2 * layers * kv_heads * head_dim * bytes_per_value

Il valore 2 conteggia separatamente chiavi e valori. I restanti numeri vanno estratti dalle specifiche del proprio 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 dichiara 32 layer e 8 head per chiavi/valori. La dimensione della head è embed diviso per heads, quindi 4096 / 32 = 128 in questo caso; alcuni modelli pubblicano questo dato direttamente come llama.attention.key_length. La cache predefinita memorizza valori f16, quindi bytes_per_value è 2, e il calcolo 2 32 8 128 2 restituisce 131.072 byte. Si tratta di 128 KiB di cache per ogni singolo token di contesto. Moltiplicando per la lunghezza del contesto, il costo smette di essere un concetto astratto.

[
  {
    "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
  }
]

Quelle righe 6 sono il risultato aritmetico della formula sopra, non misurazioni. La colonna del totale somma il download da 4,9 GB indicato dalla libreria Ollama per llama3.1:8b nell'agosto 2026, pari a 4,6 GiB, ed esclude i buffer di calcolo e il processo server stesso. Va considerato come un valore minimo.

La forma è ciò che conta. A 8k, la cache costa 1 GiB, un valore trascurabile rispetto ai pesi. Al massimo contesto del modello di 128k, il costo è di 16 GiB, più di tre volte il peso del modello, per un totale vicino a 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 per 8k. Un VPS da 16 GB raggiunge i 32k lasciando spazio per il resto del sistema. Ognuna di queste soglie si sposta verso l'alto in base ai pesi; se si sta valutando un modello più grande rispetto a questo 8B, gli stessi calcoli eseguiti per il tag Qwen 27B su un VPS solo CPU mostrano quanto poco spazio lascino i pesi per il contesto tra 8 e 64 GB.

Cosa succede quando la KV cache non rientra nella memoria

Su una VPS basata solo su CPU, il processo aumenta semplicemente di dimensioni. Monitoralo mentre il modello viene caricato e durante l'esecuzione di una richiesta lunga.

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

L'RSS (resident set size) è visualizzato in kilobyte. Se lo swap utilizzato in free -m inizia ad aumentare, riduci il contesto. Una KV cache che risiede nello swap causa blocchi nella generazione che durano secondi per ogni token, poiché ogni nuovo token richiede la lettura dell'intera cache.

Se il sistema esaurisce completamente la memoria, il kernel seleziona il processo più grande e lo termina.

sudo dmesg | grep -i "killed process"

Una riga che riporta Out of memory: Killed process 1234 (ollama) indica che il contesto richiesto non è rientrato nella memoria. Spesso Ollama rifiuta la richiesta prima di arrivare a quel punto; in tal caso, la richiesta fallisce con un messaggio che confronta la memoria richiesta con quella disponibile.

Su un sistema con GPU, il fallimento è meno evidente. I layer vengono spostati nella RAM di sistema, ollama ps mostra la suddivisione tra CPU e GPU e il throughput cala drasticamente. L'entità del calo dipende dall'hardware, quindi misura i token al secondo sul tuo sistema per ogni impostazione di contesto, invece di fare affidamento sui dati ottenuti dalla macchina di qualcun altro.

Il tempo di prefill cresce più rapidamente del prompt

Il prefill è il lavoro eseguito sull'input prima che appaia il primo token di output. Ogni token del prompt analizza tutti i token precedenti, quindi il lavoro totale cresce con il quadrato della lunghezza dell'input. Raddoppiare il prompt aumenta più del doppio l'attesa per il primo token.

La risposta contiene la misurazione, quindi non è necessario basarsi su stime.

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)}'

Eseguire il test con un prompt breve e poi con uno lungo, quindi dividere i token per i secondi in entrambi i casi. Su una VPS basata solo su CPU, il prefill è solitamente la parte più lenta di una richiesta con contesto lungo, e un valore di token al secondo ottenuto da un prompt breve non è predittivo.

La concorrenza è l'ambito in cui questo aspetto incide maggiormente. Ogni richiesta servita necessita della propria cache, quindi la memoria nel grafico sopra è per richiesta anziché per server; una singola richiesta lunga può occupare la risorsa mentre quelle brevi rimangono in coda. Impostare OLLAMA_NUM_PARALLEL in modo deliberato e leggere quanti utenti simultanei può servire un LLM self-hosted prima di aumentare entrambi i valori contemporaneamente.

Recuperare contesto con una cache ridotta

bytes_per_value nella formula è un'impostazione che puoi controllare. Le FAQ di Ollama documentano OLLAMA_KV_CACHE_TYPE, con f16 come valore predefinito a 2 byte, oltre a q8_0 a 1 byte e q4_0 per valori inferiori. Passare a q8_0 dimezza la cache, quindi la riga da 32k occupa 2 GiB invece di 4 GiB. Le stesse FAQ documentano OLLAMA_FLASH_ATTENTION=1, che alcune build richiedono prima che una cache quantizzata diventi effettiva.

[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 il valore RSS. Il supporto dipende dal modello e dal backend, quindi se un'impostazione non produce cambiamenti significa che la tua combinazione non è supportata. La documentazione elenca queste opzioni senza garantire un risultato di qualità, quindi testa q4_0 con i tuoi prompt prima di farvi affidamento. Se questi parametri sono il motivo per cui sei qui, Ollama e llama.cpp li espongono in modo differente.

Una ricetta per scegliere num_ctx

1. Leggi il contesto massimo del modello, il numero di layer e il numero di head chiave/valore da /api/show.
2. Calcola i byte per token usando la formula, quindi moltiplicali per il contesto desiderato.
3. Aggiungi la dimensione dei pesi, confrontala con la RAM libera e mantieni almeno 1 GiB di riserva per il resto del sistema.
4. Imposta il valore, carica il modello, quindi conferma quanto applicato con ollama ps e prompt_eval_count.
5. Esegui il carico di lavoro reale monitorando free -m e dimezza il contesto se inizia l'attività di swap.

La maggior parte dei task richiede meno contesto di quanto si pensi. Riassumere un lungo report rientra in 16k. Un front-end di recupero che incolla cinque frammenti di documenti raramente supera gli 8k. Un agente di programmazione che legge interi file è il caso che richiede effettivamente 64k o più, ed è anche il caso in cui dovresti dimensionare la macchina in base al contesto e non viceversa. Se il server è nuovo, parti da un'installazione funzionante di Ollama su una VPS e ottimizza il contesto una volta che i modelli vengono caricati correttamente.

FAQ

Qual è la lunghezza del contesto predefinita in Ollama?

Dipende dalla build e dall'hardware, quindi verifica invece di dare per scontato. Le FAQ di Ollama riportano 4096 token, il riferimento al Modelfile riporta un valore predefinito num_ctx di 2048, e la pagina sulla lunghezza del contesto riporta un valore predefinito scelto in base alla VRAM disponibile: 4k sotto i 24 GiB, 32k tra 24 e 48 GiB, e 256k oltre. Una VPS basata solo su CPU si attesta sul valore inferiore. ollama ps stampa il contesto applicato nelle build che includono la colonna, e prompt_eval_count in una risposta API lo conferma su ogni build.

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

Perché il prompt era più lungo della finestra di contesto, quindi il server lo ha tagliato prima che il modello lo vedesse, senza restituire alcun errore. Invia nuovamente lo stesso prompt con un num_ctx più ampio e osserva il valore di prompt_eval_count crescere nella risposta. Se quel numero non cambia, qualcosa tra te e il server sta impostando num_ctx autonomamente, il che è comune con le interfacce chat e i framework per agenti.

Quanta RAM extra richiede un num_ctx più grande?

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, questo valore è 128 KiB per token, quindi 32k token costano 4 GiB e l'intero 128k costa 16 GiB oltre ai pesi. La cache viene allocata quando il modello viene caricato, quindi un num_ctx elevato occupa quella memoria anche se i tuoi prompt rimangono brevi.

Una finestra di contesto più grande rallenta Ollama?

Sì, in due modi. Il lavoro di prefill cresce con il quadrato della lunghezza del prompt, quindi un input lungo ritarda il primo token più di quanto la sua lunghezza suggerisca. La cache più grande compete inoltre per la memoria: su un server con GPU sposta i layer nella RAM di sistema, e su un server con sola CPU spinge la macchina verso lo swap. Un num_ctx elevato che non riempi mai occupa comunque la memoria, sebbene non influisca sul 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 ottiene quel contesto senza inviare opzioni. Una richiesta che include il proprio num_ctx ha comunque la precedenza, quindi questa procedura imposta un valore predefinito piuttosto che un limite massimo.