Ollama : limiter la longueur avec num_predict

Rôle de num_predict dans Ollama

num_predict est l’option Ollama qui limite le nombre de tokens qu’un modèle peut générer dans une réponse. Elle compte uniquement les tokens produits. Le prompt n’est donc jamais pris en compte. Lorsque le modèle atteint cette limite, la génération s’arrête à cet endroit, parfois au milieu d’un mot, et la réponse renvoie done_reason défini sur length.

C’est toute la fonctionnalité. La difficulté vient du fait qu’Ollama permet de définir cette valeur à trois endroits différents, et que le réglage le plus proche de la requête est prioritaire. Presque tous les signalements indiquant que « num_predict ne fait rien » s’expliquent par une couche qui remplace silencieusement le réglage d’une autre couche.

num_predict n’est pas num_ctx

Ces deux options sont davantage confondues que toute autre paire dans Ollama, et cette confusion fait perdre un temps réel de diagnostic.

num_ctx indique la quantité que le modèle peut lire. Il s’agit de la taille de la fenêtre de contexte, qui contient le prompt et tout ce qui a été produit jusque-là. Augmenter cette valeur consomme de la mémoire, car le cache key/value que le modèle conserve pour ces tokens augmente avec la taille de la fenêtre. Dimensionner num_ctx pour votre matériel est une tâche distincte, avec ses propres causes d’échec.

num_predict indique la quantité que le modèle va écrire. Il s’agit d’une règle d’arrêt, pas d’une allocation. Augmenter cette valeur coûte du temps d’exécution plutôt que de la RAM, et rien n’est réservé à l’avance.

Ces deux paramètres se rejoignent à un endroit. Les tokens générés sont ajoutés à la fenêtre de contexte au fur et à mesure de leur production. Une réponse peut donc aussi s’arrêter parce que la fenêtre est pleine, et non parce que la limite configurée a été atteinte. Ollama signale length dans les deux cas. La valeur qui permet de les distinguer est donc eval_count, comme indiqué plus loin.

Définissez-la une fois avec un Modelfile

Un Modelfile intègre la valeur au modèle que vous créez. Écrivez le fichier :

FROM qwen3:8b
PARAMETER num_ctx 8192
PARAMETER num_predict 512

Construisez ensuite le modèle et vérifiez le résultat :

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

ollama show --parameters affiche une ligne par paramètre enregistré, avec sa valeur. Si num_predict n’apparaît pas dans cette sortie, le modèle ne contient aucune limite intégrée et la valeur par défaut d’Ollama s’applique. ollama show --modelfile qwen3-capped affiche la définition complète. C’est également le moyen le plus rapide de recopier les paramètres déjà intégrés à un modèle existant.

C’est le bon niveau de configuration pour une valeur que vous voulez transmettre à tous les appelants. Ce n’est pas le bon niveau si vous pensez qu’elle sera définitive, car ce n’est pas le cas.

Définissez-le pour chaque requête dans l’objet d’options

Chaque endpoint de génération accepte un objet options, et num_predict se place à l’intérieur :

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 utilise la même clé options avec la même signification. Une valeur définie ici s’applique uniquement à cet appel. Elle ne s’applique à rien d’autre. C’est la couche utilisée par vos outils : une interface de chat, un script, un wrapper SDK ou un agent de programmation. Ils envoient tous un objet options, qu’ils affichent ou non un champ correspondant.

Définissez-le pour une session avec le paramètre /set

Dans ollama run, la session interactive définit des options pour le reste de cette session :

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

/show parameters affiche ce que la session enverra avec votre prochain message. C’est donc le moyen le plus rapide de vérifier qu’une modification a bien été prise en compte. La valeur reste active jusqu’à ce que vous saisissiez /bye. Pour la conserver, /save qwen3-capped enregistre la session actuelle, paramètres inclus, en tant que nouveau modèle. Rien de ce que vous /set ici n’est transmis à un autre client.

Quel paramètre l’emporte, et pourquoi le vôtre semble ignoré

L’ordre est simple. Les options envoyées avec la requête ont priorité sur tout le reste. Une ligne PARAMETER num_predict dans le Modelfile du modèle sert de valeur de repli lorsque la requête ne contient aucune valeur. En l’absence de ces deux éléments, la valeur par défaut intégrée à Ollama s’applique.

/set parameter n’est pas une troisième règle. La session interactive est un client API. La valeur que vous y définissez est donc envoyée comme options de cette requête. C’est précisément pourquoi elle remplace le paramètre du Modelfile pendant la session.

Voici le problème que cela explique. Vous ajoutez PARAMETER num_predict 512, vous reconstruisez le modèle, et les réponses continuent de produire des milliers de tokens. Votre paramètre est bien présent, comme le confirme ollama show --parameters. Mais il est remplacé à chaque requête, car le client envoie son propre objet options avec sa propre valeur, souvent un nombre que vous avez saisi dans un écran de paramètres plusieurs mois auparavant et oublié depuis. ollama show lit le modèle enregistré. Il ne peut pas vous montrer ce qui arrive via HTTP.

