AI Atlas
Orta · ~2 dk okuma #num_ctx #context-length #inference

num_ctx

Context length runtime parametresi

Local inference motorlarında (Ollama, llama.cpp) modelin hafızasında tutacağı maksimum bağlam token sayısını ayarlayan parametre.

AYIRDIĞIN BAĞLAM = AYIRDIĞIN VRAMLlama 3.1 8B · KV cache büyüklüğünum_ctx=2K0.27 GBnum_ctx=8K1.05 GBnum_ctx=32K4.20 GBnum_ctx=128K16.80 GBOllama default 2048 — uzun belge için açıkça artır
Tanım

context-window modelin teorik kapasitesi (örn. Llama 3.1 8B = 128K). num_ctx ise runtime'da gerçekten ayırdığın bellek miktarı. Motorlar bunu çoğu zaman modelin tavanının altında tutar, çünkü context büyüdükçe VRAM doğrusal artar.

Hesap: KV cache ≈ 2 (K+V) × num_layers × num_kv_heads × head_dim × bytes × num_ctx. Llama 3.1 8B'de (32 katman, 8 KV head, 128 head_dim, f16) num_ctx başına ~131 KB. 8K context → ~1 GB VRAM. 32K → ~4 GB. 128K → ~16 GB sırf KV cache için — ağırlıklara ek.

Provider farkları (Ekim 2026 itibarıyla):

  • Ollama: OLLAMA_CONTEXT_LENGTH=8192 env veya Modelfile'da PARAMETER num_ctx 8192. Default VRAM'e göre seçilir: 24 GiB altı → 4096, 24–48 GiB → 32768, 48 GiB ve üstü → 262144. İstenen değer modelin eğitim bağlamını aşarsa Ollama onu o tavana indirir.
  • llama.cpp: -c / --ctx-size. Default 0 = modelin eğitildiği bağlam. Varsayılan açık olan --fit belleğe sığmazsa bu değeri --fit-ctx sınırına (default 4096) kadar düşürebilir.
  • vLLM: --max-model-len 8192. Verilmezse modelin config'inden türetilir.
  • OpenAI/Anthropic: yok — API kendisi yönetir.
Benzetme

Bir defterin sayfa sayısını ayarlamak. Modelin "hatırlama kapasitesi" sınırlı — kaç sayfa açacaksan ona göre yer ayırırsın. 4 sayfa açarsan (num_ctx=4096) hızlı ama unutkan. 100 sayfa (128K) açarsan masada çok yer kaplar (VRAM) ama uzun konuşmalarda hatırlar.

Gerçek dünyadan örnek

16 GB'lık bir Mac'te Ollama ile Llama 3.1 8B'i sohbet için kullanıyorsun:

`` ollama run llama3.1:8b > Sana 50K token belge yapıştırıyorum... > [model belgenin sadece son ~4K token'ını "görüyor"] ``

Sebep: 24 GiB'in altındaki makinelerde num_ctx default 4096. Ollama sığmayan prompt'u baştan kırpar; belgenin başı göz ardı edilir.

Çözüm: OLLAMA_CONTEXT_LENGTH=32768 ollama serve ile başlat. Veya Modelfile: `` FROM llama3.1:8b PARAMETER num_ctx 32768 ` Şimdi 50K belgenin son ~32K'sı alınır, baştaki ~18K yine düşer. Gerçekte ayrılan değeri ollama ps çıktısındaki CONTEXT` sütununda görürsün.

VRAM tüketimi (yaklaşık): num_ctx=4096 → ~5-6 GB toplam (8B Q4 + cache). num_ctx=32768 → ~9 GB. 16 GB Mac'te rahat çalışır.

Ne zaman kullan
  • RAG ya da uzun belge analizi — 4K default kesinlikle yetmez
  • Çok turlu sohbet — geçmişi tutmak için 8K+ şart
  • Kod düzenleme ve agent görevleri — Ollama dokümanı en az 64000 token öneriyor
  • VRAM bütçen müsaitse — 'olur ya' diye 32K-128K aç
Ne zaman kullanma
  • Tek seferlik kısa sorular — 2K-4K yeter, VRAM tasarruf
  • VRAM kıt (8 GB Mac) ve büyük model (13B+) — düşük num_ctx + büyük model dengesi
  • Modelin desteklemediği değer — Llama 3.1 max 128K; Ollama daha büyüğünü uyarıyla 128K'ya indirir
Sık yapılan hatalar

Düşük default sürprizi

Llama 3.1 'destek 128K' der ama 24 GiB'in altındaki makinede Ollama default 4096! Uzun bağlam istiyorsan açıkça ayarla. Not: Ollama'nın Modelfile sayfası hâlâ 2048, FAQ'su 4096 yazıyor; güncel davranış VRAM'e göre kademeli.

VRAM hesabını yapmamak

num_ctx=128K, 8B Q4 model, 16 GB Mac → patlar. Önce VRAM hesabı: model + (num_layers × kv_heads × head_dim × 4 × num_ctx). Ağırlık quantization'ı (Q4) cache'i küçültmez; cache'i ayrıca quantize etmek gerekir (OLLAMA_KV_CACHE_TYPE=q8_0 ya da llama.cpp'de -ctk/-ctv), bkz. Flash Attention.

Modelin gerçek tavanını aşmak

'128K destekli' demek 128K token verince anlam kaybetmeden ürettiği anlamına gelmez. Lost-in-the-middle real. 32K'da kal, RAG ile pencere yöneterek daha iyi sonuç al.