Cómo limitar la salida de Ollama con num_predict

Qué hace num_predict en Ollama

num_predict es la opción de Ollama que limita cuántos tokens puede generar un modelo en una sola respuesta. Sólo cuenta los tokens de salida, por lo que el prompt no se contabiliza. Cuando el modelo alcanza el límite, la generación se detiene en ese punto, a veces a mitad de una palabra, y la respuesta incluye done_reason con el valor length.

Esa es toda la funcionalidad. La dificultad es que Ollama ofrece tres lugares distintos para establecer el valor, y prevalece la configuración más cercana a la solicitud. Casi todos los informes en los que se afirma que «num_predict no hace nada» se deben a que una capa sobrescribe silenciosamente a otra.

num_predict no es num_ctx

Estas dos opciones se confunden más que cualquier otro par en Ollama, y la confusión consume mucho tiempo real de depuración.

num_ctx indica cuánto puede leer el modelo. Es el tamaño de la ventana de contexto, que contiene el prompt y todo lo generado hasta ese momento. Aumentarlo consume memoria, porque la caché de clave/valor que el modelo mantiene para esos tokens crece junto con la ventana. Dimensionar num_ctx para el hardware es una tarea independiente, con sus propios modos de fallo.

num_predict indica cuánto escribirá el modelo. Es una regla de detención, no una asignación de memoria. Aumentarlo consume tiempo de ejecución, no RAM, y no se reserva nada por adelantado.

Ambas opciones se relacionan en un punto. Los tokens generados se incorporan a la ventana de contexto a medida que se producen, por lo que una respuesta también puede detenerse porque la ventana se llenó, en lugar de porque se alcanzó el límite configurado. Ollama informa length en ambos casos, por lo que el número que permite distinguirlos es eval_count, explicado más adelante.

Configúrelo una vez con un Modelfile

Un Modelfile integra el valor en el modelo que cree. Escriba el archivo:

FROM qwen3:8b
PARAMETER num_ctx 8192
PARAMETER num_predict 512

Después, créelo y compruebe lo que se ha creado:

ollama create qwen3-capped -f Modelfile
ollama show --parameters qwen3-capped

ollama show --parameters muestra una línea por cada parámetro almacenado, junto con su valor. Si num_predict no aparece en esa salida, el modelo no tiene ningún límite integrado y se aplica el valor predeterminado de Ollama. ollama show --modelfile qwen3-capped muestra la definición completa. También es la forma más rápida de copiar los parámetros con los que ya se distribuye un modelo existente. Crear un modelo con límite de esta forma casi no consume espacio adicional en disco, porque la nueva entrada reutiliza los blobs de pesos que el modelo base ya descargó en lugar de copiarlos. Además, conviene saber dónde guarda Ollama esos blobs antes de que se llene el disco raíz de un VPS.

Esta es la capa adecuada para un valor que quiera que hereden todos los clientes. No es la capa adecuada si espera que el valor sea definitivo, porque no lo es.

Establézcalo por solicitud en el objeto de opciones

Todos los endpoints de generación aceptan un objeto options, y num_predict se incluye dentro de él:

curl http://localhost:11434/api/generate -d '{
  "model": "qwen3:8b",
  "prompt": "Explain what a reverse proxy does.",
  "stream": false,
  "options": { "num_predict": 128 }
}'

/api/chat usa la misma clave options con el mismo significado. El valor establecido aquí se aplica sólo a esa llamada y a ninguna otra. Esta es la capa que utilizan sus herramientas: una interfaz de chat, un script, un wrapper de SDK o un agente de programación. Todas envían un objeto options, aunque no muestren un campo específico para ello.

Configúrelo para una sesión con /set parameter

Dentro de ollama run, la sesión interactiva establece opciones para el resto de esa sesión:

>>> /set parameter num_predict 256
>>> /show parameters

/show parameters muestra lo que la sesión enviará con el siguiente mensaje, por lo que es la forma más rápida de confirmar que el cambio se aplicó. El valor se mantiene hasta que escriba /bye. Para conservarlo, /save qwen3-capped guarda la sesión actual, incluidos los parámetros, como un modelo nuevo. Nada de lo que /set aquí llega a ningún otro cliente.

Qué configuración tiene prioridad y por qué la tuya parece ignorarse

El orden es sencillo. Las opciones enviadas con la petición tienen prioridad sobre todo lo demás. Una línea PARAMETER num_predict en el Modelfile del modelo se usa como valor alternativo cuando la petición no incluye ningún valor. Si no existe ninguna de las dos, se aplica el valor predeterminado integrado de Ollama.

/set parameter no es una tercera regla. La sesión interactiva es un cliente de API, por lo que lo que configures allí se envía como options de esa petición. Por eso tiene prioridad sobre el Modelfile durante la sesión.

