Ollama: configurar num_ctx y evitar recortes de contexto

Qué hace num_ctx y por qué se recortó el prompt largo

La longitud de contexto de Ollama es el número de tokens que un modelo cargado puede mantener en memoria al mismo tiempo, y num_ctx es la opción que la establece. Ollama selecciona un valor predeterminado muy inferior al máximo que anuncia el modelo, por lo que un prompt más largo se recorta antes de que el modelo llegue a leerlo. La respuesta no indica que esto haya ocurrido.

Llama 3.1 8B aparece en la biblioteca de modelos de Ollama con una ventana de contexto de 128k. Un servidor con la configuración predeterminada no le proporcionará ese valor. La documentación de Ollama indica valores predeterminados diferentes según la página: las preguntas frecuentes indican 4096 tokens, la referencia de Modelfile indica que num_ctx tiene un valor predeterminado de 2048, y la página sobre la longitud de contexto indica que el valor predeterminado se selecciona según la VRAM disponible (memoria de vídeo): 4k por debajo de 24 GiB, 32k entre 24 y 48 GiB, y 256k por encima de ese valor. Cada uno de esos valores fue correcto para alguna compilación. Esa discrepancia deja una lección útil: lea el valor en su propio servidor en ejecución en lugar de confiar en cualquier página, incluida esta.

El truncamiento es silencioso porque el modelo sigue respondiendo y la respuesta sigue pareciendo correcta. Se generó a partir del final de la entrada. Un resumen que omite la primera mitad de un documento parece obra de un modelo deficiente. Normalmente se debe a una ventana de contexto pequeña.

Compruebe la longitud de contexto de Ollama que el servidor aplicó realmente

La comprobación que funciona en cualquier compilación es prompt_eval_count, el número de tokens del prompt que el servidor informa haber procesado. Envíe más contenido del que puede admitir el contexto y ese número se detendrá en el límite.

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

Ese prompt contiene unas 18,000 palabras, por lo que supera ampliamente los 4096 tokens. prompt_eval_count devuelve un valor cercano a 4096, no al número real de tokens, porque el servidor descartó el resto. Vuelva a ejecutarlo con "num_ctx":16384 y el número aumentará. Si su compilación devuelve un error en lugar de truncar el contenido, el resultado indica lo mismo, pero de forma más evidente.

ollama ps

La columna CONTEXT, en las compilaciones que la muestran, contiene la longitud de contexto con la que se está ejecutando ahora el modelo cargado. La columna PROCESSOR contigua indica dónde se ejecuta el modelo. 100% CPU es normal en un VPS sin GPU. Una distribución como 30%/70% CPU/GPU en un equipo con GPU indica que los pesos y la caché ya no caben en la VRAM, y un valor elevado de num_ctx suele ser la causa.

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

El ejecutor de inferencia muestra el tamaño del contexto en una línea que contiene n_ctx. El texto exacto cambia entre versiones, así que interprete la ausencia de esa línea como un cambio de nombre, no como una prueba de nada.

Cuatro lugares donde establecer num_ctx

En la solicitud. Envíe "options": {"num_ctx": 16384} a /api/generate o /api/chat. Esta configuración tiene prioridad sobre todas las demás y sólo se aplica a esa llamada. Si el valor difiere del que usa el modelo cargado, el servidor vuelve a cargar primero el modelo. Puede verlo en load_duration en la respuesta: pasa de casi cero a varios segundos. La misma espera aparece cuando el modelo ha permanecido inactivo el tiempo suficiente para descargarse. Por eso, cuando haya decidido el tamaño del contexto, conviene mantener el modelo residente con keep_alive.

En la sesión interactiva. Dentro de ollama run, escriba /set parameter num_ctx 16384. Sólo se mantiene durante esa sesión.

En un Modelfile. Esto incorpora el valor a un modelo con nombre, de modo que todos los clientes lo reciben sin cambios en el cliente.

FROM llama3.1:8b
PARAMETER num_ctx 16384

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

En el servidor. OLLAMA_CONTEXT_LENGTH establece el valor predeterminado para todas las solicitudes que no incluyan su propio num_ctx. Con systemd, añada un drop-in en lugar de editar el archivo de unidad.

sudo systemctl edit ollama.service

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=16384"

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

La prioridad es especialmente importante al depurar el cliente de otra persona. Una solicitud que incluya num_ctx tiene prioridad sobre el valor predeterminado del servidor. Por tanto, un frontend de chat o un agente que envíe su propio valor pequeño puede anular silenciosamente el cambio realizado en systemd. Cuando conecte un agente de programación a su servidor Ollama, compruebe qué envía el cliente antes de atribuir el problema al servidor.

Por qué no puede establecer num_ctx directamente en el máximo del modelo

La atención hace que cada token consulte todos los tokens anteriores. Las claves y los valores calculados para los tokens anteriores se conservan para no recalcularlos con cada token nuevo. Ese almacenamiento es la caché KV (caché de claves y valores). Se reserva para todo num_ctx cuando se carga el modelo, no a medida que crece la conversación. Por eso, un contexto grande consume esa memoria incluso con un prompt de una sola línea.

