Ollama: як налаштувати num_ctx і довжину контексту
Ollama може обрізати довгі prompt через мале num_ctx. Дізнайтеся, як задати параметр для запиту чи сервера та оцінити RAM для KV cache.
Що робить num_ctx і чому довгий prompt було обрізано
Довжина контексту Ollama — це кількість токенів, які завантажена модель може одночасно зберігати в пам’яті, а num_ctx — параметр, що її визначає. Ollama вибирає значення за замовчуванням, яке значно менше за максимальне значення, заявлене для моделі, тому довший prompt обрізається ще до того, як модель його прочитає. У відповіді немає жодної ознаки, що це сталося.
Для Llama 3.1 8B у бібліотеці моделей Ollama указано контекстне вікно 128k. Стандартний сервер не надає такого значення. У власній документації Ollama на різних сторінках указано різні значення за замовчуванням: у FAQ — 4096 токенів, у довідці Modelfile зазначено, що num_ctx за замовчуванням дорівнює 2048, а на сторінці про довжину контексту сказано, що значення за замовчуванням залежить від доступної VRAM (відеопам’яті): 4k для обсягу менше ніж 24 GiB, 32k для обсягу від 24 GiB до 48 GiB і 256k для обсягу 48 GiB або більше. Кожне з цих значень відповідало певній збірці. Практичний висновок такий: перевіряйте значення на власному запущеному сервері, а не довіряйте будь-якій сторінці, зокрема цій.
Обрізання відбувається непомітно, оскільки модель усе одно відповідає, а відповідь може виглядати переконливо. Її створено на основі кінцевої частини вашого введення. Резюме, у якому пропущено першу половину документа, може виглядати як результат роботи слабкої моделі. Зазвичай причина — замале контекстне вікно.
Перевірте фактичну довжину контексту Ollama, яку застосував сервер
Перевірка, що працює в будь-якій збірці, — це prompt_eval_count, тобто кількість токенів промпту, оброблених сервером. Надішліть більше токенів, ніж може вмістити контекст, і це число зупиниться на граничному значенні.
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}'Цей промпт містить приблизно 18,000 слів, тобто значно більше за 4096 токенів. prompt_eval_count повертає значення близько 4096, а не фактичну кількість токенів, оскільки сервер відкинув решту. Запустіть команду ще раз із "num_ctx":16384 — кількість зросте. Якщо ваша збірка повертає помилку замість обрізання, це той самий результат, але з чіткішим сигналом.
ollama psУ збірках, де цей стовпець виводиться, стовпець CONTEXT містить довжину контексту, з якою завантажена модель працює зараз. Сусідній стовпець PROCESSOR показує, де розміщена модель. 100% CPU — нормальне значення для VPS без GPU. Розподіл на кшталт 30%/70% CPU/GPU на сервері з GPU означає, що ваги моделі разом із кешем більше не вміщуються у VRAM. Зазвичай причиною є збільшене значення num_ctx.
journalctl -u ollama --no-pager | grep -i n_ctx | tail -n 5Inference runner виводить розмір контексту в рядку, що містить n_ctx. Точне формулювання змінюється між релізами, тому відсутній рядок слід сприймати як перейменування, а не як доказ будь-якого факту.
Чотири місця для налаштування num_ctx
У запиті. Передайте "options": {"num_ctx": 16384} до /api/generate або /api/chat. Це налаштування має найвищий пріоритет і діє лише для цього запиту. Якщо значення відрізняється від того, з яким запущена завантажена модель, сервер спочатку повторно завантажує модель. Це видно за load_duration у відповіді: значення зростає майже з нуля до кількох повних секунд. Така сама затримка виникає, коли модель достатньо довго простоює і вивантажується. Тому після вибору розміру контексту варто залишати модель завантаженою за допомогою keep_alive.
В інтерактивному сеансі. У ollama run введіть /set parameter num_ctx 16384. Це налаштування діє протягом поточного сеансу.
У Modelfile. Так значення вбудовується в іменовану модель, і кожен клієнт отримує його без змін на стороні клієнта.
FROM llama3.1:8b
PARAMETER num_ctx 16384ollama create llama3.1-16k -f ./Modelfile
ollama run llama3.1-16kНа сервері. OLLAMA_CONTEXT_LENGTH задає значення за замовчуванням для кожного запиту, який не містить власного num_ctx. У systemd додайте drop-in, а не редагуйте файл unit.
sudo systemctl edit ollama.service[Service]
Environment="OLLAMA_CONTEXT_LENGTH=16384"sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama psПріоритет налаштувань особливо важливий під час налагодження чужого клієнта. Запит із num_ctx має вищий пріоритет за значення сервера за замовчуванням. Тому chat front end або агент, який сам надсилає невелике значення, непомітно скасовує вашу зміну в systemd. Коли ви підключаєте coding agent до свого Ollama server, перевірте, що саме надсилає клієнт, перш ніж звинувачувати сервер.
Чому не можна просто встановити num_ctx на максимальне значення моделі
Механізм attention змушує кожен токен переглядати всі попередні токени. Обчислені для попередніх токенів keys і values зберігаються, щоб не обчислювати їх заново для кожного нового токена. Це сховище називається KV cache (key/value cache). Воно виділяється для всього num_ctx під час завантаження моделі, а не в міру зростання діалогу. Тому великий контекст споживає пам’ять навіть для однорядкового запиту.
Кожен layer зберігає один key vector і один value vector для кожної key/value head і кожного токена. Розрахунок можна записати одним рядком:
kv_bytes_per_token = 2 * layers * kv_heads * head_dim * bytes_per_valueЧисло 2 враховує keys і values окремо. Інші значення візьміть із власної моделі.
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 використовує 32 layers і 8 key/value heads. Розмір head дорівнює embed, поділеному на heads, тобто тут 4096 / 32 = 128. Деякі моделі безпосередньо публікують це значення як llama.attention.key_length. Типове cache зберігає значення у форматі f16, тому bytes_per_value дорівнює 2. Розрахунок 2 32 8 128 2 дає 131,072 bytes. Отже, кожен токен контексту потребує 128 KiB cache. Помножте це значення на довжину контексту, і витрати перестануть бути абстрактними.
Дані, на яких побудовано графік
[
{
"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
}
]Ці 6 rows обчислено за наведеною вище формулою, а не виміряно. У стовпці total додано завантаження розміром 4.9 GB, яке бібліотека Ollama вказувала для llama3.1:8b у жовтні 2026 року. Це 4.6 GiB. Буфери обчислень і сам server process не враховано. Вважайте це мінімальною оцінкою.
Важливий саме масштаб змін. За 8k cache потребує 1 GiB, що мало порівняно з вагами. За повного контексту 128k він потребує 16 GiB — це більш ніж утричі перевищує обсяг ваг. Загальний обсяг становить приблизно 20.6 GiB. Тому VPS із 4 GB не зможе завантажити цю модель із практично придатним контекстом. VPS із 8 GB комфортно працює з 8k. VPS із 16 GB досягає 32k і залишає пам’ять для інших компонентів системи. Зі збільшенням ваг кожен із цих порогів також зростає. Якщо ви порівнюєте більшу модель із цією 8B, ті самі розрахунки для тега Qwen 27B на VPS лише з CPU показують, як мало пам’яті залишається для контексту в діапазоні від 8 до 64 GB.
Що відбувається, коли KV cache не вміщується
На VPS лише з CPU процес просто споживає дедалі більше пам’яті. Спостерігайте за ним під час завантаження моделі та виконання довгого запиту.
free -m
ps -eo rss,comm --sort=-rss | head -n 5RSS (resident set size) виводиться в кілобайтах. Якщо використання swap у free -m починає зростати, зменште context. KV cache, що зберігається у swap, спричиняє затримку генерації на кілька секунд для кожного токена, оскільки кожен новий токен читає весь cache.
Якщо на сервері повністю закінчується пам’ять, kernel вибирає процес для завершення, зазвичай той, що використовує найбільше пам’яті.
sudo dmesg | grep -i "killed process"Рядок із Out of memory: Killed process 1234 (ollama) означає, що Ollama був процесом, який вибрав kernel, а не обов’язково процесом, що використав усю пам’ять. Якщо Ollama — єдиний великий процес на сервері, найімовірнішою причиною є надто великий context. Перевірте, що ще працювало, перш ніж зменшувати num_ctx. Ollama часто відмовляється ще до цього етапу, і тоді запит завершується помилкою, у якій зазначено обсяг пам’яті, потрібний процесу, і обсяг вільної пам’яті.
На сервері з GPU помилка менш очевидна. Частина layers переміщується в системну RAM, ollama ps показує розподіл між CPU та GPU, а throughput різко зменшується. Наскільки саме — залежить від вашого обладнання, тому вимірюйте кількість токенів за секунду на власному сервері для кожного значення context, а не покладайтеся на показник із чужої системи.
Підготовка prompt зростає швидше, ніж сам prompt
Prefill — це обробка вашого вводу до появи першого токена відповіді. Кожен токен prompt обробляється з урахуванням усіх попередніх токенів, тому загальний обсяг роботи зростає пропорційно квадрату довжини вводу. Якщо подвоїти prompt, час очікування першого токена зросте більш ніж удвічі.
Відповідь містить вимірювання, тому вам не потрібно приймати це без перевірки.
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)}'Запустіть це з коротким і довгим промптом, а потім у кожному випадку поділіть кількість токенів на кількість секунд. На VPS лише з CPU prefill зазвичай є найповільнішою частиною запиту з довгим контекстом, тому показник токенів за секунду, отриманий для короткого промпту, не прогнозує час його обробки. Якщо prefill триває довше, ніж дозволяє встановлений перед ним timeout, довгий промпт зазвичай завершується повідомленням перевищено граничний час контексту, а не відповіддю. Тому спочатку з’ясуйте, який саме рівень перервав операцію, і лише потім скорочуйте контекст.
Найбільше це впливає на одночасну обробку запитів. Кожен запит, який обслуговується, потребує власного кешу. Тому обсяг пам’яті на наведеній вище діаграмі вказано для одного запиту, а не для всього сервера. Один довгий запит може зайняти весь сервер, поки короткі запити стоятимуть у черзі. Установлюйте OLLAMA_NUM_PARALLEL обдумано та перегляньте скільки одночасних користувачів може обслуговувати self-hosted LLM, перш ніж одночасно збільшувати обидва значення.
Поверніть пам’ять, зменшивши cache
bytes_per_value у формулі — це параметр, яким ви керуєте. У FAQ Ollama описано OLLAMA_KV_CACHE_TYPE, де f16 є значенням за замовчуванням, q8_0 використовує приблизно вдвічі менше пам’яті, ніж f16, а q4_0 — приблизно вчетверо менше. Точне значення для q8_0 трохи перевищує половину: llama.cpp зберігає кожен блок із 32 значень як 32 однобайтові значення та двобайтовий scale, тобто 34 байти замість 64 для f16. Тому перехід на q8_0 зменшує обсяг для рядка 32k приблизно до 2.1 GiB замість 4 GiB. Квантування ваг вивільняє пам’ять з іншого боку того самого бюджету, а тег GLM, який справді вміщується у VPS розглянуто з варіантами квантування, якщо ви віддаєте перевагу саме такому компромісу. У тій самій FAQ зазначено, що cache квантується лише за ввімкненого Flash Attention, а OLLAMA_FLASH_ATTENTION=1 дає змогу примусово ввімкнути його.
[Service]
Environment="OLLAMA_FLASH_ATTENTION=1"
Environment="OLLAMA_KV_CACHE_TYPE=q8_0"Не припускайте, а перевірте: перезапустіть сервіс, завантажте модель із тим самим num_ctx, що й раніше, і порівняйте RSS. Підтримка залежить від моделі та backend, тому параметр, який нічого не змінює, означає, що ваша комбінація не підтримується. Тип cache є глобальним параметром, тому всі моделі на сервері працюватимуть із ним. Щодо якості, у FAQ зазначено, що q8_0 зазвичай не має помітного впливу, тоді як q4_0 втрачає більше точності, особливо за більших розмірів context, тому перевірте q4_0 на власних запитах, перш ніж покладатися на нього. Якщо ви використовуєте ці параметри для розв’язання проблеми, Ollama та llama.cpp надають до них різний доступ.
Рекомендації щодо вибору num_ctx
- Зчитайте максимальний контекст моделі, кількість її шарів і кількість голів key/value з
/api/show. - Обчисліть кількість байтів на токен за формулою, а потім помножте її на потрібний розмір контексту.
- Додайте розмір ваг, порівняйте результат із вільною RAM і залиште щонайменше 1 GiB для інших процесів сервера.
- Установіть значення, завантажте модель, а потім перевірте застосовані параметри за допомогою
ollama psіprompt_eval_count. - Запустіть реальне робоче навантаження, стежачи за
free -m, і зменште контекст удвічі, якщо swap почне використовуватися.
Для більшості завдань потрібен менший контекст, ніж зазвичай указують. Резюме довгого звіту вміщується в 16k. Front end для retrieval, який додає п’ять фрагментів документів, рідко перевищує 8k. Coding agent, який читає цілі файли, є випадком, коли справді потрібен контекст 64k або більше. У такому разі машину слід підбирати за розміром контексту, а не навпаки. Якщо сервер ще не налаштований, почніть із робочої інсталяції Ollama на VPS і налаштуйте контекст після того, як моделі почнуть завантажуватися без помилок.
FAQ
Яка довжина контексту встановлена в Ollama за замовчуванням?
Це залежить від збірки та апаратного забезпечення, тому перевірте значення, а не покладайтеся на припущення. У FAQ Ollama зазначено 4096 токенів, у довіднику Modelfile — значення num_ctx за замовчуванням, що дорівнює 2048, а на сторінці про довжину контексту описано значення за замовчуванням, вибране залежно від доступної VRAM: 4k для обсягу менше 24 GiB, 32k для обсягу від 24 GiB до 48 GiB і 256k для обсягу 48 GiB або більше. VPS лише з CPU використовує нижнє значення цього діапазону. ollama ps виводить застосовану довжину контексту в збірках, де є відповідний стовпець, а prompt_eval_count у відповіді API підтверджує її в кожній збірці.
Чому Ollama ігнорує початок мого довгого промпту?
Тому що промпт був довшим за вікно контексту. Сервер обрізав його до того, як модель його отримала, і не повернув помилку. Надішліть той самий промпт ще раз із більшим значенням num_ctx і простежте, як у відповіді збільшується prompt_eval_count. Якщо це число не змінюється, щось між вами та сервером самостійно встановлює num_ctx. Це часто трапляється з chat front end і agent framework.
Скільки додаткової RAM потребує більший num_ctx?
Помножте довжину контексту на вартість кешу на токен, яка дорівнює 2 * layers * kv_heads * head_dim * bytes_per_value. Для Llama 3.1 8B у f16 це 128 KiB на токен, тому 32k токенів потребують 4 GiB, а повні 128k — 16 GiB додатково до пам’яті під ваги. Кеш виділяється під час завантаження моделі, тому велике значення num_ctx потребує цього обсягу пам’яті, навіть якщо ваші промпти залишаються короткими.
Чи робить більше вікно контексту Ollama повільнішою?
Так, з двох причин. Обсяг роботи під час prefill зростає пропорційно квадрату довжини промпту, тому довгий вхід затримує появу першого токена сильніше, ніж можна припустити лише за його довжиною. Більший кеш також конкурує за пам’ять: на сервері з GPU він переміщує шари до системної RAM, а на сервері лише з CPU наближає систему до використання swap. Велике значення num_ctx, яке ви ніколи не заповнюєте, усе одно потребує пам’яті, хоча й не збільшує час prefill.
Чи можна постійно встановити num_ctx для однієї моделі?
Так. Створіть Modelfile, що містить FROM llama3.1:8b і PARAMETER num_ctx 16384, а потім виконайте ollama create llama3.1-16k -f ./Modelfile. Кожен клієнт, який запитує llama3.1-16k, отримує цей контекст без передавання додаткових options. Запит із власним значенням num_ctx має вищий пріоритет, тому це встановлює значення за замовчуванням, а не верхню межу.