Ahora, el fallo que esto explica. Añades PARAMETER num_predict 512, reconstruyes el modelo y las respuestas siguen llegando a miles de tokens. La configuración está presente, y ollama show --parameters lo demuestra. Se sobrescribe en cada petición porque el cliente envía su propio objeto options con su propio número. A menudo es un número que escribiste en una pantalla de configuración meses atrás y olvidaste. ollama show lee el modelo almacenado. No puede mostrarte lo que llega por HTTP.

Comprueba el comportamiento del servidor con un solo comando. Envía una petición que produzca una respuesta larga, fuerza un límite bajo y lee dos campos:

curl -s http://localhost:11434/api/generate -d '{
  "model": "qwen3-capped",
  "prompt": "Describe the Linux boot process in detail.",
  "stream": false,
  "options": { "num_predict": 32 }
}' | jq '.done_reason, .eval_count'

Esto debería mostrar "length" y 32. Instala primero jq con sudo apt install -y jq si falta. Una respuesta de "length" y 32 significa que el servidor respeta la opción y que tu aplicación está enviando otro valor. Para consultar el registro propio del servidor sobre una petición, reinícialo con OLLAMA_DEBUG=1 en el entorno y monitoriza journalctl -u ollama -f mientras tu aplicación se comunica con él.

Los valores negativos y los números que no debe copiar

num_predict también acepta valores negativos, que actúan como indicadores especiales en lugar de representar cantidades. Un valor negativo significa «no limite esto; siga generando». Otro se ha utilizado para «completar el contexto restante». En agosto de 2026, la referencia de Ollama Modelfile indica -1 como valor predeterminado para la generación infinita, y las versiones anteriores de la misma tabla también mostraban -2 para completar el contexto.

Trate todo esto como dependiente de la versión, porque ha cambiado. Durante mucho tiempo, la referencia documentó 128 como valor predeterminado, hasta que la entrada se corrigió a finales de 2024. Por eso, muchas guías todavía repiten el número antiguo. Consulte la referencia de parámetros de Modelfile correspondiente a la versión que realmente ejecuta y confirme después el comportamiento con la comprobación eval_count anterior. Un valor que haya verificado en su propio sistema es más fiable que cualquier valor leído en otro sitio, incluido este artículo.

Por qué la longitud de la salida es el coste principal en una VPS sin GPU

La generación tiene dos fases con velocidades muy diferentes. Los tokens del prompt se evalúan por lotes, muchos a la vez. Los tokens de salida se producen uno a uno y cada uno requiere un recorrido completo por los pesos del modelo. En una VPS sin GPU, ese recorrido está limitado por el ancho de banda de memoria, por lo que generar un token cuesta mucho más que procesar un token del prompt. Como ese recorrido debe leer todos los pesos, el número de bytes que ocupa cada peso establece el límite de la velocidad de generación. Por eso una compilación q4 decodifica más rápido que el mismo modelo en q8 o fp16.

Solicite una respuesta sin streaming y los valores aparecerán directamente:

"prompt_eval_count": 26,
"prompt_eval_duration": 107345000,
"eval_count": 237,
"eval_duration": 4289432000

Las duraciones están expresadas en nanosegundos. En ese bloque, que es la respuesta de ejemplo publicada en la documentación de la API de Ollama y no una medición de un servidor concreto, 26 tokens del prompt tardaron aproximadamente 0.1 segundos, mientras que 237 tokens de salida tardaron unos 4.3 segundos. Su velocidad de generación es eval_count dividida entre eval_duration y convertida a segundos. Medir los tokens por segundo en su propio hardware merece la pena hacerlo una vez antes de ajustar cualquier otra cosa. Esa velocidad depende tanto del modelo como de la máquina. Si las respuestas largas son el coste real, un modelo diseñado para decodificar rápido, como Nemotron 3.5 Lightning en una VPS, recupera parte del tiempo que, de otro modo, protege un límite bajo.

La aritmética completa el análisis. A 8 tokens por segundo, una respuesta de 2,000 tokens mantiene ocupada la máquina durante más de cuatro minutos, y el modelo no sabe que usted quería un párrafo. Un modelo de razonamiento consume parte de ese presupuesto pensando antes de escribir la palabra solicitada. Ese razonamiento también se genera un token cada vez, como todo lo demás. Por tanto, el esfuerzo de razonamiento que solicite es otra variable del mismo coste. Algunos modelos también entran en bucles y repiten una frase hasta que algo los detiene. Sin un límite, esa única solicitud mantiene un núcleo ocupado hasta que se agota la ventana de contexto. num_predict es el ajuste que establece ese límite. Esto es especialmente importante en una VPS de Ollama autohospedada pequeña, donde una solicitud larga puede ocupar toda la máquina.

La salida truncada suele deberse al límite, no a un fallo del modelo

Los síntomas parecen indicar un fallo del modelo. Una respuesta que se detiene a mitad de una frase. Un JSON que no se puede analizar porque nunca llegó la llave de cierre. La reacción habitual es culpar al modelo o a la cuantización. Revise primero la respuesta.