El tutorial de DigitalOcean sobre el coste de inferencia muestra el cálculo en una sola línea:

kv_bytes_per_token = 2 * layers * kv_heads * head_dim * bytes_per_value

El 2 cuenta las claves y los valores por separado. Obtenga los demás números del propio modelo.

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 indica 32 capas y 8 cabezas de claves/valores. La dimensión de cada cabeza es embed dividida por heads, así que aquí 4096 / 32 = 128. Algunos modelos la publican directamente como llama.attention.key_length. La caché predeterminada almacena valores f16, por lo que bytes_per_value es 2. El cálculo 2 32 8 128 2 da 131,072 bytes. Son 128 KiB de caché por cada token de contexto. Multiplique por la longitud del contexto y el coste deja de ser abstracto.

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

Esas 6 filas son cálculos derivados de la fórmula anterior, no mediciones. La columna total suma los 4.9 GB de descarga que la biblioteca de Ollama indicaba para llama3.1:8b en agosto de 2026, equivalentes a 4.6 GiB, y omite los búferes de cómputo y el propio proceso del servidor. Considérelo un mínimo.

La forma de la curva es lo importante. Con 8k, la caché cuesta 1 GiB, una cantidad insignificante frente a los pesos. Con los 128k completos del modelo, cuesta 16 GiB, más de tres veces los pesos, para un total cercano a 20.6 GiB. Por tanto, un VPS de 4 GB no puede cargar este modelo con un contexto útil. Un VPS de 8 GB funciona con comodidad a 8k. Un VPS de 16 GB alcanza 32k y todavía deja memoria para el resto del sistema. Cada uno de esos límites aumenta con los pesos. Si compara un modelo más grande con este 8B, los mismos cálculos aplicados a la etiqueta de 27B de Qwen en un VPS que sólo usa la CPU muestran cuánto dejan los pesos para el contexto entre 8 y 64 GB.

Qué ocurre cuando la caché KV no cabe

En un VPS que sólo usa CPU, el proceso simplemente crece. Supervíselo mientras se carga el modelo y mientras se ejecuta una solicitud larga.

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

RSS (tamaño del conjunto residente) se muestra en kilobytes. Si el uso de swap en free -m empieza a aumentar, reduzca el contexto. Una caché KV que reside en swap hace que la generación se detenga durante varios segundos por token, porque cada token nuevo lee toda la caché.

Si el sistema se queda completamente sin memoria, el kernel selecciona el proceso más grande y lo termina.

sudo dmesg | grep -i "killed process"

Una línea que muestra Out of memory: Killed process 1234 (ollama) significa que el contexto solicitado no cabía. Ollama suele rechazar la solicitud antes de llegar a ese punto. En ese caso, la solicitud falla con un mensaje que indica la memoria que necesitaba y la memoria que estaba libre.

En un sistema con GPU, el fallo es menos evidente. Algunas capas pasan a la RAM del sistema, ollama ps muestra la distribución entre CPU y GPU y el rendimiento cae bruscamente. La magnitud de la caída depende del hardware. Por eso, mida los tokens por segundo en su propio sistema con cada valor de contexto, en lugar de confiar en una cifra obtenida en el sistema de otra persona.

El tiempo de prellenado aumenta más rápido que el prompt

El prellenado es el trabajo que se realiza con la entrada antes de que aparezca el primer token de salida. Cada token del prompt presta atención a todos los tokens anteriores, por lo que el trabajo total crece con el cuadrado de la longitud de la entrada. Si duplica el prompt, la espera del primer token aumenta más del doble.

La respuesta incluye la medición, por lo que no tiene que aceptarla sin comprobarla.

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

Ejecuta la prueba con un prompt corto y repítela con uno largo. Después, divide los tokens entre los segundos en cada caso. En un VPS que sólo usa CPU, el prellenado suele ser la parte más lenta de una solicitud con mucho contexto. La cifra de tokens por segundo obtenida con un prompt corto no permite predecir su rendimiento.

Si el prellenado supera el tiempo de espera configurado delante del servicio, la solicitud con un prompt largo suele devolver tiempo de espera agotado del contexto en lugar de una respuesta. Antes de reducir el contexto, averigua qué capa agotó el tiempo de espera.

La concurrencia es donde este efecto resulta más importante. Cada solicitud atendida necesita su propia caché, por lo que la memoria del gráfico anterior corresponde a cada solicitud y no al servidor completo. Una solicitud larga puede ocupar el servidor mientras las solicitudes cortas esperan detrás. Establezca OLLAMA_NUM_PARALLEL de forma deliberada y consulte cuántos usuarios simultáneos puede atender un LLM autoalojado antes de aumentar ambos valores a la vez.

Recuperar memoria reduciendo la caché

