SSD Nodes Learn Hosting plans →
Guías Matt ConnorPor Matt Connor · Actualizado 2026-10-20

Ollama: configurar num_ctx y evitar truncar prompts

Ollama puede truncar prompts largos por defecto. Configura num_ctx por petición o servidor y calcula la RAM del KV cache antes de subirlo.

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

La longitud de contexto de Ollama es el número de tokens que un modelo cargado puede mantener en memoria a la vez, 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 trunca 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 proporcionará ese valor. La documentación de Ollama muestra valores predeterminados diferentes en distintas páginas: 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 desde 24 GiB hasta 48 GiB, y 256k a partir de 48 GiB. Cada valor fue válido 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 pasa desapercibido porque el modelo sigue respondiendo y la respuesta sigue teniendo sentido. La respuesta se generó a partir del 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 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 simplemente num_ctx en el máximo del modelo

Attention hace que cada token consulte todos los tokens anteriores. Las keys y values calculadas para los tokens anteriores se conservan para no volver a calcularlas con cada token nuevo. Ese almacenamiento es la KV cache (key/value cache). 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.

Cada capa conserva un vector key y un vector value por cada cabeza key/value y por cada token. La operación se resume en una línea:

kv_bytes_per_token = 2 * layers * kv_heads * head_dim * bytes_per_value

El valor 2 cuenta las keys y las values por separado. Consulte los demás valores en 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 cabezas key/value. La dimensión de la cabeza es embed dividida entre heads, por lo que aquí 4096 / 32 = 128. Algunos modelos la publican directamente como llama.attention.key_length. La cache predeterminada usa valores f16, por lo que bytes_per_value es 2. Así, 2 32 8 128 2 da 131,072 bytes. Eso equivale a 128 KiB de cache por cada token de contexto. Multiplique por la longitud del contexto y el coste deja de ser abstracto.

GráficoLlama 3.1 8B at f16: KV cache and total RAM by context length, in GiB
Los datos de este gráfico
[
  {
    "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 octubre de 2026, equivalente a 4.6 GiB, y excluye 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 cache 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, una VPS de 4 GB no puede cargar este modelo con un contexto útil. Una VPS de 8 GB funciona con comodidad a 8k. Una VPS de 16 GB alcanza 32k y deja memoria para el resto del sistema. Cada uno de esos umbrales aumenta con el tamaño de los pesos. Si compara un modelo más grande con este 8B, los mismos cálculos aplicados a la etiqueta 27B de Qwen en una VPS con CPU únicamente muestran cuánta memoria 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 simplemente sigue creciendo. 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 la swap usada en free -m empieza a aumentar, reduzca el contexto. Una caché KV que reside en la swap hace que la generación se detenga durante varios segundos por token, porque cada token nuevo lee toda la caché.

Si el equipo se queda completamente sin memoria, el kernel elige un proceso para terminarlo, normalmente el que más memoria ocupa.

sudo dmesg | grep -i "killed process"

Una línea que indique Out of memory: Killed process 1234 (ollama) significa que Ollama fue el proceso que eligió el kernel, no necesariamente el que agotó la memoria. En un equipo donde Ollama es el único proceso grande, un contexto demasiado grande suele ser la causa. Compruebe qué más se estaba ejecutando antes de reducir num_ctx. Ollama suele rechazar la solicitud antes de llegar a ese punto; en ese caso, la solicitud falla con un mensaje que indica cuánta memoria necesitaba y cuánta memoria estaba libre.

En un equipo con GPU, el fallo es menos evidente. Algunas capas pasan a la RAM del sistema, ollama ps muestra el reparto entre CPU y GPU y el rendimiento cae de forma considerable. La magnitud de la caída depende del hardware. Por eso, mida los tokens por segundo en su propio equipo con cada valor de contexto, en lugar de confiar en una cifra obtenida en el equipo 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.

Recupere memoria reduciendo la caché

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, q8_0 con aproximadamente la mitad de memoria que f16 y q4_0 con aproximadamente una cuarta parte. La cifra exacta de q8_0 es algo más de la mitad: llama.cpp almacena cada bloque de 32 valores como 32 valores de un byte más una escala de dos bytes, es decir, 34 bytes, mientras que f16 necesita 64. Cambiar a q8_0 reduce la fila de 32k a aproximadamente 2.1 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. La misma FAQ indica que la caché sólo se cuantiza cuando Flash Attention está habilitado, y documenta OLLAMA_FLASH_ATTENTION=1 para forzarlo.

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

Confirme el resultado 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á contemplada. El tipo de caché es una opción global, así que todos los modelos del servidor la utilizan. En cuanto a la calidad, la FAQ indica que q8_0 normalmente no tiene un efecto perceptible, mientras que q4_0 pierde más precisión, sobre todo con tamaños de contexto mayores. Por tanto, pruebe q4_0 con sus propias peticiones antes de depender de él. 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. 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. Si ese informe es un PDF, recuerde que Ollama no abre el archivo: el programa que extrae el texto y se lo entrega a Ollama decide cuánto de ese documento llega realmente al contexto. 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 predeterminado elegido según la VRAM disponible: 4k por debajo de 24 GiB, 32k desde 24 GiB hasta 48 GiB y 256k con 48 GiB o más. 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 era más largo que 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 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 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 lo que 32k tokens cuestan 4 GiB y los 128k completos cuestan 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í, 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 indica. La caché mayor también compite por la memoria: en un equipo con GPU, hace que algunas capas pasen a la RAM del sistema, y en un equipo que sólo usa 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 ejecute ollama create llama3.1-16k -f ./Modelfile. Todo cliente que solicite llama3.1-16k obtiene 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.

¿Te resultó útil este artículo?