Ollama: cómo configurar num_ctx y evitar prompts cortados

Qué hace num_ctx y por qué se cortó 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 corta antes de que el modelo llegue a leerlo. La respuesta no indica que esto haya ocurrido.

Llama 3.1 8B aparece con una ventana de contexto de 128k en la biblioteca de modelos de Ollama. Un servidor con la configuración predeterminada no le proporcionará ese valor. La documentación de Ollama muestra valores predeterminados distintos en páginas diferentes: las FAQ 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 elige según la VRAM disponible: 4k por debajo de 24 GiB, 32k entre 24 y 48 GiB y 256k por encima de ese valor. Cada cifra fue válida para alguna compilación. Esa discrepancia deja una lección útil: lea el valor del servidor que está ejecutando, en lugar de confiar en cualquier página, incluida esta.

El truncamiento pasa desapercibido porque el modelo sigue respondiendo y la respuesta sigue pareciendo correcta. El modelo la generó usando la parte final de la entrada. Un resumen que omite la primera mitad de un documento parece indicar que el modelo es deficiente. Normalmente se debe a una ventana de contexto pequeña.

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

La comprobación que funciona en cualquier compilación es prompt_eval_count, el recuento de tokens del prompt que el servidor indica que procesó. Envíe más contenido del que cabe en 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 tiene unos 18,000 términos, es decir, muchos más de 4096 tokens. prompt_eval_count devuelve un valor cercano a 4096, no al recuento real de tokens, porque el servidor descartó el resto. Ejecútelo de nuevo con "num_ctx":16384 y el recuento aumentará. Si su compilación devuelve un error en lugar de truncar el contenido, el resultado es el mismo, pero la señal es más clara.

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, situada junto a ella, indica dónde se ejecuta el modelo. 100% CPU es normal en un VPS sin GPU. Una divisió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 aumentado 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 se aplica sólo 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.

En la sesión interactiva. Dentro de ollama run, escriba /set parameter num_ctx 16384. 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 precedencia 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 eso, un frontend de chat o un agente que envía su propio valor pequeño puede anular silenciosamente el cambio de systemd. Cuando conecte un agente de programación a su servidor Ollama, compruebe qué envía el cliente antes de culpar al servidor.

Por qué no puede establecer num_ctx simplemente 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 asigna 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 presenta 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 de su 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 cabezales de claves/valores. La dimensión del cabezal es embed dividida entre heads, por lo 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, y 2 32 8 128 2 da 131,072 bytes. Eso equivale a 128 KiB de caché por cada token del 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 basados en la fórmula anterior, no mediciones. La columna total suma la descarga de 4.9 GB que la biblioteca de Ollama indicaba para llama3.1:8b en agosto de 2026, equivalente a 4.6 GiB, y no incluye los búferes de cómputo ni el propio proceso del servidor. Considérelo un valor 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. Todos esos límites aumentan con el tamaño de los pesos. Si compara un modelo mayor con este modelo 8B, los mismos cálculos aplicados a la etiqueta 27B de Qwen en un VPS que sólo usa CPU muestran cuánto margen dejan los pesos para el contexto entre 8 y 64 GB.

Qué ocurre cuando la caché KV no cabe

En una VPS que sólo usa CPU, el proceso 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 almacenada 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 cabe. Ollama suele rechazar la solicitud antes de llegar a ese punto. Entonces la solicitud falla con un mensaje que indica la memoria necesaria y la memoria disponible.

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 disminuye considerablemente. La magnitud depende del hardware. Por eso, mida los tokens por segundo en su propio sistema con cada configuración de contexto, en lugar de confiar en una cifra obtenida en el equipo de otra persona.

El tiempo de prellenado crece 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 atiende 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, el tiempo de espera hasta el 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)}'

Ejecute esto con un prompt corto y vuelva a ejecutarlo con uno largo. Después, divida 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 un contexto largo. Una cifra de tokens por segundo obtenida con un prompt corto no permite predecir su rendimiento.

La concurrencia es donde este problema 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. Configure 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.

Recupere contexto con una caché más pequeña

bytes_per_value en la fórmula es un ajuste que puede controlar. La FAQ de Ollama documenta 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. La misma FAQ documenta OLLAMA_FLASH_ATTENTION=1, que algunas compilaciones requieren para que se aplique una caché cuantizada.

[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 de 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; pruebe q4_0 con sus propias solicitudes antes de basarse en ello. Si estos ajustes son el motivo de su consulta, Ollama y llama.cpp los exponen de forma diferente.

Una receta para elegir num_ctx

1. Consulte en /api/show el contexto máximo del modelo, el número de capas y el número de cabezas de clave/valor.
2. Calcule los bytes por token con la fórmula y multiplíquelos por el contexto que desea.
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 qué se aplicó 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 uso de swap empieza a aumentar.

La mayoría de los trabajos necesitan menos contexto del que se les asigna. Resumir un informe largo cabe en 16k. Un frontend 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 según el contexto, y no al revés. 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. Las preguntas frecuentes de Ollama documentan 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 predeterminado elegido según la VRAM disponible: 4k por debajo de 24 GiB, 32k entre 24 y 48 GiB, y 256k por encima. 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. Vuelva a enviar 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 usted y el servidor está estableciendo num_ctx por su cuenta. Esto es habitual con 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 la 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, así que un num_ctx grande consume esa memoria aunque sus prompts sigan siendo cortos.

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

Sí, de dos formas. El trabajo de prellenado crece con el cuadrado de la longitud del prompt, por lo que una entrada larga retrasa el primer token más de lo que su longitud podría sugerir. Además, la caché mayor compite por la memoria: en un equipo con GPU, hace que algunas capas pasen a la RAM del sistema; en un equipo con CPU, acerca la máquina 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.