bytes_per_value en la fórmula es un ajuste que puede controlar. Las preguntas frecuentes de Ollama documentan OLLAMA_KV_CACHE_TYPE, con f16 como valor predeterminado de 2 bytes, además de q8_0 con 1 byte y q4_0 por debajo de ese valor. Cambiar a q8_0 reduce la caché a la mitad, por lo que la fila de 32k cuesta 2 GiB en lugar de 4 GiB. Cuantizar los pesos libera memoria del otro lado del mismo presupuesto, y la etiqueta de GLM que realmente cabe en una VPS se analiza cuantización por cuantización si prefiere aplicar ese intercambio. Las mismas preguntas frecuentes documentan OLLAMA_FLASH_ATTENTION=1, que algunas compilaciones necesitan antes de que una caché cuantizada tenga efecto.

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

Confírmelo en lugar de darlo por supuesto: reinicie el servicio, cargue el modelo con el mismo num_ctx que antes y compare el RSS. La compatibilidad depende del modelo y del backend, por lo que un ajuste que no cambie nada indica que su combinación no está cubierta. La documentación enumera estas opciones sin garantizar un resultado de calidad, así que pruebe q4_0 con sus propios prompts antes de depender de ello. Si estos ajustes son el motivo de su consulta, Ollama y llama.cpp los exponen de forma distinta.

Una receta para elegir num_ctx

1. Lea el contexto máximo del modelo, el número de capas y el número de cabezas key/value desde /api/show.
2. Calcule los bytes por token con la fórmula y multiplíquelos por el contexto que necesita.
3. Sume el tamaño de los pesos, compárelo con la RAM libre y reserve al menos 1 GiB para el resto del sistema.
4. Establezca el valor, cargue el modelo y confirme lo aplicado con ollama ps y prompt_eval_count.
5. Ejecute la carga de trabajo real mientras supervisa free -m y reduzca el contexto a la mitad si el espacio de swap empieza a utilizarse.

La mayoría de los trabajos necesita menos contexto del que se suele asignar. Resumir un informe largo cabe en 16k. Una interfaz de recuperación que inserta cinco fragmentos de documentos rara vez supera 8k. Un agente de programación que lee archivos completos es el caso que realmente necesita 64k o más. También es el caso en el que debe dimensionar la máquina en función del contexto, y no al contrario. Si el servidor todavía es nuevo, empiece por una instalación funcional de Ollama en un VPS y ajuste el contexto cuando los modelos se carguen correctamente.

FAQ

¿Cuál es la longitud de contexto predeterminada en Ollama?

Depende de la compilación y del hardware, así que debe comprobarla en lugar de darla por supuesta. La FAQ de Ollama documenta 4096 tokens, la referencia de Modelfile documenta un valor predeterminado de num_ctx de 2048, y la página sobre la longitud de contexto documenta un valor elegido según la VRAM disponible: 4k por debajo de 24 GiB, 32k entre 24 y 48 GiB y 256k por encima de ese valor. Una VPS que sólo usa CPU queda en el extremo inferior. ollama ps muestra el contexto aplicado en las compilaciones que incluyen esa columna, y prompt_eval_count en una respuesta de la API lo confirma en todas las compilaciones.

¿Por qué Ollama ignora el principio de mi prompt largo?

Porque el prompt superaba la ventana de contexto. El servidor lo recortó antes de que el modelo lo recibiera y no devolvió ningún error. Envíe de nuevo el mismo prompt con un num_ctx mayor y observe cómo aumenta prompt_eval_count en la respuesta. Si ese número no cambia, algo entre el cliente y el servidor está estableciendo num_ctx por su cuenta. Esto es habitual en las interfaces de chat y los frameworks de agentes.

¿Cuánta RAM adicional necesita un num_ctx mayor?

Multiplique la longitud de contexto por el coste de caché por token, que es 2 * layers * kv_heads * head_dim * bytes_per_value. Para Llama 3.1 8B en f16, son 128 KiB por token. Por tanto, 32k tokens consumen 4 GiB y los 128k completos consumen 16 GiB adicionales a los pesos. La caché se asigna cuando se carga el modelo, por lo que un num_ctx grande consume esa memoria aunque los prompts sean cortos.

¿Una ventana de contexto mayor hace que Ollama sea más lento?

Sí, por dos motivos. El trabajo de prellenado aumenta con el cuadrado de la longitud del prompt. Por eso, una entrada larga retrasa el primer token más de lo que su longitud podría indicar. La caché mayor también compite por la memoria: en un equipo con GPU, hace que algunas capas pasen a la RAM del sistema; en un equipo que sólo usa CPU, acerca el sistema al uso de swap. Un num_ctx grande que nunca se llena sigue consumiendo memoria, aunque no aumenta el tiempo de prellenado.

¿Puedo establecer num_ctx de forma permanente para un modelo?

Sí. Escriba un Modelfile que contenga FROM llama3.1:8b y PARAMETER num_ctx 16384 y, después, ejecute ollama create llama3.1-16k -f ./Modelfile. Todos los clientes que soliciten llama3.1-16k obtendrán ese contexto sin enviar ninguna opción. Una solicitud que incluya su propio num_ctx sigue teniendo prioridad, por lo que esto establece un valor predeterminado, no un límite máximo.