Ollama contextlengte aanpassen 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 afgekapt voordat het model deze volledig leest. Er is geen melding in de respons die aangeeft 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 bij minder dan 24 GiB, 32k tussen 24 en 48 GiB, en 256k daarboven. Elk van deze beweringen was op enig moment correct voor een specifieke build. De tegenstrijdigheid is hier de belangrijkste les: lees de waarde af van uw eigen draaiende server in plaats van te vertrouwen op welke pagina dan ook, inclusief deze.

Afkapping gebeurt geruisloos omdat het model nog steeds antwoordt en het antwoord nog steeds goed 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 de oorzaak een te klein contextvenster.

Controleer de Ollama-contextlengte die uw server daadwerkelijk toepast

De controle die op elke build werkt is prompt_eval_count, het aantal prompt-tokens waarvan de server rapporteert dat deze zijn 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 in de buurt van 4096 in plaats van in de buurt van het werkelijke aantal tokens, omdat de server de rest heeft verwijderd. Voer het opnieuw uit met "num_ctx":16384 en het aantal stijgt. Als uw build een foutmelding geeft in plaats van af te kappen, is dat dezelfde bevinding 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 de gebruikelijke 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 iets anders.

Vier locaties om num_ctx in te stellen

In het verzoek. Stuur "options": {"num_ctx": 16384} naar /api/generate of /api/chat. Deze instelling overrulet alle andere 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. Dezelfde wachttijd treedt op wanneer het model lang genoeg inactief is geweest om te worden ontladen. Zodra u een contextgrootte heeft gekozen, is het daarom de moeite waard om het model in het geheugen te houden met keep_alive.

In de interactieve sessie. Typ /set parameter num_ctx 16384 binnen ollama run. Dit is 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 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, overrulet de standaardwaarde van de server. Een chat-interface of een agent die zelf een kleine waarde meestuurt, maakt uw systemd-wijziging dus ongedaan. Wanneer u een programmeer-agent naar uw Ollama-server laat wijzen, 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 berekend hoeven te worden; dit geheugen is de KV cache (key/value cache). Deze wordt bij het laden van het model volledig toegewezen voor de gehele num_ctx, en groeit niet mee met het gesprek. Een grote context vereist dus ook bij een korte prompt al het volledige geheugen.

De tutorial van DigitalOcean over inference-kosten 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 afzonderlijk tellen van keys en values. De overige getallen kunt u afleiden van 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
  }
]

De 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 aangaf, 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. Al deze drempelwaarden schuiven op naarmate de gewichten toenemen; als u een groter model vergelijkt met deze 8B, laten dezelfde berekeningen voor Qwen's 27B-tag op een VPS zonder GPU zien hoe weinig ruimte 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 dit in de gaten terwijl het model laadt en terwijl een lang verzoek wordt uitgevoerd.

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

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 vaak al 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 het falen 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 andermans machine.

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 token dat eraan voorafgaat, 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 dat uit met een korte prompt en nogmaals met een lange prompt. Deel de tokens vervolgens in beide gevallen door het aantal seconden. Op een CPU-only VPS is prefill doorgaans het traagste onderdeel van een verzoek met een lange context. Een waarde voor tokens per seconde die met een korte prompt is gemeten, voorspelt de prestaties daarvan niet. Wanneer prefill langer duurt dan de timeout die ervoor staat, komt een lange prompt meestal terug als contextdeadline overschreden in plaats van als antwoord. Stel daarom eerst vast welke laag de verwerking heeft afgebroken voordat u de context inkort.

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

Geheugenruimte 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 standaardwaarde 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. Het kwantiseren van de gewichten maakt geheugen vrij aan de andere kant van hetzelfde budget, en de GLM-tag die daadwerkelijk op een VPS past wordt per kwantisatie uitgewerkt als dat de afweging is die u liever maakt. 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, dus 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 van uw bezoek, Ollama en llama.cpp stellen deze op verschillende manieren beschikbaar.

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 af via /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 vrije RAM-geheugen en reserveer ten minste 1 GiB voor de rest van het systeem.
4. Stel de waarde in, laad het model en bevestig vervolgens de toegepaste instellingen 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, overschrijdt zelden de 8k. Een coding agent die volledige bestanden leest, is een 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 dus niet uit van aannames, maar controleer het. 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 tussen 24 en 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 bevatten, en prompt_eval_count in een API-respons 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 afgekapt 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 de respons toeneemt. Als dat getal niet verandert, stelt een component tussen u en de server zelf de num_ctx in; dit komt vaak voor bij chat-front-ends en agent-frameworks.

Hoeveel extra RAM heeft een grotere num_ctx nodig?

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.

Maakt een groter contextvenster Ollama trager?

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 bovendien 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 dat er opties hoeven te worden meegestuurd. Een verzoek dat zijn eigen num_ctx bevat, krijgt nog steeds voorrang; dit stelt dus een standaardwaarde in in plaats van een maximum.