Vérifiez le serveur avec une seule commande. Envoyez une requête qui produira une réponse longue, imposez une limite basse et lisez deux champs :

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'

Cette commande doit afficher "length" et 32. Installez d’abord jq avec sudo apt install -y jq s’il est absent. Une réponse contenant "length" et 32 signifie que le serveur respecte l’option et que votre application envoie une valeur différente. Pour afficher ce que le serveur reçoit réellement, redémarrez-le avec OLLAMA_DEBUG=1 dans l’environnement et surveillez journalctl -u ollama -f pendant que votre application lui envoie des requêtes.

Les valeurs négatives et les nombres à ne pas copier

num_predict accepte également les valeurs négatives. Il s’agit de valeurs sentinelles, pas de comptes. Une valeur négative signifie « ne pas limiter cette valeur, continuer la génération ». Une autre a signifié « remplir le contexte restant ». En août 2026, la référence Ollama Modelfile indique -1 comme valeur par défaut, ce qui correspond à une génération infinie. Des versions antérieures du même tableau indiquaient également -2 pour remplir le contexte.

Considérez ces valeurs comme dépendantes de la version, car elles ont changé. La référence a longtemps documenté 128 comme valeur par défaut, avant que cette entrée soit corrigée fin 2024. De nombreux guides reprennent donc encore l’ancien nombre. Consultez la référence des paramètres Modelfile correspondant à la version que vous utilisez, puis confirmez le comportement avec la vérification eval_count ci-dessus. Une valeur vérifiée sur votre propre serveur est plus fiable qu’une valeur lue ailleurs, y compris dans cet article.

Pourquoi la longueur de la sortie est le principal coût sur un VPS sans GPU

La génération comporte deux phases, à des vitesses très différentes. Les tokens du prompt sont évalués par lots, plusieurs à la fois. Les tokens de sortie sont produits un par un, et chacun nécessite un parcours complet des poids du modèle. Sur un VPS sans GPU, ce parcours est limité par la bande passante mémoire. La génération d’un token coûte donc beaucoup plus cher que l’évaluation d’un token du prompt.

Demandez une réponse sans streaming et les valeurs apparaissent directement :

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

Les durées sont exprimées en nanosecondes. Dans ce bloc, qui correspond à l’exemple de réponse publié dans la documentation de l’API Ollama et non à une mesure effectuée sur un serveur particulier, 26 tokens du prompt ont pris environ 0.1 seconde, tandis que 237 tokens de sortie ont pris environ 4.3 secondes. Votre débit de génération correspond à eval_count divisé par eval_duration, puis converti en secondes. Il est utile de mesurer le nombre de tokens par seconde sur votre propre matériel une fois avant d’ajuster autre chose. Ce débit dépend autant du modèle que de la machine. Si les réponses longues représentent le coût réel, un modèle conçu pour un décodage rapide, comme Nemotron 3.5 Lightning sur un VPS, permet de récupérer une partie du temps qu’un plafond bas cherche autrement à protéger.

Le calcul suffit ensuite. À 8 tokens par seconde, une réponse de 2,000 tokens mobilise la machine pendant plus de quatre minutes, et le modèle ne sait pas que vous vouliez un paragraphe. Certains modèles bouclent également et répètent une phrase jusqu’à ce qu’un mécanisme les arrête. Sans plafond, cette requête continue à occuper un cœur jusqu’à ce que la fenêtre de contexte soit épuisée. num_predict est le paramètre qui fixe cette limite. Il est particulièrement important sur un VPS Ollama auto-hébergé de petite taille, où une seule requête longue peut mobiliser toute la machine.

Une sortie tronquée indique généralement que la limite a été atteinte, pas que le modèle est défaillant

Les symptômes donnent l’impression que le modèle a échoué. La réponse s’arrête au milieu d’une phrase. Le JSON ne peut pas être analysé, car l’accolade fermante n’est jamais arrivée. Le premier réflexe consiste à accuser le modèle ou la quantisation. Commencez par lire la réponse.

done_reason signifie que la réponse répond directement à la question. stop signifie que le modèle s’est arrêté de lui-même, soit en émettant son token de fin de séquence, soit en trouvant l’une des chaînes indiquées dans l’option stop. length signifie que la génération a été interrompue parce qu’il n’y avait plus assez de place. Lorsque vous voyez length, comparez eval_count à votre limite : une correspondance exacte signifie que num_predict a arrêté la génération, tandis qu’une valeur inférieure signifie que la fenêtre de contexte s’est remplie en premier.

Avec le streaming, ces champs arrivent dans le dernier chunk, celui qui contient "done": true. De nombreuses bibliothèques clientes ignorent ce chunk et ne transmettent à votre code que le texte. C’est pourquoi la même troncature semble inexpliquée dans une application, alors qu’elle est évidente avec curl. Si une bibliothèque masque cette information, envoyez une requête avec curl pour savoir ce que le serveur a réellement indiqué.

