Ollama: limitar la salida 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 los tokens del prompt no se incluyen en ese límite. 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 devuelve done_reason establecido en length.

Esa es toda la funcionalidad. La dificultad es que Ollama permite establecer el valor en tres lugares distintos, y prevalece la configuración más cercana a la solicitud. Casi todos los informes de 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 hace perder mucho tiempo 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 claves y valores que el modelo conserva para esos tokens crece con la ventana. Dimensionar num_ctx para el hardware es una tarea independiente, con sus propios modos de fallo.

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

Ambas opciones interactúan 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ó y no porque se alcanzara el límite configurado. Ollama informa length en ambos casos, por lo que el número que permite distinguirlos es eval_count, que se explica 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 lea la configuración resultante:

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 un 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.

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

Configúrelo 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 configurado aquí se aplica sólo a esa llamada y a ninguna otra. Esta es la capa que usan 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 le muestren un campo para configurarlo.

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

Dentro de ollama run, la sesión interactiva configura 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 escribas /bye. Para conservarlo, /save qwen3-capped escribe la sesión actual, incluidos los parámetros, como un modelo nuevo. Nada de lo que /set configures aquí afecta a ningún otro cliente.

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

El orden es sencillo. Las opciones enviadas con la solicitud prevalecen sobre todo lo demás. Una línea PARAMETER num_predict en el Modelfile del modelo es el valor alternativo que se usa cuando la solicitud no incluye ningún valor. Si no se especifica ninguno de los 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 tanto, lo que configuras allí se envía como options de esa solicitud. Por eso sustituye al valor del Modelfile durante la sesión.

Esto explica el fallo. Añades PARAMETER num_predict 512, vuelves a compilar el modelo y las respuestas siguen generando miles de tokens. Tu configuración está presente, y ollama show --parameters lo demuestra. Pero se sustituye en cada solicitud porque el cliente envía su propio objeto options con su propio valor, a menudo 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 solicitud 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'

Debería mostrar "length" y 32. Instala 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 ver el registro que el propio servidor hace de una solicitud, 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 funcionan como indicadores especiales y no como cantidades. Un valor negativo significa «no limitar esto; continuar generando». Otro ha significado «rellenar 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 rellenar el contexto.

Trate todo esto como información 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 ejecuta y confirme después el comportamiento con la comprobación eval_count anterior. Un valor que haya verificado en su propio equipo es más fiable que uno que haya leído en cualquier sitio, incluido este artículo.

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

La generación tiene dos fases con velocidades muy diferentes. Los tokens del prompt se evalúan en lotes, muchos a la vez. Los tokens de salida se generan de uno en 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 evaluar un token del prompt.

Solicite una respuesta sin streaming y las cifras aparecen 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 muestra 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 por eval_duration y convertida a segundos. También conviene medir los tokens por segundo en su propio hardware una vez antes de ajustar cualquier otra cosa. Esa velocidad depende tanto del modelo como de la máquina. Por tanto, si las respuestas largas son el coste real, un modelo diseñado para una decodificación rápida, como Nemotron 3.5 Lightning en una VPS, recupera parte del tiempo que un límite bajo intenta ahorrar.

La aritmética completa el análisis. A 8 tokens por segundo, una respuesta de 2,000 tokens mantiene la máquina ocupada durante más de cuatro minutos, y el modelo no sabe que usted quería un párrafo. 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 con Ollama autohospedado pequeña, donde una solicitud larga puede ocupar toda la máquina.

El resultado truncado suele deberse al límite, no a un fallo del modelo

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

done_reason significa que la respuesta responde directamente a la pregunta. stop significa que el modelo terminó por sí solo, ya sea porque emitió su token de fin de secuencia o porque coincidió 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, y un número menor significa que la ventana de contexto se llenó antes.

Cuando usa streaming, esos campos llegan en el último fragmento, el que contiene "done": true. Muchas bibliotecas cliente descartan ese fragmento y entregan a su código sólo el texto. Por eso la misma truncación parece inexplicable dentro de una aplicación y evidente en curl. Si una biblioteca oculta ese dato, envíe una solicitud con curl para saber qué respondió realmente el servidor.

Hay otro punto que evita perder una tarde. Aumentar num_predict no hace que un 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 un límite mayor no cambia nada. Las respuestas cortas con stop son un problema de prompting. Las respuestas cortas con length son un problema de límite.

Elegir un valor

• Para el chat interactivo, déjelo sin límite y pulse Ctrl+C para detener una respuesta descontrolada. De todos modos, está observando la pantalla.
• Para cualquier proceso con scripts, 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 la salida estructurada, establezca el límite por encima del documento válido más grande que espera. Después, trate done_reason de length como un error grave y vuelva a intentarlo en lugar de analizar la respuesta recibida.
• En 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, por lo que no debe calcularlo de forma aproximada. Genere una respuesta representativa sin límite, lea 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 permite completar una respuesta con un modelo Llama puede truncar esa misma respuesta con 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 más 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 se reserva nada por adelantado. Los tokens generados cuentan para ambos límites, por lo que la respuesta puede quedar truncada por cualquiera de los dos.

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

Porque un valor enviado con la solicitud sustituye al valor almacenado en el modelo. Añada PARAMETER num_predict 512 a un Modelfile, use después ese modelo desde una interfaz de chat o un agente de programación y el cliente enviará su propio objeto options, cuyo número tiene prioridad. ollama show --parameters seguirá mostrando su valor, porque lee el modelo almacenado y no puede ver lo que llega por 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. Al usar streaming, ambos campos llegan en el bloque 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 en lugar de basarse 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, y esa entrada se corrigió a finales de 2024 después de años en los que se documentó 128. Los valores negativos actúan como indicadores especiales, no como cantidades, y las versiones anteriores de la misma tabla también indicaban -2 para completar 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 superior. 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 cómo se formule la solicitud: pida una estructura concreta, un número de secciones o un nivel de detalle específico. Aumente num_predict sólo cuando done_reason devuelva length.