Ollama num_predict 设置:如何限制模型输出长度
Ollama 的 num_predict 参数用于限制单次生成的最大 token 数。本文详细解析 Modelfile、API 请求与运行参数的优先级规则,并教你如何通过响应中的 done_reason 字段判断生成是否因达到上限而停止。
Ollama 中的 num_predict
num_predict 是 Ollama 中用于限制模型单次响应最多生成多少个 token 的选项。它只统计输出 token,因此不会将提示词计入其中。模型达到上限后,生成会立即停止,有时会停在单词中间;此时响应中的 done_reason 会设置为 length。
这就是该功能的全部内容。难点在于,Ollama 提供了 3 个独立位置来设置此值,并且离请求最近的设置优先。几乎所有“num_predict 不起作用”的报告,原因都是某一层在无提示的情况下覆盖了另一层的设置。
num_predict 不是 num_ctx
在 Ollama 中,这两个选项比其他任何选项组合都更容易混淆,而且这种混淆会浪费大量实际排障时间。
num_ctx 表示模型可以读取多少内容。它是上下文窗口的大小,包含提示词以及截至当前已经生成的全部内容。提高该值会增加内存开销,因为模型为这些 token 保留的键值缓存会随窗口增大。根据硬件确定 num_ctx 是另一项独立工作,也有其自身的故障模式。
num_predict 表示模型将写入多少内容。它是停止规则,而不是内存分配。提高该值增加的是实际运行时间,而不是 RAM 占用,并且不会预先预留资源。
这两个值会在一个地方发生关联。生成的 token 会在生成过程中进入上下文窗口。在 Ollama v0.40.11 中,大多数模型默认启用上下文移动,因此窗口填满后会丢弃较早的 token,生成过程会继续。若关闭上下文移动,或者请求发送了 "shift": false,或者模型不支持上下文移动,回复也可能因为窗口已满而停止,而不是因为达到你的上限而停止。Ollama 在这两种情况下都会报告 length,因此用于区分二者的数值是 eval_count,下文将进一步介绍。
通过 Modelfile 一次性设置
Modelfile 会将该值写入您创建的模型。创建文件:
FROM qwen3:8b
PARAMETER num_ctx 8192
PARAMETER num_predict 512然后构建模型,并读取构建结果:
ollama create qwen3-capped -f Modelfile
ollama show --parameters qwen3-cappedollama show --parameters 会逐行输出每个已存储参数及其值。如果输出中缺少 num_predict,说明该模型未内置上限,Ollama 会使用自身的默认值。ollama show --modelfile qwen3-capped 会输出完整定义。这也是复制现有模型自带参数的最快方式。使用此方法创建带上限的模型几乎不会额外占用磁盘空间,因为新条目会复用基础模型已下载的权重 blob,而不是复制这些 blob。在 VPS 的 root 磁盘空间耗尽之前,最好了解 Ollama 保存这些 blob 的位置。
如果希望所有调用方都继承某个值,应在这一层设置它。如果希望该值不可被覆盖,则不应在这一层设置,因为它并非最终值。
在选项对象中按请求设置
每个生成端点都接收一个 options 对象,num_predict 放在该对象中:
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 使用含义相同的 options 键。这里设置的值只对当前调用生效,不影响其他调用。这是工具使用的配置层:聊天前端、脚本、SDK 包装器或编码代理。无论界面是否显示对应输入框,它们都会发送一个 options 对象。
使用 /set 参数为单个会话设置
在 ollama run 中,交互式会话会为当前会话的剩余时间设置选项:
>>> /set parameter num_predict 256
>>> /show parameters/show parameters 会显示会话在下一条消息中发送的内容,因此这是确认更改是否生效的最快方法。该值会一直保留,直到您输入 /bye。要保留该设置,请使用 /save qwen3-capped 将当前会话(包括参数)写入为新模型。在此处通过 /set 进行的任何操作都不会影响其他客户端。
哪个设置生效,以及为什么您的设置看起来被忽略
顺序很简单。随请求发送的选项优先级最高。模型的 Modelfile 中的 PARAMETER num_predict 行是在请求未提供值时使用的后备设置。如果两者都没有设置,则使用 Ollama 的内置默认值。
/set parameter 不是第三条规则。交互式会话是 API 客户端,因此您在那里设置的值会作为该请求的 options 发送。这正是它会在该会话中覆盖 Modelfile 的原因。
现在说明由此导致的故障。您添加 PARAMETER num_predict 512,重新构建模型,但回复仍然运行到数千个 token。您的设置确实存在,ollama show --parameters 也证明了这一点。但每个请求都会覆盖它,因为客户端会发送自己的 options 对象,其中包含自己的数值。这个数值通常是您几个月前在设置界面中输入的,后来忘记了。ollama show 读取存储的模型。它无法显示通过 HTTP 接收到的内容。
使用一条命令证明服务器端的行为。发送一个会生成长回复的请求,将上限强制设为较低值,然后读取两个字段:
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'详细回复会远远超过 32 个 token,因此应看到 "length" 和 32。如果缺少 jq,请先使用 sudo apt install -y jq 安装。32 并非固定结果,因为 eval_count 只是服务器实际生成的输出 token 数量。如果模型提前结束,您会得到 "stop" 和更小的计数;此时应修改提示词,要求生成更多内容。如果得到 "length" 和 32,说明请求自身的值覆盖了 qwen3-capped 中存储的 512,这证明服务器支持按请求设置选项。这无法告诉您应用实际发送了什么,因此接下来应检查客户端。要查看服务器对请求的记录,请在环境中使用 OLLAMA_DEBUG=1 重启服务器,并在应用与服务器通信时监控 journalctl -u ollama -f。
负值以及不应照抄的数字
num_predict 也接受负值,但负值表示特殊标记,而不是计数。其中一个负值表示“不要限制,继续生成”。另一个负值曾表示“填满剩余上下文”。截至 October 2026,Ollama Modelfile 参考文档将默认值列为 -1,表示无限生成;同一表格的早期版本还曾列出 -2,表示填满上下文。
请将这些内容视为版本相关信息,因为它们发生过变化。很长一段时间内,参考文档将默认值记为 128,之后才更正为 -1,因此许多指南仍在重复旧数字。行为也发生了变化。Ollama v0.40.11 是 October 25, 2026 的当前版本。它会将 GGUF 模型交给上游 llama-server 进程,而该进程需要有限的预算。因此,Ollama 会将任何负值,以及任何超过 num_ctx 十倍的上限,替换为 num_ctx 的十倍。因此,对于上面的 qwen3-capped 模型,“无限”实际表示 81,920 个 token,而 -2 的行为不再与 -1 不同。请阅读与您实际运行版本对应的 Modelfile 参数参考,然后使用上面的 eval_count 检查确认行为。在您自己的主机上验证过的值,比您从任何地方读到的值都更可靠,包括本文中的值。
为什么输出长度是纯 CPU VPS 上的主要成本
Ollama 可在您控制的机器上免费运行,因此本地生成不会按量计费;回答越长,付出的只是更多时间。生成分为两个速度差异很大的阶段。提示词 token 会批量处理,一次处理多个。输出 token 则逐个生成,每个 token 都需要遍历其使用的权重。在仅使用 CPU 的 VPS 上,这一过程受内存带宽限制,因此生成一个 token 的成本远高于处理一个提示词 token。因为这一过程必须读取该 token 使用的全部权重(稠密模型会读取全部权重;对于 Nemotron 3.5 Lightning 这类混合专家模型,则只读取路由到的专家权重;该模型每个 token 约激活 30B 个参数中的 3B 个),每个权重所占的字节数决定了 token 速率的上限。这就是为什么 q4 构建的解码速度快于同一模型的 q8 或 fp16 版本。
要求不使用流式传输的响应,相关数字会直接显示:
"prompt_eval_count": 11,
"prompt_eval_duration": 13074791,
"eval_count": 18,
"eval_duration": 52479709持续时间的单位是纳秒。在这段数据中,样例响应来自 Ollama API 文档,截至 October 2026;它不是任何特定服务器的测量结果。11 个提示词 token 用时约 0.013 秒,18 个输出 token 用时约 0.052 秒。这相当于每个提示词 token 约 1.2 毫秒,而每个输出 token 约 2.9 毫秒。因此,即使只有一行回复,每个生成的 token 成本也超过每个读取的 token 的两倍;对于较长的回答,占用时间的主要部分是输出。您自己的生成速率是将 eval_count 除以 eval_duration 后换算为秒,在自己的硬件上测量每秒 token 数值得在进行其他调优前完成一次。该速率取决于模型和机器,因此如果长回答才是真正的成本,选择针对快速解码构建的模型,例如VPS 上的 Nemotron 3.5 Lightning,可以收回低上限原本节省的部分时间。
剩下的只需计算即可。在每秒 8 个 token 的速度下,一个 2,000 token 的回答会让机器持续忙碌超过 4 分钟,而模型并不知道您只想要一个段落。推理模型会先用部分预算进行思考,然后才写出您要求的内容;这部分思考和其他内容一样,都是逐个 token 生成的。因此,您要求的推理工作量也会影响同一项成本。有些模型还会循环重复某个短语,直到某个条件停止它们。如果没有上限,单个请求会持续占用一个 CPU 核心,直到达到 num_ctx 的 10 倍 token 数,因为上下文转移会阻止完整窗口结束该请求。num_predict 是用于限制它的设置。在小型自托管 Ollama VPS 上,这一点尤其重要,因为一个长请求可能占用整台机器。
输出截断通常是由于达到上限,而非模型损坏
症状看起来像是模型故障。回答在句子中间停止。JSON 无法解析,因为缺少结束括号。第一反应通常是归咎于模型或量化。请先阅读响应内容。
done_reason 直接回答了问题。stop 表示生成在达到任何限制之前结束,原因要么是模型输出了序列结束标记,要么是输出匹配了 stop 选项中的字符串,该选项会在匹配位置结束回复。length 表示生成因空间不足而被截断。当看到 length 时,请将 eval_count 与您的上限进行比较:数值完全相等意味着 num_predict 停止了生成,数值较小则意味着上下文窗口已满(这种情况仅在关闭上下文偏移时发生)。
使用流式传输时,这些字段会出现在最后一个数据块中,即携带 "done": true 的那个块。许多客户端库会丢弃该块,只将文本传递给您的代码,这就是为什么同样的截断在应用程序中看起来无法解释,而在 curl 下却显而易见的原因。如果库隐藏了这些信息,请发送一个带有 curl 的请求,以查明服务器的真实响应。
另一点建议可以避免浪费时间。提高 num_predict 不会使模型写得更多。它只是移除了上限。如果回答在 200 个 token 处结束,且 done_reason 为 stop,则说明模型认为已完成或匹配了您的 stop 字符串,此时增大上限没有任何作用。带有 stop 的简短回答是提示词或停止字符串的问题。带有 length 的简短回答则是上限设置的问题。
选择数值
- 对于交互式聊天,不要设置上限;按 Ctrl+C 可停止失控的回复。因为您始终在查看屏幕。
- 对于任何脚本任务,都应设置上限。在循环中进行不限长度的生成,会导致本应运行十分钟的批处理任务到第二天早上仍未结束。
- 对于结构化输出,将上限设置为高于预期最大有效文档的值,然后将
done_reasonoflength视为硬错误并重试,不要解析已返回的内容。 - 对于编码代理,该值应配置在代理自身的配置中,因为代理会在每次请求中发送自己的选项。将编码代理指向 Ollama介绍了这些设置的位置。
上限计算的是 token 数量,而不是单词数或字符数,因此不要进行估算。在不设上限的情况下生成一个有代表性的回答,读取 eval_count,然后将限制设置为明显高于该值的数值。不同模型系列的分词方式不同,因此适用于 Llama 模型的数值,可能会截断同一 VPS 上Qwen 3 模型返回的相同答案。
FAQ
num_ctx 和 num_predict 有什么区别?
num_ctx 是上下文窗口的大小,用于设置模型可以读取的内容量:提示词加上目前已生成的全部内容。它会占用内存,因为键值缓存会随之增大。num_predict 设置模型在一次响应中最多可以生成的 token 数量。它主要占用时间而不是内存,也不会预先分配空间。生成的 token 会同时计入两者,因此在关闭上下文移位时,回复可能因任一限制而提前截断。
为什么我的 num_predict 设置似乎没有生效?
因为请求中发送的值会覆盖模型中存储的值。将 PARAMETER num_predict 512 写入 Modelfile,然后通过聊天前端或编码代理使用该模型时,客户端会发送自己的 options 对象,其中的数值优先。ollama show --parameters 仍会显示你设置的值,因为它读取的是模型中存储的内容,看不到通过 HTTP 到达的请求内容。使用 "options": {"num_predict": 32} 发送一个带有 curl 的请求,并提供需要较长回答的提示词,然后读取 done_reason 和 eval_count。如果 length 的 eval_count 为 32,且显示的是请求中的值而不是存储的值,就说明请求值覆盖了存储值。这也确认服务器本身运行正常,接下来应在应用中查找问题。stop 的计数较小只表示模型先完成了生成,因此应使用要求更长回答的提示词重试。
如何判断输出是否因 num_predict 而被截断?
使用 "stream": false 发送请求,然后读取 done_reason。值为 stop 表示模型自行完成了生成,或某个 stop 字符串结束了生成。值为 length 表示可用空间已耗尽。然后将 eval_count 与你的上限进行比较:如果两者完全相同,说明是 num_predict 停止了生成;如果 eval_count 更小,说明上下文窗口先被填满。使用流式传输时,这两个字段会随 "done": true 一起出现在最后一个数据块中,但许多客户端库会在代码读取前将其丢弃。
num_predict 的默认值是多少?
不要从文章中查找,而应从你自己的安装中读取。以 October 2026 为准,Ollama Modelfile 参考文档将默认值列为 -1,表示生成没有上限;该条目是在长期记录为 128 后更正的。在 Ollama v0.40.11 中,这个开放式默认值与任何负值一样,实际上会在达到 num_ctx 的十倍时停止。负值是哨兵值,不是计数;同一表格的旧版本还曾将 -2 列为用于填满剩余上下文的值。请查看适用于你版本的 Modelfile 参数参考,然后使用 ollama show --parameters 和一个 curl 请求进行确认。
提高 num_predict 会让模型生成更长的回答吗?
不会。它只会取消上限。如果回复以 done_reason 结束,且 stop,说明模型判断生成已完成,或某个 stop 字符串匹配成功;提高上限不会改变结果。此时,长度取决于提示词:要求特定结构、指定章节数量或明确详细程度。只有当 done_reason 返回 length 时,才应提高 num_predict。