Un dernier point peut vous éviter de perdre une après-midi. Augmenter num_predict ne fait pas écrire davantage le modèle. Cela supprime seulement une limite supérieure. Si une réponse s’arrête à 200 tokens avec done_reason de stop, le modèle a décidé qu’elle était terminée et une limite plus élevée ne changera rien. Les réponses courtes avec stop indiquent un problème de prompting. Les réponses courtes avec length indiquent un problème de limite.

Choisir une valeur

• Pour le chat interactif, ne définissez aucune limite et appuyez sur Ctrl+C pour arrêter une réponse qui s’emballe. Vous surveillez l’écran de toute façon.
• Pour tout ce qui est exécuté par un script, définissez-la. Une génération sans limite dans une boucle peut faire durer jusqu’au lendemain un traitement par lots qui devrait prendre dix minutes.
• Pour une sortie structurée, définissez la limite au-dessus de la taille du plus grand document valide attendu, puis considérez done_reason de length comme une erreur bloquante et relancez la requête au lieu d’analyser la réponse reçue.
• Pour un agent de programmation, la valeur doit être définie dans la configuration de l’agent, car celui-ci envoie ses propres options à chaque requête. Configurer un agent de programmation avec Ollama indique où se trouvent ces paramètres.

La limite compte les tokens, pas les mots ni les caractères. Ne l’estimez donc pas. Générez une réponse représentative sans limite, lisez eval_count, puis définissez la limite nettement au-dessus de cette valeur. Les familles de modèles ne tokenisent pas de la même façon. Une valeur suffisante pour un modèle Llama peut donc tronquer la même réponse produite par un modèle Qwen 3 sur le même VPS.

FAQ

Quelle est la différence entre num_ctx et num_predict dans Ollama ?

num_ctx correspond à la taille de la fenêtre de contexte. Il détermine la quantité de texte que le modèle peut lire : le prompt et tout ce qui a déjà été produit. Il consomme de la mémoire, car le cache key/value augmente avec cette taille. num_predict détermine le nombre de tokens que le modèle peut écrire dans une réponse. Il consomme du temps plutôt que de la mémoire, et rien n’est réservé à l’avance. Les tokens générés sont comptabilisés dans les deux limites. Une réponse peut donc être interrompue par l’une ou l’autre.

Pourquoi mon paramètre num_predict semble-t-il ignoré ?

Parce qu’une valeur envoyée avec la requête remplace celle stockée dans le modèle. Placez PARAMETER num_predict 512 dans un Modelfile, puis utilisez ce modèle depuis une interface de chat ou un coding agent. Le client envoie alors son propre objet options, et sa valeur est prioritaire. ollama show --parameters affiche toujours votre valeur, car il lit le modèle enregistré et ne peut pas voir ce qui arrive via HTTP. Envoyez une requête avec curl en utilisant "options": {"num_predict": 32}, puis vérifiez que eval_count revient à 32. Cela confirme que le serveur se comporte correctement et oriente la recherche vers votre application.

Comment savoir si ma sortie a été interrompue par num_predict ?

Envoyez la requête avec "stream": false et lisez done_reason. La valeur stop signifie que le modèle a terminé de lui-même. La valeur length signifie qu’il n’avait plus assez de place. Comparez ensuite eval_count à votre limite : s’ils correspondent exactement, num_predict a interrompu la génération. Si eval_count est inférieur, la fenêtre de contexte a été remplie en premier. En streaming, les deux champs arrivent dans le dernier bloc avec "done": true. De nombreuses bibliothèques clientes les suppriment avant que votre code ne les reçoive.

Quelle est la valeur par défaut de num_predict ?

Lisez-la dans votre propre installation plutôt que dans un article. En août 2026, la référence du Modelfile d’Ollama indique que la valeur par défaut est -1. Cela signifie que la génération n’est pas limitée. Cette entrée a été corrigée à la fin de 2024, après plusieurs années pendant lesquelles la documentation indiquait 128. Les valeurs négatives sont des valeurs sentinelles, et non des nombres de tokens. Les anciennes versions du même tableau indiquaient également -2 pour remplir le contexte restant. Consultez la référence des paramètres du Modelfile correspondant à votre version, puis confirmez-la avec ollama show --parameters et une requête curl.

Augmenter num_predict fait-il écrire des réponses plus longues au modèle ?

Non. Cela supprime seulement une limite supérieure. Si une réponse se termine par done_reason de stop, le modèle a décidé qu’elle était terminée et une limite plus élevée ne change rien. Dans ce cas, la longueur dépend du prompt : demandez une structure précise, un nombre de sections ou un niveau de détail défini. Augmentez num_predict uniquement lorsque done_reason revient avec la valeur length.