done_reason indica que la respuesta responde directamente a la pregunta. stop significa que el modelo terminó por sí solo, ya sea al emitir su token de fin de secuencia o al coincidir con una de las cadenas de la opción stop. length significa que la generación se interrumpió porque se quedó sin espacio. Cuando vea length, compare eval_count con su límite: una coincidencia exacta significa que num_predict detuvo la generación, mientras que un número menor significa que la ventana de contexto se llenó primero.

Al transmitir la respuesta, esos campos llegan en el último fragmento, el que contiene "done": true. Muchas bibliotecas cliente descartan ese fragmento y entregan al código sólo el texto. Por eso la misma truncación parece inexplicable dentro de una aplicación y resulta evidente con curl. Si una biblioteca oculta esa información, envíe una solicitud con curl para comprobar qué respondió realmente el servidor.

Hay otro punto que evita perder una tarde. Aumentar num_predict no hace que el modelo escriba más. Sólo elimina un límite superior. Si una respuesta termina en 200 tokens con done_reason de stop, el modelo decidió que había terminado y aumentar el límite no cambia nada. Las respuestas cortas con stop son un problema de prompting. Las respuestas cortas con length son un problema del límite.

Elegir un valor

• Para el chat interactivo, no establezca un límite y pulse Ctrl+C para detener una respuesta descontrolada. De todos modos, está supervisando la pantalla.
• Para cualquier proceso automatizado, establézcalo. Una generación sin límite dentro de un bucle puede hacer que un trabajo por lotes que debería tardar diez minutos siga ejecutándose a la mañana siguiente.
• Para una salida estructurada, establezca el límite por encima del documento válido más grande que espere y trate done_reason de length como un error grave. Vuelva a intentarlo en lugar de analizar la respuesta recibida.
• Para un agente de programación, el valor debe estar en la configuración del propio agente, porque el agente envía sus propias opciones en cada solicitud. Configurar un agente de programación para usar Ollama explica dónde se encuentran esos ajustes.

El límite cuenta tokens, no palabras ni caracteres, así que no lo estime. Genere una respuesta representativa sin límite, consulte eval_count y establezca el límite bastante por encima de ese valor. Las familias de modelos tokenizan de forma diferente, por lo que un valor que basta para un modelo Llama puede truncar la misma respuesta de un modelo Qwen 3 en el mismo VPS.

FAQ

¿Cuál es la diferencia entre num_ctx y num_predict en Ollama?

num_ctx es el tamaño de la ventana de contexto, por lo que determina cuánto puede leer el modelo: el prompt y todo lo generado hasta ese momento. Consume memoria porque la caché de clave/valor crece con ella. num_predict determina cuántos tokens puede escribir el modelo en una respuesta. Consume tiempo, no memoria, y no reserva espacio por adelantado. Los tokens generados cuentan para ambos límites, por lo que cualquiera de los dos puede truncar la respuesta.

¿Por qué parece que se ignora mi configuración de num_predict?

Porque un valor enviado con la solicitud reemplaza al valor almacenado en el modelo. Incluya PARAMETER num_predict 512 en un Modelfile, use después ese modelo desde un frontend de chat o un agente de programación, y el cliente enviará su propio objeto options, cuyo número tendrá prioridad. ollama show --parameters seguirá mostrando su valor, porque lee el modelo almacenado y no puede ver lo que llega mediante HTTP. Envíe una solicitud con curl usando "options": {"num_predict": 32} y compruebe que eval_count devuelve 32. Esto confirma que el servidor funciona correctamente y limita la búsqueda a la aplicación.

¿Cómo puedo saber si num_predict truncó mi salida?

Envíe la solicitud con "stream": false y lea done_reason. Un valor de stop significa que el modelo terminó por sí solo. Un valor de length significa que se quedó sin espacio. Compare después eval_count con su límite: si coinciden exactamente, num_predict detuvo la generación; si eval_count es menor, la ventana de contexto se llenó primero. En modo streaming, ambos campos llegan en el fragmento final con "done": true, que muchas bibliotecas cliente descartan antes de que el código pueda verlo.

¿Cuál es el valor predeterminado de num_predict?

Consúltelo en su propia instalación, no en un artículo. En agosto de 2026, la referencia de Modelfile de Ollama indica que el valor predeterminado es -1, lo que significa que la generación no está limitada. Esa entrada se corrigió a finales de 2024, después de años de documentar 128. Los valores negativos son indicadores especiales, no cantidades, y las versiones anteriores de la misma tabla también indicaban -2 para llenar el contexto restante. Consulte la referencia de parámetros de Modelfile correspondiente a su versión y confírmelo con ollama show --parameters y una solicitud curl.

¿Aumentar num_predict hace que el modelo escriba respuestas más largas?

No. Sólo elimina un límite máximo. Si una respuesta termina con done_reason de stop, el modelo decidió que había terminado y aumentar el límite no cambia nada. En ese caso, la longitud depende de la instrucción: solicite una estructura concreta, un número de secciones o un nivel de detalle definido. Aumente num_predict sólo cuando done_reason devuelva length.