Ollama num_predict: limite o tamanho da 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 a confusão custa tempo real de depuração.

num_ctx define quanto o modelo pode 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 de chave/valor 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 define 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 cruzam-se num ponto. Os tokens gerados entram na janela de contexto à medida que são produzidos. Por isso, 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. O número que permite distingui-los é eval_count, abordado 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 512

Depois, crie o modelo e leia o resultado:

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

ollama 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 prevalece e por que a sua parece ser ignorada

A ordem é curta. As opções enviadas com o pedido prevalecem sobre todas as outras. Uma linha PARAMETER num_predict no Modelfile do modelo é o valor de fallback usado quando o pedido não contém um valor. Sem nenhuma das duas, aplica-se o valor predefinido incorporado no Ollama.

/set parameter não é uma terceira regra. A sessão interativa é um cliente de API. Por isso, o valor definido nessa sessão é enviado como options desse pedido. É exatamente por isso que ele substitui o Modelfile durante a sessão.

Agora, o problema que isto explica. Você adiciona PARAMETER num_predict 512, recria o modelo e as respostas continuam a gerar milhares de tokens. A sua configuração está presente, e ollama show --parameters comprova isso. No entanto, ela é substituída em todos os pedidos, porque o cliente envia o seu próprio objeto options com o seu próprio valor, muitas vezes um número introduzido numa tela de configurações meses atrás e esquecido. ollama show lê o modelo armazenado. Ele não mostra o que chega por HTTP.

Comprove o comportamento no servidor com um comando. Envie um pedido que produza uma resposta longa, force 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'

Isso deve imprimir "length" e 32. Instale jq primeiro com sudo apt install -y jq, se estiver ausente. Uma resposta com "length" e 32 significa que o servidor respeita a opção e que a sua aplicação está enviando outro valor. Para ver o registro do próprio servidor sobre um pedido, reinicie-o com OLLAMA_DEBUG=1 no ambiente e monitore journalctl -u ollama -f enquanto a aplicação se 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, não como contagens. Um valor negativo significa "não limitar, continuar a gerar". Outro significava "preencher o contexto restante". Em agosto 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 esses valores foram alterados. Durante muito tempo, a referência documentou 128 como valor predefinido, até a entrada ser corrigida no final de 2024. Por isso, muitos guias ainda repetem o número antigo. Consulte a referência dos parâmetros do Modelfile correspondente à versão que realmente executa e confirme o comportamento com a verificação eval_count acima. Um valor que verificou no seu próprio sistema é mais confiável do que um valor lido em qualquer outro lugar, incluindo este texto.

Por que o comprimento da saída é o principal custo numa VPS apenas com CPU

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 da saída são produzidos um de cada vez, e cada um exige uma passagem completa pelos pesos do modelo. Numa VPS apenas com CPU, essa passagem é limitada pela largura de banda da memória, por isso um token gerado custa muito mais do que um token do prompt. Como essa passagem tem de ler todos os pesos, o número de bytes ocupado por cada peso define o limite 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 valores ficam visíveis:

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

As durações estão em nanossegundos. Nesse bloco, que é a resposta de exemplo publicada na documentação da API do Ollama e não uma medição de nenhum servidor específico, 26 tokens do prompt demoraram cerca de 0.1 segundos, enquanto 237 tokens da saída demoraram cerca de 4.3 segundos. 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 fazê-lo uma vez antes de ajustar qualquer outra coisa. Essa taxa depende tanto do modelo como da máquina. Portanto, se as respostas longas forem o custo real, um modelo concebido para uma descodificação rápida, como Nemotron 3.5 Lightning numa VPS, recupera parte do tempo que um limite baixo estaria a poupar.

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 um parágrafo. Um modelo de raciocínio usa parte desse orçamento a pensar antes de escrever uma palavra do que pediu. 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 ciclo e repetem uma frase até algo os parar. Sem um limite, esse único pedido mantém um núcleo ocupado até a janela de contexto ficar cheia. num_predict é a definição que estabelece esse limite. Isso é especialmente importante numa pequena VPS com Ollama autoalojado, onde um pedido longo pode ocupar a máquina inteira.

A saída truncada geralmente é o limite, não 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. Leia primeiro a resposta.

done_reason significa que o modelo respondeu diretamente à pergunta. stop significa que o modelo terminou por iniciativa própria, emitindo o token de fim de sequência ou correspondendo a uma das strings na opção stop. length significa que a geração foi interrompida porque o espaço disponível acabou. Quando vir length, compare eval_count com o seu limite: uma correspondência exata significa que num_predict interrompeu a geração, enquanto um número menor significa que a janela de contexto ficou cheia primeiro.

Durante o streaming, esses campos chegam no bloco final, 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 ao usar curl. Se uma biblioteca estiver a ocultar essa informação, envie um pedido com curl para saber o que o servidor realmente devolveu.

Há ainda um ponto que 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 tinha terminado, e um limite maior não altera nada. Respostas curtas com stop são um problema de prompting. Respostas curtas com length são 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_reason de length como 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, portanto define quanto o modelo pode ler: o prompt mais tudo o que foi produzido até ao momento. Consome memória, porque a cache de chave/valor cresce com esse tamanho. num_predict define quantos tokens o modelo pode escrever numa resposta. Consome tempo, não memória, e nada é reservado antecipadamente. Os tokens gerados contam para ambos, portanto uma resposta pode ser interrompida por qualquer um deles.

Por que motivo a minha definição de num_predict parece ser ignorada?

Porque um valor enviado com o pedido substitui o valor armazenado no modelo. Coloque PARAMETER num_predict 512 num Modelfile, use depois esse modelo a partir de um frontend de chat ou de um agente de programação, e o cliente enviará o seu próprio objeto options, cujo valor numérico prevalece. ollama show --parameters continua a mostrar o seu valor, porque lê o modelo armazenado e não consegue ver o que chega por HTTP. Envie um pedido com curl usando "options": {"num_predict": 32} e confirme que eval_count regressa como 32. Isto confirma que o próprio servidor está a funcionar corretamente e desloca a investigação para a sua aplicação.

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 decisão própria. Um valor de length significa que ficou sem espaço. 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, que muitas bibliotecas de cliente descartam antes de o código os poder ler.

Qual é o valor predefinido de num_predict?

Leia-o na sua própria instalação, em vez de confiar num artigo. Em agosto de 2026, a referência do Modelfile do Ollama indica -1 como valor predefinido. Isto significa que a geração não tem limite, e essa entrada foi corrigida no final de 2024, depois de anos a documentar 128. Os valores negativos são sentinelas, não contagens, e as 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 correspondente à sua versão e confirme-a com ollama show --parameters e um pedido curl.

Aumentar num_predict faz o modelo escrever respostas mais longas?

Não. Apenas remove um limite superior. Se uma resposta terminar com done_reason de stop, o modelo decidiu que estava concluída, e um limite maior não altera o 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 regressar como length.