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. Ela contabiliza apenas os tokens de saída, por isso o prompt não é 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 distintos, 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 aumenta o 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 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 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 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 atingiu o seu limite. O Ollama apresenta length nos dois casos. O número que permite distingui-los é eval_count, explicado mais abaixo.

Defina uma vez com um Modelfile

Um Modelfile incorpora o valor num modelo que você cria. Escreva o ficheiro:

FROM qwen3:8b
PARAMETER num_ctx 8192
PARAMETER num_predict 512

Depois crie o modelo e leia de volta o que foi criado:

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

ollama show --parameters imprime 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 imprime a definição completa. Esta é também a forma mais rápida de copiar os parâmetros que um modelo existente já inclui.

Esta é a camada correta para um valor que pretende que todos os chamadores herdem. É a camada errada se espera que o valor seja final, porque não é.

Defina-o por pedido no objeto de opções

Todos os endpoints de geração recebem um objeto options, e num_predict fica dentro dele:

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 se aplica a mais nada. Esta é a camada usada pelas suas ferramentas: um frontend 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 /set parameter

Dentro de ollama run, a sessão interativa define opções para o restante da 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 entrou em vigor. O valor permanece ativo 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 fizer aqui com /set chega a qualquer outro cliente.

Qual configuração prevalece e por que a sua parece ser ignorada

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

/set parameter não é uma terceira regra. A sessão interativa é um cliente de API, portanto o valor definido nela é enviado como options dessa requisição. É exatamente por isso que ele substitui o Modelfile durante a sessão.

Agora, o problema que isso explica. Você adiciona PARAMETER num_predict 512, recria o modelo e as respostas continuam chegando a milhares de tokens. A configuração está presente, e ollama show --parameters comprova isso. Ela está sendo substituída em todas as requisições porque o cliente envia o próprio objeto options com seu próprio valor, muitas vezes um número que você digitou numa tela de configurações meses atrás e esqueceu. ollama show lê o modelo armazenado. Ele não mostra o que chega por HTTP.

Comprove o comportamento do servidor com um único comando. Envie uma requisição 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 algo diferente. Para ver o registo do próprio servidor sobre uma requisição, reinicie-o com OLLAMA_DEBUG=1 no ambiente e monitorize journalctl -u ollama -f enquanto a sua 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 e não como contagens. Um valor negativo significa «não limitar este valor; continuar a gerar». Outro significava «preencher o contexto restante». Em agosto de 2026, a referência do Ollama Modelfile indica -1 como predefinição, para geração infinita, e versões anteriores da mesma tabela também indicavam -2 para preencher o contexto.

Considere tudo isto dependente da versão, porque estes 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 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 nesta publicação.

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

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 com CPU apenas, essa passagem é limitada pela largura de banda da memória. Por isso, cada token gerado custa muito mais do que um token do prompt.

Peça uma resposta sem streaming e os números ficam claros:

"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 um 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, convertida para segundos. Vale a pena medir os tokens por segundo no seu próprio hardware 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 normalmente poupa.

A aritmética trata do resto. A 8 tokens por segundo, uma resposta com 2,000 tokens mantém a máquina ocupada durante mais de quatro minutos, e o modelo não sabe que pretendia apenas um parágrafo. Alguns modelos também entram em loop e repetem uma frase até que algo os pare. Sem limite, esse único pedido mantém um core ocupado até a janela de contexto se esgotar. num_predict é a definição que limita esse valor. Isto é especialmente importante numa VPS Ollama autoalojada pequena, onde um único pedido longo pode ocupar a máquina inteira.

A saída truncada geralmente indica o limite, não um modelo avariado

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 a resposta responde diretamente à pergunta. stop significa que o modelo terminou por iniciativa própria, emitindo o seu 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 ficou sem espaço. 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 inferior significa que a janela de contexto ficou cheia primeiro.

Durante o streaming, estes campos chegam no bloco final, aquele que contém "done": true. Muitas bibliotecas de 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 essa informação, envie um pedido com curl para descobrir 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 conversas interativas, não defina um limite e pressione Ctrl+C para interromper uma resposta que não termina. De qualquer forma, estará a acompanhar o ecrã.
• Para qualquer processo automatizado, defina um valor. Uma geração sem limite dentro de um ciclo pode fazer com que um trabalho em lote que deveria demorar dez minutos ainda esteja a ser executado na manhã seguinte.
• Para saídas estruturadas, defina o limite acima do maior documento válido esperado. Depois, trate done_reason de length como um erro grave e tente novamente, em vez de analisar o conteúdo recebido.
• Para um agente de programação, o valor deve ficar 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 fazem a tokenização de formas diferentes. Por isso, um valor que é 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 e tudo o que foi produzido até ao momento. Consome memória, porque a cache de chave/valor cresce com esse valor. 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 dos limites.

Porque é que a minha configuração 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 esse modelo a partir de um front-end de chat ou de um agente de programação, e o cliente enviará o seu próprio objeto options, cujo número 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 é devolvido como 32. Isto confirma que o próprio servidor está a funcionar corretamente e direciona a investigação para a 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 iniciativa 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 foi preenchida primeiro. Durante o streaming, ambos os campos chegam no bloco final com "done": true. Muitas bibliotecas de cliente descartam esse bloco antes de ele chegar ao seu código.

Qual é o valor predefinido de num_predict?

Leia esse valor na sua própria instalação, em vez de usar o valor indicado num artigo. Em agosto de 2026, a referência do Modelfile do Ollama indica -1 como predefinição, o que significa que a geração não tem limite. Essa entrada foi corrigida no final de 2024, depois de anos a documentar 128. Os valores negativos são sentinelas, não contagens, e 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 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 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 devolver length.