Ollama contextlengte verhogen met num_ctx

Wat num_ctx doet en waarom uw lange prompt werd ingekort

De contextlengte van Ollama is het aantal tokens dat een geladen model tegelijkertijd in het geheugen kan vasthouden, en num_ctx is de optie die dit instelt. Ollama kiest een standaardwaarde die ver onder het maximum ligt dat het model zelf aangeeft, waardoor een langere prompt wordt ingekort voordat het model deze überhaupt kan lezen. Niets in de respons geeft aan dat dit is gebeurd.

Llama 3.1 8B staat in de Ollama-modelbibliotheek vermeld met een contextvenster van 128k. Een standaardserver biedt u dat niet. De documentatie van Ollama zelf hanteert verschillende standaardwaarden op verschillende pagina's: de FAQ spreekt van 4096 tokens, de Modelfile-referentie stelt dat num_ctx standaard op 2048 staat, en de pagina over contextlengte vermeldt dat de standaardwaarde wordt gekozen op basis van het beschikbare VRAM (video RAM): 4k onder 24 GiB, 32k tussen 24 en 48 GiB, en 256k daarboven. Elk van deze beweringen was op een bepaald moment correct voor een specifieke build. Die tegenstrijdigheid is de belangrijkste les: lees de waarde af van uw eigen draaiende server in plaats van te vertrouwen op welke pagina dan ook, inclusief deze.

Truncatie verloopt geruisloos omdat het model nog steeds antwoordt en het antwoord nog steeds leesbaar is. Het is geschreven op basis van het laatste deel van uw invoer. Een samenvatting die de eerste helft van een document mist, lijkt op een zwak model. Meestal is een te klein contextvenster de oorzaak.

Controleer de Ollama-contextlengte die uw server daadwerkelijk toepast

De controle die op elke build werkt is prompt_eval_count, het aantal prompt-tokens dat de server volgens eigen opgave heeft verwerkt. Verstuur meer dan de context kan bevatten en dat getal stopt bij de limiet.

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

Die prompt bevat ongeveer 18.000 woorden, dus ruim meer dan 4096 tokens. prompt_eval_count komt terug met een waarde nabij 4096 in plaats van nabij het werkelijke aantal tokens, omdat de server de rest heeft verwijderd. Voer het opnieuw uit met "num_ctx":16384 en het aantal loopt op. Als uw build een foutmelding geeft in plaats van af te kappen, is dat hetzelfde resultaat met een duidelijker signaal.

ollama ps

De kolom CONTEXT, op builds die deze afdrukken, bevat de contextlengte waarmee het geladen model op dit moment draait. De kolom PROCESSOR daarnaast toont waar het model zich bevindt. 100% CPU is normaal op een VPS zonder GPU. Een splitsing zoals 30%/70% CPU/GPU op een systeem met GPU betekent dat de gewichten plus de cache niet langer in het VRAM passen, en een verhoogde num_ctx is daarvoor meestal de reden.

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

De inference runner drukt de contextgrootte af in een regel die n_ctx bevat. De exacte bewoording verandert tussen releases, dus beschouw een ontbrekende regel als een naamswijziging in plaats van als bewijs van wat dan ook.

Vier locaties om num_ctx in te stellen

In het verzoek. Stuur "options": {"num_ctx": 16384} naar /api/generate of /api/chat. Dit overschrijft elke andere instelling en is alleen van toepassing op die specifieke aanroep. Als de waarde afwijkt van de waarde waarmee het geladen model draait, herlaadt de server eerst het model. Dit is zichtbaar in load_duration in het antwoord: de waarde springt van bijna nul naar enkele seconden.

In de interactieve sessie. Typ /set parameter num_ctx 16384 binnen ollama run. Dit blijft geldig voor de duur van die sessie.

In een Modelfile. Hiermee wordt de waarde vastgelegd in een benoemd model, zodat elke client deze gebruikt zonder wijzigingen aan de clientzijde.

FROM llama3.1:8b
PARAMETER num_ctx 16384

ollama create llama3.1-16k -f ./Modelfile
ollama run llama3.1-16k

Op de server. OLLAMA_CONTEXT_LENGTH stelt de standaardwaarde in voor elk verzoek dat niet zijn eigen num_ctx bevat. Voeg onder systemd een drop-in bestand toe in plaats van het unit-bestand te bewerken.

sudo systemctl edit ollama.service

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=16384"

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

De prioriteit is vooral van belang wanneer u de client van iemand anders debugt. Een verzoek dat num_ctx bevat, overschrijft de standaardwaarde van de server. Een chat-frontend of een agent die zelf een kleine waarde meestuurt, maakt uw systemd-wijziging dus ongedaan zonder dat u het merkt. Wanneer u een programmeer-agent naar uw Ollama-server wijst, controleer dan wat de client verstuurt voordat u de server de schuld geeft.

Waarom u num_ctx niet zomaar op het maximum van het model kunt instellen

