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 de sortie. Le prompt n’est donc jamais pris en compte dans cette limite. 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 revient avec 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 paramètre le plus proche de la requête est prioritaire. Presque tous les signalements indiquant que « num_predict ne fait rien » sont dus à une couche qui remplace discrètement le paramètre d’une autre couche.

num_predict n’est pas num_ctx

Ces deux options sont davantage confondues que n’importe quelle autre paire dans Ollama, et cette confusion fait perdre beaucoup de temps lors du débogage.

num_ctx détermine la quantité de texte que le modèle peut lire. Il s’agit de la taille de la fenêtre de contexte, qui contient le prompt ainsi que tout le contenu déjà produit. L’augmenter consomme de la mémoire, car le cache clé/valeur 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 détermine la quantité de texte que le modèle peut écrire. Il s’agit d’une règle d’arrêt, et non d’une allocation. L’augmenter consomme du temps d’exécution plutôt que de la RAM, et aucune mémoire n’est réservée à l’avance.

Ces deux options 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 indique length dans les deux cas. La valeur qui permet de les distinguer est donc eval_count, présentée plus bas.

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 relisez ce que vous avez créé :

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 aussi le moyen le plus rapide de copier les paramètres déjà fournis avec un modèle existant. La création d’un modèle limité de cette manière consomme presque aucun espace disque supplémentaire, car la nouvelle entrée réutilise les blobs de poids déjà téléchargés par le modèle de base au lieu de les copier. Il est utile de savoir où Ollama conserve ces blobs avant que le disque root d’un VPS arrive à saturation.

C’est la bonne couche pour une valeur que vous voulez transmettre à tous les appelants. Ce n’est pas la bonne couche 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, dans lequel num_predict est placé :

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 à ce niveau qu’interviennent 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éfinir le paramètre pour une session avec /set

Dans ollama run, la session interactive définit des options pour le reste de la 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 compris, comme un nouveau modèle. Rien de ce que vous /set ici n’est transmis à un autre client.

Quel réglage est prioritaire, et pourquoi le vôtre semble ignoré

L’ordre est simple. Les options envoyées avec la requête sont prioritaires. 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 des deux, 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 d’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 réglage du Modelfile pour la session.

Voici le problème que cela permet d’expliquer. Vous ajoutez PARAMETER num_predict 512, vous reconstruisez le modèle, mais les réponses contiennent toujours des milliers de tokens. Votre réglage est bien présent, et ollama show --parameters le confirme. Il est remplacé à chaque requête, car le client envoie son propre objet options avec sa propre valeur, souvent une valeur saisie dans un écran de paramètres plusieurs mois auparavant et oubliée depuis. ollama show lit le modèle enregistré. Il ne peut pas vous montrer ce qui arrive via HTTP.

Vérifiez le serveur en 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'

La 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 voir 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 que vous ne devez pas copier

num_predict accepte également les valeurs négatives. Il s’agit de sentinelles, pas de nombres de tokens. L’une d’elles signifie « ne pas limiter ce paramètre, continuer à générer ». 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, pour une génération infinie. Les versions précédentes du même tableau indiquaient également -2 pour remplir le contexte.

Considérez tout cela comme dépendant de la version, car ce comportement a changé. La référence indiquait 128 comme valeur par défaut depuis longtemps, 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 de Modelfile correspondant à la version que vous utilisez, puis confirmez le comportement avec la vérification eval_count ci-dessus. Une valeur que vous avez vérifiée sur votre propre système est plus fiable qu’une valeur lue ailleurs, y compris dans cet article.

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

La génération comporte deux phases, à deux 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. Comme ce parcours doit lire chaque poids, le nombre d’octets occupés par chaque poids fixe le plafond du débit de génération. C’est pourquoi un build q4 décode plus rapidement que le même modèle en q8 ou fp16.

Demandez une réponse sans streaming pour voir directement les valeurs :

"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 donné, 26 tokens de 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 est 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 longues réponses constituent le coût réel, un modèle conçu pour accélérer le décodage, comme Nemotron 3.5 Lightning sur un VPS, réduit une partie du temps qu’un plafond bas cherche à 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 ignore que vous vouliez un paragraphe. Un modèle de raisonnement consacre une partie de ce budget à réfléchir avant d’écrire le moindre mot demandé. Cette réflexion est générée un token à la fois, comme le reste. Ainsi, l’effort de raisonnement que vous demandez constitue un autre levier sur la même facture. 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 unique maintient un cœur CPU occupé 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 petit VPS Ollama auto-hébergé, où une seule requête longue peut mobiliser toute la machine.

La sortie tronquée vient généralement de la limite, pas d’un modèle défaillant

Les symptômes font penser à un problème du modèle. 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 réflexe consiste à accuser le modèle ou la quantification. 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 détectant 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 context window a été remplie en premier.

En 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 vérifier ce que le serveur a réellement renvoyé.

Un autre point permet d’éviter de perdre une après-midi. Augmenter num_predict ne fait pas écrire davantage au modèle. Cela supprime uniquement 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 change 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 un 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 qu’un traitement par lots prévu pour durer dix minutes tourne encore le lendemain matin.
• Pour une sortie structurée, définissez une limite supérieure à la taille du document valide le plus volumineux que vous prévoyez, puis considérez done_reason de length comme une erreur bloquante et relancez la requête au lieu d’analyser le résultat obtenu.
• Pour un agent de programmation, la valeur doit figurer dans sa propre configuration, car l’agent envoie ses propres options à chaque requête. Configurer un agent de programmation avec Ollama explique 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 une limite suffisamment supérieure. Les familles de modèles tokenisent différemment : une valeur suffisante pour un modèle Llama peut 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 donc la quantité de texte que le modèle peut lire : le prompt et tout ce qui a été produit jusque-là. Il consomme de la mémoire, car le cache key/value augmente avec cette taille. num_predict définit le nombre maximal de tokens que le modèle peut écrire dans une réponse. Il consomme du temps plutôt que de la mémoire, et aucune capacité n’est réservée à l’avance. Les tokens générés sont pris en compte 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 la valeur enregistré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 agent de programmation. Le client envoie alors son propre objet options, dont la valeur est prioritaire. ollama show --parameters affiche tout de même votre valeur, car il lit le modèle enregistré et ne voit pas ce qui arrive via HTTP. Envoyez une requête avec curl à l’aide de "options": {"num_predict": 32} et vérifiez que eval_count revient avec la valeur 32. Cela confirme que le serveur fonctionne 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 de place. Comparez ensuite eval_count à votre limite : si les deux valeurs sont exactement identiques, num_predict a interrompu la génération. Si eval_count est plus petit, la fenêtre de contexte s’est remplie en premier. En mode streaming, les deux champs arrivent dans le dernier bloc avec "done": true. De nombreuses bibliothèques clientes les suppriment avant que votre code puisse les lire.

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 Ollama des Modelfile indique que la valeur par défaut est -1, ce qui 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 128 était documenté. Les valeurs négatives sont des valeurs sentinelles, pas des nombres de tokens. Les anciennes versions du même tableau indiquaient également -2 pour utiliser le contexte restant. Consultez la référence des paramètres 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 uniquement 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 indiqué. Augmentez num_predict uniquement lorsque done_reason revient avec la valeur length.