Ollama : limiter la longueur avec num_predict
Apprenez où définir num_predict dans Ollama, quelle valeur est prioritaire et comment interpréter done_reason lorsque la génération s’arrête sur la limite.
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 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 ainsi que tout ce qui a été produit jusque-là. L’augmentation de cette valeur 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 indique la quantité que le modèle va é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 ressource n’est réservée à 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. Dans Ollama v0.40.11, le décalage du contexte est activé par défaut pour la plupart des modèles. Lorsque la fenêtre est pleine, les anciens tokens sont supprimés et la génération continue. Si le décalage est désactivé, parce que la requête envoie "shift": false ou parce que le modèle ne prend pas en charge ce mécanisme, la réponse peut aussi s’arrêter parce que la fenêtre est pleine, et non parce que la limite définie a été atteinte. Ollama signale length dans les deux cas. La valeur qui permet de les distinguer est donc eval_count, comme expliqué 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 512Construisez ensuite le modèle et relisez ce que vous avez créé :
ollama create qwen3-capped -f Modelfile
ollama show --parameters qwen3-cappedollama 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. Si aucune des deux n’est définie, 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 explique. Vous ajoutez PARAMETER num_predict 512, 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 un nombre que vous avez saisi dans un écran de paramètres plusieurs mois auparavant et oublié depuis. ollama show lit la configuration enregistrée du modèle. Il ne peut pas vous montrer ce qui arrive via HTTP.
Vérifiez le comportement côté serveur avec une seule commande. Envoyez une requête qui produira une réponse longue, forcez 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'Une réponse détaillée dépasse largement 32 tokens. Attendez-vous donc à "length" et 32. Installez d’abord jq avec sudo apt install -y jq s’il est absent. La valeur 32 n’est pas garantie, car eval_count correspond simplement au nombre de tokens de sortie effectivement générés par le serveur. Si le modèle termine rapidement, vous obtenez "stop" et un nombre inférieur. Le correctif consiste alors à utiliser un prompt qui demande une réponse plus longue. Lorsque vous obtenez "length" et 32, la valeur propre à la requête a remplacé la valeur 512 enregistrée dans qwen3-capped. Cela montre que le serveur respecte les options définies par requête. Cela ne vous indique pas ce que votre application envoie. La recherche se poursuit donc côté client. Pour voir ce que le serveur reçoit lui-même, 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 nombres de tokens. Une valeur négative signifie « ne pas limiter, continuer à générer ». Une autre a signifié « remplir le contexte restant ». En octobre 2026, la référence Ollama Modelfile indique -1, soit une génération infinie, comme valeur par défaut. Les versions précédentes 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é. Pendant longtemps, la référence indiquait 128 comme valeur par défaut. Cette valeur a ensuite été remplacée par -1. De nombreux guides reprennent donc encore l’ancien nombre. Le comportement a également changé. Ollama v0.40.11, la version actuelle au 25 octobre 2026, transmet les modèles GGUF à un processus llama-server en amont qui nécessite une limite finie. Il remplace donc toute valeur négative, ainsi que toute limite supérieure à dix fois num_ctx, par dix fois num_ctx. « Infini » signifie donc 81,920 tokens pour le modèle qwen3-capped ci-dessus. -2 ne se comporte plus différemment de -1. Consultez la référence des paramètres du Modelfile correspondant à la version que vous utilisez, puis vérifiez le comportement avec le contrôle 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
Ollama est gratuit à exécuter sur une machine que vous contrôlez, donc la génération locale n’est jamais facturée au token. Une réponse longue se paie plutôt en temps. 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 passage sur les poids utilisés. Sur un VPS limité au CPU, ce passage est limité par la bande passante mémoire. Un token généré coûte donc beaucoup plus cher qu’un token du prompt. Ce passage doit lire chaque poids utilisé par le token : tous les poids dans un modèle dense, ou seulement les experts sélectionnés dans un modèle à mixture of experts comme Nemotron 3.5 Lightning, qui active environ 3B de ses 30B paramètres par token. Le nombre d’octets occupés par chaque poids fixe donc le plafond du débit de génération. C’est pourquoi un build q4 décode plus vite que le même modèle en q8 ou en fp16.
Demandez une réponse sans streaming et les chiffres sont immédiatement visibles :
"prompt_eval_count": 11,
"prompt_eval_duration": 13074791,
"eval_count": 18,
"eval_duration": 52479709Les 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 en octobre 2026 et non à une mesure effectuée sur un serveur particulier, 11 tokens de prompt ont pris environ 0.013 seconde, contre environ 0.052 seconde pour 18 tokens de sortie. Cela représente environ 1.2 milliseconde par token de prompt, contre 2.9 millisecondes par token de sortie. Ainsi, même pour une réponse d’une seule ligne, chaque token généré a coûté plus de deux fois plus cher que chaque token lu. Pour une réponse longue, c’est donc la sortie qui occupe l’essentiel du temps. Votre débit de génération correspond à eval_count divisé par eval_duration, après conversion en secondes. Il est utile de mesurer les tokens par seconde sur votre propre matériel une fois avant de modifier quoi que ce soit. 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 décoder rapidement, comme Nemotron 3.5 Lightning sur un VPS, peut récupérer une partie du temps qu’une limite basse cherche autrement à préserver.
Le calcul suffit à comprendre le reste. À 8 tokens par seconde, une réponse de 2,000 tokens monopolise la machine pendant plus de quatre minutes. Le modèle ne sait pas que vous vouliez seulement 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 agit sur le même coût. Certains modèles bouclent également et répètent une phrase jusqu’à ce qu’un mécanisme les arrête. Sans limite, cette requête monopolise un cœur jusqu’à atteindre dix fois num_ctx tokens, car le décalage du contexte empêche une fenêtre complète de l’arrêter. 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 utiliser toute la machine.
La sortie tronquée vient généralement de la limite, pas d’un modèle 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 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 la génération s’est terminée avant d’atteindre une limite, soit parce que le modèle a émis son jeton de fin de séquence, soit parce que la sortie correspondait à l’une des chaînes de votre option stop, qui termine la réponse à l’endroit de la correspondance. 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’un nombre inférieur signifie que la fenêtre de contexte s’est remplie en premier, ce qui ne peut se produire que si le déplacement du contexte est désactivé.
Avec le streaming, ces champs arrivent dans le dernier fragment, celui qui contient "done": true. De nombreuses bibliothèques clientes ignorent ce fragment et ne transmettent à votre code que le texte. C’est pourquoi la même troncature semble inexpliquée dans une application, mais évidente sous 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 d’y passer l’après-midi. Augmenter num_predict ne fait pas écrire davantage le modèle. Cette opération supprime seulement une limite supérieure. Si une réponse s’arrête à 200 tokens avec done_reason de stop, soit le modèle a décidé qu’elle était terminée, soit l’une de vos chaînes stop a correspondu ; une limite plus élevée ne change alors rien. Les réponses courtes avec stop indiquent un problème de prompt ou de chaîne d’arrêt. 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_reasondelengthcomme 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éfinit la quantité de contenu 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 générer dans une réponse. Il consomme du temps plutôt que de la mémoire, et aucune quantité n’est réservée à l’avance. Les tokens générés sont comptabilisés dans les deux valeurs. Avec le context shift désactivé, 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. Ajoutez PARAMETER num_predict 512 dans un Modelfile, puis utilisez ce modèle depuis un front-end de chat ou un agent de programmation : le client envoie son propre objet options, dont la valeur est prioritaire. ollama show --parameters affiche toujours votre valeur, car il lit le modèle enregistré et ne voit pas ce qui arrive via HTTP. Envoyez une requête avec curl en utilisant "options": {"num_predict": 32} et un prompt qui nécessite une réponse longue, puis consultez done_reason et eval_count. Un length avec un eval_count de 32 montre que la valeur de la requête a remplacé celle du modèle. Cela confirme que le serveur fonctionne correctement et oriente la recherche vers votre application. Un stop avec un nombre plus faible signifie seulement que le modèle a terminé plus tôt. Réessayez avec un prompt qui demande une réponse plus longue.
Comment savoir si ma sortie a été interrompue par num_predict ?
Envoyez la requête avec "stream": false et consultez done_reason. La valeur stop signifie que le modèle a terminé de lui-même ou que l’une de vos chaînes stop a mis fin à la génération. La valeur length signifie qu’il n’avait plus 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 s’est remplie en premier. En streaming, les deux champs arrivent dans le dernier chunk 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 octobre 2026, la référence Ollama Modelfile 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 après une longue période durant laquelle 128 était documenté. Dans Ollama v0.40.11, cette valeur par défaut sans limite, comme toute valeur négative, s’arrête en réalité à dix fois num_ctx. Les valeurs négatives servent de sentinelles plutôt que de compteurs. Les anciennes versions du même tableau indiquaient également -2 pour remplir 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 générer 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 ou l’une de vos chaînes stop a correspondu. Une limite plus élevée ne change alors 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 renvoie length.