Bij attention kijkt elk token naar elk voorgaand token. De keys en values die voor eerdere tokens zijn berekend, worden bewaard zodat ze niet voor elk nieuw token opnieuw hoeven te worden berekend; dit geheugen is de KV cache (key/value cache). Deze wordt toegewezen voor de gehele num_ctx zodra het model wordt geladen, en niet naarmate het gesprek groeit. Een grote context kost dus ook geheugen bij een prompt van slechts één regel.

De tutorial over inference-kosten van DigitalOcean vat de berekening in één regel samen:

kv_bytes_per_token = 2 * layers * kv_heads * head_dim * bytes_per_value

De 2 staat voor het apart tellen van keys en values. Lees de overige getallen af bij uw eigen model.

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 rapporteert 32 lagen en 8 key/value heads. De head-dimensie is embed gedeeld door heads, dus 4096 / 32 = 128 in dit geval; sommige modellen publiceren dit direct als llama.attention.key_length. De standaard cache bevat f16-waarden, dus bytes_per_value is 2, en 2 32 8 128 2 resulteert in 131.072 bytes. Dat is 128 KiB aan cache voor elk afzonderlijk context-token. Vermenigvuldig dit met de contextlengte en de kosten worden concreet.

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

Die 6 rijen zijn het resultaat van de bovenstaande formule, geen metingen. De kolom voor het totaal voegt de download van 4,9 GB toe die de Ollama-bibliotheek in augustus 2026 voor llama3.1:8b vermeldde, wat neerkomt op 4,6 GiB, en laat de compute-buffers en het serverproces zelf buiten beschouwing. Beschouw dit als een ondergrens.

De verhouding is hier het punt. Bij 8k kost de cache 1 GiB, wat verwaarloosbaar is ten opzichte van de gewichten. Bij de volledige 128k van het model kost het 16 GiB, meer dan drie keer de gewichten, voor een totaal van bijna 20.6 GiB. Een VPS van 4 GB kan dit model dus niet laden met een bruikbare context. Een VPS van 8 GB is comfortabel bij 8k. Een VPS van 16 GB bereikt 32k met ruimte over voor de rest van het systeem. Elk van deze drempelwaarden stijgt mee met de gewichten; als u dus een groter model vergelijkt met deze 8B, laten dezelfde berekeningen die zijn uitgevoerd voor Qwen's 27B-tag op een VPS zonder GPU zien hoe weinig de gewichten overlaten voor context tussen 8 en 64 GB.

Wat gebeurt er als de KV-cache niet past

Op een VPS die alleen een CPU gebruikt, groeit het proces simpelweg. Houd het proces in de gaten terwijl het model laadt en terwijl een lang verzoek wordt verwerkt.

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

De RSS (resident set size) wordt weergegeven in kilobytes. Als het gebruikte swap-geheugen in free -m begint op te lopen, verklein dan de context. Een KV-cache die in swap staat, zorgt ervoor dat de generatie seconden per token vertraagt, omdat elk nieuw token de volledige cache moet inlezen.

Als de server volledig zonder geheugen komt te zitten, kiest de kernel het grootste proces en beëindigt dit.

sudo dmesg | grep -i "killed process"

Een regel met de tekst Out of memory: Killed process 1234 (ollama) betekent dat de gevraagde context niet paste. Ollama weigert dit vaak voordat het zover komt; het verzoek mislukt dan met een melding waarin het benodigde geheugen wordt afgezet tegen het beschikbare geheugen.

Op een systeem met een GPU verloopt de foutmelding geruislozer. Lagen worden verplaatst naar het systeem-RAM, ollama ps toont de verdeling tussen CPU en GPU, en de doorvoer daalt aanzienlijk. Hoe sterk de daling is, hangt af van uw hardware. Meet daarom zelf het aantal tokens per seconde op uw eigen systeem bij elke contextinstelling in plaats van te vertrouwen op cijfers van de machine van iemand anders.

De prefill-tijd groeit sneller dan de prompt

Prefill is het werk dat wordt verricht aan uw invoer voordat het eerste output-token verschijnt. Elk prompt-token attendeert op elk voorgaand token, waardoor de totale werklast kwadratisch toeneemt met de lengte van de invoer. Het verdubbelen van de prompt zorgt voor meer dan een verdubbeling van de wachttijd voor het eerste token.

De respons bevat de meting, dus u hoeft dit niet zomaar aan te nemen.

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

Voer dit uit met een korte prompt en daarna met een lange, en deel vervolgens in beide gevallen het aantal tokens door het aantal seconden. Op een VPS die alleen op CPU draait, is prefill meestal het traagste onderdeel van een verzoek met een lange context; een cijfer voor tokens per seconde dat is gebaseerd op een korte prompt, zal dit niet voorspellen.

Gelijktijdigheid is waar dit het meest knelt. Elk verzoek dat wordt afgehandeld heeft zijn eigen cache nodig, dus het geheugen in de bovenstaande grafiek is per verzoek in plaats van per server. Eén lang verzoek kan de server bezet houden terwijl korte verzoeken erachter in de wachtrij staan. Stel OLLAMA_NUM_PARALLEL bewust in en lees hoeveel gelijktijdige gebruikers één zelfgehost LLM kan bedienen voordat u beide getallen tegelijk verhoogt.

Context terugwinnen met een kleinere cache

