Ollama num_predict: limite o tamanho da resposta
Entenda como num_predict limita os tokens de saída no Ollama, onde definir a opção, qual configuração vence e como interpretar done_reason na resposta.
O que num_predict faz no Ollama
num_predict é a opção do Ollama que limita o número de tokens que um modelo pode gerar numa única resposta. A contagem inclui apenas os tokens de saída, por isso o prompt nunca é contabilizado nesse limite. Quando o modelo atinge o limite, a geração para nesse ponto, por vezes a meio de uma palavra, e a resposta é devolvida com done_reason definido como length.
Essa é toda a funcionalidade. A dificuldade está no facto de o Ollama permitir definir o valor em três locais diferentes, e a configuração mais próxima do pedido tem precedência. Quase todos os relatos de que «num_predict não faz nada» resultam de uma camada substituir silenciosamente outra.
num_predict não é num_ctx
Estas duas opções são confundidas mais do que qualquer outro par no Ollama, e essa confusão consome tempo real de diagnóstico.
num_ctx indica quanto o modelo consegue ler. É o tamanho da janela de contexto, que contém o prompt e tudo o que foi produzido até ao momento. Aumentá-lo consome memória, porque a cache key/value que o modelo mantém para esses tokens cresce com a janela. Dimensionar num_ctx para o seu hardware é uma tarefa separada, com os seus próprios modos de falha.
num_predict indica quanto o modelo vai escrever. É uma regra de paragem, não uma alocação. Aumentá-lo consome tempo de execução, não RAM, e nada é reservado antecipadamente.
As duas opções encontram-se num único ponto. Os tokens gerados entram na janela de contexto à medida que são produzidos. No Ollama v0.40.11, o context shift está ativado por predefinição na maioria dos modelos, por isso uma janela cheia remove os tokens mais antigos e a geração continua. Com o shift desativado, porque o pedido envia "shift": false ou porque o modelo não suporta shifting, uma resposta também pode parar porque a janela ficou cheia, e não porque o limite foi atingido. O Ollama comunica length nos dois casos, por isso o número que os distingue é eval_count, explicado mais abaixo.
Defina uma vez com um Modelfile
Um Modelfile incorpora o valor num modelo que cria. Escreva o ficheiro:
FROM qwen3:8b
PARAMETER num_ctx 8192
PARAMETER num_predict 512Depois, crie o modelo e leia o resultado:
ollama create qwen3-capped -f Modelfile
ollama show --parameters qwen3-cappedollama show --parameters apresenta uma linha por parâmetro armazenado, com o respetivo valor. Se num_predict não aparecer nessa saída, o modelo não tem um limite incorporado e aplica-se o valor predefinido do próprio Ollama. ollama show --modelfile qwen3-capped apresenta a definição completa. Esta é também a forma mais rápida de copiar os parâmetros que um modelo existente já inclui. Criar um modelo com limite desta forma quase não ocupa espaço adicional em disco, porque a nova entrada reutiliza os blobs de pesos que o modelo base já descarregou, em vez de os copiar. É útil saber onde o Ollama mantém esses blobs antes de o disco root de uma VPS ficar cheio.
Esta é a camada correta para um valor que todos os chamadores devem herdar. É a camada errada se espera que o valor seja definitivo, porque não é.
Defina-o por pedido no objeto de opções
Cada endpoint de geração aceita um objeto options, e num_predict é incluído nesse objeto:
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 a mesma chave options, com o mesmo significado. Um valor definido aqui aplica-se apenas a essa chamada. Não afeta mais nada. Esta é a camada usada pelas suas ferramentas: uma interface de chat, um script, um wrapper de SDK ou um agente de programação. Todas enviam um objeto options, mesmo que não apresentem uma caixa para o configurar.
Defina-o para uma sessão com o parâmetro /set
Dentro de ollama run, a sessão interativa define opções para o restante dessa sessão:
>>> /set parameter num_predict 256
>>> /show parameters/show parameters mostra o que a sessão enviará na próxima mensagem, sendo a forma mais rápida de confirmar que uma alteração foi aplicada. O valor permanece até escrever /bye. Para o manter, /save qwen3-capped grava a sessão atual, incluindo os parâmetros, como um novo modelo. Nada do que /set aqui chega a qualquer outro cliente.
Qual configuração vence e por que a sua parece ser ignorada
A ordem é simples. As opções enviadas com o pedido têm prioridade sobre tudo o resto. Uma linha PARAMETER num_predict no Modelfile do modelo é o valor de fallback usado quando o pedido não contém nenhum valor. Sem nenhuma das duas opções, aplica-se o valor predefinido integrado no Ollama.
/set parameter não é uma terceira regra. A sessão interativa é um cliente da API. Por isso, o valor definido nessa sessão é enviado como options desse pedido. É exatamente por isso que substitui o Modelfile durante a sessão.
Isto explica a falha. Adiciona PARAMETER num_predict 512, reconstrói o modelo e as respostas continuam a atingir milhares de tokens. A configuração está presente, e ollama show --parameters prova isso. Ela está a ser substituída em todos os pedidos, porque o cliente envia o seu próprio objeto options com o seu próprio número. Muitas vezes, esse número foi introduzido numa página de definições há meses e ficou esquecido. ollama show lê o modelo armazenado. Não mostra o que chega por HTTP.
Comprove o comportamento do servidor com um comando. Envie um pedido que produza uma resposta longa, defina um limite baixo e leia dois 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'Uma resposta detalhada ultrapassa facilmente 32 tokens, por isso espere "length" e 32. Instale jq primeiro com sudo apt install -y jq, se estiver em falta. O valor 32 não é garantido, porque eval_count é apenas o número de tokens de saída que o servidor gerou efetivamente. Se o modelo terminar cedo, obterá "stop" e uma contagem menor. Nesse caso, a correção é usar um prompt que peça uma resposta mais longa. Quando obtiver "length" e 32, o valor definido no próprio pedido teve prioridade sobre o valor 512 armazenado em qwen3-capped. Isto mostra que o servidor respeita opções específicas de cada pedido. Não mostra o que a sua aplicação envia, por isso a investigação passa para o cliente. Para consultar o registo do próprio servidor sobre um pedido, reinicie-o com OLLAMA_DEBUG=1 no ambiente e monitorize journalctl -u ollama -f enquanto a aplicação comunica com ele.
Os valores negativos e os números que não deve copiar
num_predict também aceita valores negativos, que funcionam como sentinelas e não como contagens. Um valor negativo significa "não limitar, continuar a gerar". Outro significava "preencher o contexto restante". Em outubro de 2026, a referência do Ollama Modelfile indica -1 como valor predefinido, para geração infinita, e versões anteriores da mesma tabela também indicavam -2 para preencher o contexto.
Considere tudo isso dependente da versão, porque estes valores foram alterados. Durante muito tempo, a referência documentou 128 como valor predefinido, antes de corrigir a entrada para -1. Por isso, muitos guias ainda repetem o número antigo. O comportamento também foi alterado. O Ollama v0.40.11, a versão atual em 25 de outubro de 2026, entrega os modelos GGUF a um processo llama-server upstream que requer um limite finito. Por isso, substitui qualquer valor negativo e qualquer limite superior a dez vezes num_ctx por dez vezes num_ctx. Assim, "infinito" significa 81,920 tokens para o modelo qwen3-capped acima, e -2 já não se comporta de forma diferente de -1. Consulte a referência dos parâmetros do Modelfile correspondente à versão que realmente executa e confirme depois o comportamento com a verificação eval_count acima. Um valor que verificou no seu próprio sistema é mais fiável do que um valor lido em qualquer outro lugar, incluindo neste artigo.
Por que o comprimento da saída é o principal custo numa VPS apenas com CPU
Ollama é gratuito para executar numa máquina sob o seu controlo, pelo que a geração local nunca é contabilizada e uma resposta longa é paga apenas em tempo. A geração tem duas fases com velocidades muito diferentes. Os tokens do prompt são avaliados em lotes, muitos de cada vez. Os tokens de saída são produzidos um de cada vez, e cada um requer uma passagem pelos pesos que utiliza. Numa VPS apenas com CPU, essa passagem é limitada pela largura de banda da memória, pelo que cada token gerado custa muito mais do que um token do prompt. Como essa passagem tem de ler todos os pesos utilizados pelo token (todos num modelo denso, apenas os especialistas encaminhados num modelo de mistura de especialistas como Nemotron 3.5 Lightning, que ativa cerca de 3B dos seus 30B parâmetros por token), o número de bytes ocupado por cada peso define o limite superior da sua taxa de tokens. É por isso que uma build q4 descodifica mais depressa do que o mesmo modelo em q8 ou fp16.
Peça uma resposta sem streaming e os números ficam visíveis:
"prompt_eval_count": 11,
"prompt_eval_duration": 13074791,
"eval_count": 18,
"eval_duration": 52479709As durações estão em nanossegundos. Nesse bloco, que corresponde à resposta de exemplo publicada na documentação da API do Ollama em outubro de 2026, e não a uma medição de um servidor específico, 11 tokens do prompt demoraram cerca de 0.013 segundos, enquanto 18 tokens da saída demoraram cerca de 0.052 segundos. Isso corresponde aproximadamente a 1.2 milissegundos por token do prompt contra 2.9 milissegundos por token da saída. Assim, mesmo numa resposta de uma linha, cada token gerado custou mais do dobro de cada token lido. Numa resposta longa, é o lado da saída que ocupa o tempo de execução. A sua taxa de geração é eval_count dividida por eval_duration e convertida para segundos. Medir os tokens por segundo no seu próprio hardware é útil fazer uma vez antes de ajustar qualquer outra coisa. Essa taxa depende tanto do modelo como da máquina. Por isso, se as respostas longas forem o custo real, um modelo concebido para descodificação rápida, como Nemotron 3.5 Lightning numa VPS, recupera parte do tempo que um limite baixo pretende proteger.
A aritmética explica o resto. A 8 tokens por segundo, uma resposta de 2,000 tokens mantém a máquina ocupada durante mais de quatro minutos, e o modelo não sabe que queria apenas um parágrafo. Um modelo de raciocínio utiliza parte desse orçamento para pensar antes de escrever uma palavra do pedido. Esse raciocínio também é gerado um token de cada vez, como tudo o resto. Por isso, o esforço de raciocínio que solicita é outra variável do mesmo custo. Alguns modelos também entram em loop e repetem uma frase até algo os interromper. Sem um limite, esse único pedido mantém um núcleo ocupado até atingir dez vezes num_ctx tokens, porque a mudança de contexto impede que o fim de uma janela completa o interrompa. num_predict é a definição que estabelece esse limite. Isto é especialmente importante numa pequena VPS Ollama alojada por si onde um pedido longo ocupa toda a máquina.
A saída truncada normalmente é causada pelo limite, não por uma falha do modelo
Os sintomas parecem indicar uma falha do modelo. A resposta termina a meio de uma frase. O JSON não pode ser analisado porque a chave de fecho nunca chegou. A reação imediata é culpar o modelo ou a quantização. Primeiro, leia a resposta.
done_reason significa que a resposta à pergunta foi concluída diretamente. stop significa que a geração terminou antes de atingir qualquer limite, porque o modelo emitiu o seu token de fim de sequência ou porque a saída correspondeu a uma das strings na opção stop, que termina a resposta no ponto em que a correspondência ocorre. length significa que a geração foi interrompida por falta de espaço. Quando vir length, compare eval_count com o seu limite: uma correspondência exata significa que num_predict interrompeu a geração, e um número menor significa que a janela de contexto ficou cheia primeiro, o que só pode acontecer com o deslocamento de contexto desativado.
Ao transmitir a resposta, esses campos chegam no bloco final, aquele que contém "done": true. Muitas bibliotecas cliente descartam esse bloco e entregam ao seu código apenas o texto. Por isso, a mesma truncagem parece inexplicável dentro de uma aplicação e evidente em curl. Se uma biblioteca estiver a ocultar esse campo, envie um pedido com curl para descobrir o que o servidor realmente informou.
Outro ponto evita perder uma tarde. Aumentar num_predict não faz o modelo escrever mais. Apenas remove um limite superior. Se uma resposta terminar em 200 tokens com done_reason de stop, o modelo decidiu que terminou ou uma das suas strings stop correspondeu, e aumentar o limite não altera nada. Respostas curtas com stop indicam um problema no prompt ou nas strings de paragem. Respostas curtas com length indicam um problema de limite.
Escolher um valor
- Para chat interativo, não defina um limite e prima Ctrl+C para parar uma resposta que esteja a ser gerada indefinidamente. De qualquer forma, está a acompanhar o ecrã.
- Para qualquer tarefa automatizada, defina-o. Uma geração sem limite dentro de um ciclo é a razão pela qual um trabalho em lote que deveria demorar dez minutos ainda está em execução na manhã seguinte.
- Para saída estruturada, defina o limite acima do maior documento válido esperado. Trate
done_reasondelengthcomo um erro grave e repita o pedido, em vez de analisar o conteúdo recebido. - Para um agente de programação, o valor deve estar na configuração do próprio agente, porque o agente envia as suas próprias opções em cada pedido. Configurar um agente de programação para usar o Ollama explica onde essas definições ficam.
O limite conta tokens, não palavras nem caracteres. Por isso, não o estime. Gere uma resposta representativa sem limite, leia eval_count e defina o limite confortavelmente acima desse valor. As famílias de modelos usam tokenizações diferentes. Por isso, um valor que seja suficiente para um modelo Llama pode truncar a mesma resposta de um modelo Qwen 3 no mesmo VPS.
FAQ
Qual é a diferença entre num_ctx e num_predict no Ollama?
num_ctx é o tamanho da janela de contexto. Ele define quanto o modelo pode ler: o prompt e tudo o que foi produzido até ao momento. O consumo de memória aumenta, porque a cache de chave/valor cresce com esse tamanho. num_predict define quantos tokens o modelo pode escrever numa resposta. O custo é principalmente de tempo, não de memória, e nada é reservado antecipadamente. Os tokens gerados contam para ambos. Com a deslocação de contexto desativada, uma resposta pode ser interrompida por qualquer um dos dois limites.
Por que motivo a minha definição de num_predict parece ser ignorada?
Porque um valor enviado com o pedido substitui o valor guardado no modelo. Coloque PARAMETER num_predict 512 num Modelfile, use esse modelo a partir de uma interface de chat ou de um agente de programação, e o cliente enviará o seu próprio objeto options. É esse número que prevalece. ollama show --parameters continua a mostrar o seu valor, porque lê o modelo guardado e não consegue ver o que chega através de HTTP. Envie um pedido com curl usando "options": {"num_predict": 32} e um prompt que exija uma resposta longa. Depois, leia done_reason e eval_count. Um length com um eval_count de 32 mostra que o valor do pedido substituiu o valor guardado. Isso confirma que o servidor está a funcionar corretamente e que a investigação deve continuar na aplicação. Um stop com um valor menor significa apenas que o modelo terminou primeiro. Nesse caso, repita o teste com um prompt que peça mais conteúdo.
Como posso saber se a minha saída foi interrompida por num_predict?
Envie o pedido com "stream": false e leia done_reason. Um valor de stop significa que o modelo terminou por iniciativa própria ou que uma das suas strings stop terminou a geração. Um valor de length significa que o espaço disponível terminou. Compare depois eval_count com o seu limite. Se forem exatamente iguais, num_predict interrompeu a geração. Se eval_count for menor, a janela de contexto ficou cheia primeiro. Durante o streaming, ambos os campos chegam no bloco final com "done": true. Muitas bibliotecas de cliente descartam esses campos antes de o código os conseguir ler.
Qual é o valor predefinido de num_predict?
Leia esse valor na sua própria instalação, em vez de o obter de um artigo. Em outubro de 2026, a referência de Modelfile do Ollama indica -1 como valor predefinido. Isso significa que a geração não tem um limite definido. Essa entrada foi corrigida depois de um longo período em que 128 era documentado. No Ollama v0.40.11, esse valor predefinido sem limite, tal como qualquer valor negativo, na prática termina após dez vezes num_ctx. Os valores negativos são indicadores especiais, não contagens. Versões mais antigas da mesma tabela também indicavam -2 para preencher o contexto restante. Consulte a referência dos parâmetros do Modelfile da sua versão. Depois, confirme o valor com ollama show --parameters e um pedido curl.
Aumentar num_predict faz o modelo escrever respostas mais longas?
Não. Isso apenas remove um limite superior. Se uma resposta terminar com done_reason de stop, o modelo decidiu que terminou ou uma das suas strings stop correspondeu. Um limite maior não altera esse resultado. Nesse caso, o comprimento depende do prompt. Peça uma estrutura específica, um número de secções ou um nível de detalhe definido. Aumente num_predict apenas quando done_reason devolver length.