bytes_per_value in de formule is een instelling die u beheert. De FAQ van Ollama documenteert OLLAMA_KV_CACHE_TYPE, waarbij f16 de standaard is op 2 bytes, plus q8_0 op 1 byte en q4_0 daaronder. Overstappen naar q8_0 halveert de cache, waardoor de 32k-rij 2 GiB kost in plaats van 4 GiB. Dezelfde FAQ documenteert OLLAMA_FLASH_ATTENTION=1, wat sommige builds vereisen voordat een gekwantiseerde cache effect sorteert.

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

Bevestig in plaats van aan te nemen: herstart de service, laad het model op dezelfde num_ctx als voorheen en vergelijk de RSS. Ondersteuning hangt af van het model en de backend; een instelling die niets verandert, betekent dat uw combinatie niet wordt ondersteund. De documentatie vermeldt deze opties zonder een kwalitatief resultaat te garanderen, dus test q4_0 met uw eigen prompts voordat u erop vertrouwt. Als deze instellingen de reden zijn dat u hier bent, Ollama en llama.cpp stellen ze verschillend bloot.

Een recept voor het bepalen van num_ctx

1. Lees het maximale contextvenster, het aantal lagen en het aantal key/value-heads van het model uit /api/show.
2. Bereken het aantal bytes per token met de formule en vermenigvuldig dit met de gewenste contextgrootte.
3. Tel de grootte van de gewichten erbij op, vergelijk dit met het beschikbare RAM en houd minimaal 1 GiB vrij voor de rest van het systeem.
4. Stel de waarde in, laad het model en controleer vervolgens wat er is toegepast met ollama ps en prompt_eval_count.
5. Voer uw werkelijke workload uit terwijl u free -m in de gaten houdt; halveer de context als het systeem begint te swappen.

De meeste taken vereisen minder context dan vaak wordt toegewezen. Het samenvatten van een lang rapport past in 16k. Een retrieval-frontend die vijf documentfragmenten plakt, komt zelden boven de 8k uit. Een coding agent die volledige bestanden leest, is het scenario dat daadwerkelijk 64k of meer nodig heeft; in dat geval dient u de machine op basis van de context te dimensioneren in plaats van andersom. Als de server nog nieuw is, begin dan bij een werkende Ollama-installatie op een VPS en stem de context af zodra de modellen correct laden.

FAQ

Wat is de standaard contextlengte in Ollama?

Dit hangt af van de build en de hardware; ga niet uit van aannames, maar controleer dit. De FAQ van Ollama vermeldt 4096 tokens, de Modelfile-referentie documenteert een num_ctx standaard van 2048, en de pagina over contextlengte documenteert een standaardwaarde die wordt gekozen op basis van het beschikbare VRAM: 4k bij minder dan 24 GiB, 32k bij 24 tot 48 GiB, en 256k daarboven. Een VPS die alleen op CPU draait, valt in de onderste categorie. ollama ps toont de toegepaste context bij builds die deze kolom ondersteunen, en prompt_eval_count in een API-antwoord bevestigt dit bij elke build.

Waarom negeert Ollama het begin van mijn lange prompt?

Omdat de prompt langer was dan het contextvenster, heeft de server deze ingekort voordat het model de tekst kon verwerken, zonder dat er een foutmelding werd geretourneerd. Verstuur dezelfde prompt opnieuw met een grotere num_ctx en zie hoe prompt_eval_count in het antwoord toeneemt. Als dit getal niet verandert, wordt num_ctx door een tussenliggende laag overschreven; dit komt vaak voor bij chat-frontends en agent-frameworks.

Hoeveel extra RAM vereist een grotere num_ctx?

Vermenigvuldig de contextlengte met de cachekosten per token, wat 2 * layers * kv_heads * head_dim * bytes_per_value is. Voor Llama 3.1 8B op f16 is dat 128 KiB per token, dus 32k tokens kost 4 GiB en de volledige 128k kost 16 GiB bovenop de gewichten. De cache wordt toegewezen wanneer het model wordt geladen, dus een grote num_ctx kost dat geheugen, zelfs als uw prompts kort blijven.

Wordt Ollama trager door een groter contextvenster?

Ja, op twee manieren. De prefill-tijd groeit kwadratisch met de lengte van de prompt, waardoor een lange invoer de eerste token meer vertraagt dan de lengte doet vermoeden. De grotere cache concurreert ook om geheugen: op een GPU-systeem dwingt dit lagen naar het systeem-RAM, en op een CPU-systeem dwingt dit de machine richting swap. Een grote num_ctx die u nooit volledig benut, kost nog steeds het geheugen, hoewel het geen invloed heeft op de prefill-tijd.

Kan ik num_ctx permanent instellen voor één model?

Ja. Schrijf een Modelfile met daarin FROM llama3.1:8b en PARAMETER num_ctx 16384, en voer vervolgens ollama create llama3.1-16k -f ./Modelfile uit. Elke client die om llama3.1-16k vraagt, krijgt die context zonder zelf opties te hoeven sturen. Een verzoek dat zijn eigen num_ctx bevat, krijgt nog steeds voorrang; dit stelt dus een standaardwaarde in in plaats van een maximum.