Ollama num_predict 如何限制輸出長度?
Ollama 的 num_predict 只限制輸出 token。本文說明 3 個設定位置、哪一層優先,以及如何從回應的 done_reason 判斷是否達到上限。
Ollama 中的 num_predict 功能
num_predict 是 Ollama 中限制模型單次回應最多可產生多少 token 的選項。它只計算輸出 token,因此不會將提示內容計入限制。模型達到上限後,會立即停止產生內容,有時甚至會在單字中間停止;此時回應會將 done_reason 設為 length。
這就是此功能的全部內容。問題在於,Ollama 提供 3 個可設定此值的位置,而且距離請求最近的設定會優先套用。幾乎所有「num_predict 沒有作用」的問題,都是某一層設定在不知情的情況下覆寫了另一層設定。
num_predict 不是 num_ctx
這兩個選項在 Ollama 中最容易混淆,也最常因此浪費實際的除錯時間。
num_ctx 是模型可以讀取的內容量。它代表 context window 的大小,包含提示詞以及目前為止產生的所有內容。提高這個值會增加記憶體用量,因為模型為這些 token 保留的 key/value cache 會隨視窗大小增加。評估硬體適用的 num_ctx 大小 是另一項工作,也有各自的失敗原因。
num_predict 是模型會寫入的內容量。它是停止規則,不是配置大小。提高這個值會增加實際執行時間,而不是 RAM 用量,且不會預先保留記憶體。
兩者會在同一處產生關聯。模型產生內容時,產生的 token 會放入 context window。Ollama v0.40.11 對大多數模型預設啟用 context shift,因此視窗填滿後會移除較早的 token,並繼續產生內容。若停用 shift,因為請求會傳送 "shift": false,或模型不支援 shifting,回覆也可能因視窗已填滿而停止,而不是因為達到你的上限而停止。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 物件中針對每個請求設定
每個 generation endpoint 都接受 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 wrapper 或 coding agent。無論介面是否顯示可供您填寫的欄位,它們都會傳送 options 物件。
使用 /set parameter 在單一工作階段中設定
在 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 也接受負值,但負值代表的是特殊標記,而不是數量。其中一個負值表示「不要限制,持續產生」。另一個負值則曾表示「填滿剩餘的內容區段」。截至 2026 年 10 月,Ollama Modelfile 參考文件將預設值列為 -1,代表無限生成;同一份表格的早期版本也曾列出 -2,表示填滿內容區段。
這些設定都必須視為與版本相關,因為其定義曾經變更。參考文件長期將預設值記載為 128,之後才修正為 -1,因此許多指南仍會重複舊數值。行為也曾變更。Ollama v0.40.11 是 2026 年 10 月 25 日的目前版本,會將 GGUF 模型交給需要有限預算的上游 llama-server 程序,因此會將任何負值,以及任何超過 num_ctx 十倍的上限,替換為 num_ctx 的十倍。因此,對上方的 qwen3-capped 模型而言,「無限」實際上代表 81,920 個 token,而 -2 的行為已不再與 -1 不同。請閱讀目前實際執行版本的 Modelfile 參數參考,再使用上方的 eval_count 檢查行為。你在自己的主機上驗證過的值,比從任何地方讀到的值都可靠,包括本文。
為什麼輸出長度是僅使用 CPU 的 VPS 上的主要成本
Ollama 可在你控制的機器上免費執行,因此本機生成不會按量計費;長答案付出的代價只是等待時間。生成分為兩個階段,速度差異很大。系統會分批評估 prompt token,一次處理許多 token。Output token 則一次產生一個,每個 token 都需要遍歷所使用的權重。在僅使用 CPU 的 VPS 上,此遍歷速度受記憶體頻寬限制,因此生成一個 token 的成本遠高於評估一個 prompt token。這是因為該遍歷必須讀取該 token 所使用的每個權重:dense model 會讀取全部權重;mixture-of-experts model(例如 Nemotron 3.5 Lightning)則只讀取經路由選出的 experts。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 core,直到達到 num_ctx 的 10 倍 token 數,因為 context shift 會阻止完整 context window 結束該請求。num_predict 是設定上限的選項。這對小型的 自行託管 Ollama VPS 最為重要,因為一個長請求就可能占用整台機器。
輸出遭截斷通常是上限所致,不是模型故障
這些症狀看起來像是模型故障。回答在句子中途停止。JSON 無法解析,因為結尾的大括號始終未出現。直覺上,人們會怪罪模型或量化設定。請先讀取回應。
done_reason 表示直接回答問題。stop 表示生成在達到任何上限前結束,原因可能是模型輸出了序列結束標記,也可能是輸出符合 stop 選項中的其中一個字串;只要符合,回應就會在該處結束。length 表示生成因空間不足而遭截斷。看到 length 時,請將 eval_count 與上限比較:數值完全相同表示 num_predict 停止了生成;數值較小則表示內容視窗先填滿,而這只有在關閉 context shift 時才會發生。
使用串流時,這些欄位會出現在最後一個區塊中,也就是包含 "done": true 的區塊。許多用戶端函式庫會丟棄這個區塊,只將文字交給程式,因此相同的截斷在應用程式內看似無從解釋,在 curl 下卻很明顯。若函式庫隱藏了這項資訊,請使用 curl 傳送一次請求,以確認伺服器實際回傳的內容。
還有一點可以避免浪費整個下午。提高 num_predict 不會讓模型寫出更多內容,只會移除上限。如果回應在 200 個 token 處以 done_reason 的 stop 結束,表示模型判定內容已完成,或其中一個 stop 字串符合;提高上限不會改變結果。帶有 stop 的簡短回答屬於提示或停止字串問題。帶有 length 的簡短回答則屬於上限問題。
選擇值
- 互動式聊天可不設上限,並按下 Ctrl+C 停止失控的回覆。因為你會持續查看畫面。
- 任何腳本化工作都應設定上限。在迴圈中不設上限地生成內容,可能導致原本只需執行十分鐘的批次工作持續到隔天早上。
- 對結構化輸出,請將上限設在預期最大有效文件的大小之上,然後將
done_reasonoflength視為嚴重錯誤,重新嘗試,而不是解析已取得的內容。 - 對程式碼代理程式,應在代理程式本身的設定中指定此值,因為代理程式會在每次請求中自行傳送選項。將程式碼代理程式指向 Ollama 說明這些設定的位置。
此上限計算的是 tokens,不是單字或字元,因此不要自行估算。先在不設上限的情況下產生一個具代表性的回答,讀取 eval_count,再將限制設得比該值寬裕一些。不同模型系列的 tokenization 方式不同,因此某個適用於 Llama 模型的值,可能會截斷同一 VPS 上 Qwen 3 模型的相同回答。
FAQ
num_ctx 和 num_predict 有什麼差異?
num_ctx 是 context window 的大小,因此決定模型能讀取多少內容:包括 prompt 以及目前為止產生的所有內容。它會消耗記憶體,因為 key/value cache 會隨之增長。num_predict 則決定模型在單次回應中最多可寫入多少 token。它主要消耗時間,而不是記憶體,且不會預先保留容量。產生的 token 會同時計入兩者,因此在關閉 context shift 時,回應可能因其中任一限制而提前截斷。
為什麼我的 num_predict 設定似乎沒有作用?
因為隨請求傳送的值會覆寫模型中儲存的值。將 PARAMETER num_predict 512 放入 Modelfile,接著從聊天前端或程式碼代理程式使用該模型時,client 會自行傳送 options 物件,其中的數值會優先採用。ollama show --parameters 仍會顯示你的設定值,因為它讀取的是儲存於模型中的設定,看不到經由 HTTP 傳入的內容。使用 "options": {"num_predict": 32} 傳送一個包含 curl 的請求,並使用需要長篇回答的 prompt,然後讀取 done_reason 和 eval_count。length 搭配值為 32 的 eval_count 顯示請求中的值覆寫了儲存值,這表示伺服器本身運作正常,應改從應用程式中尋找原因。若 stop 的數值較小,僅表示模型較早完成,因此請改用要求更長回答的 prompt 重試。
如何判斷輸出是否因 num_predict 而截斷?
使用 "stream": false 傳送請求,然後讀取 done_reason。stop 表示模型自行完成,或其中一個 stop 字串終止了輸出。length 表示模型已用完可用空間。接著將 eval_count 與你的上限比較:若兩者完全相同,表示 num_predict 停止了輸出;若 eval_count 較小,表示 context window 先填滿。使用串流時,這兩個欄位會在最後一個 chunk 中與 "done": true 一起傳回,但許多 client library 會在你的程式讀取前將其丟棄。
num_predict 的預設值是多少?
請從你自己的安裝環境讀取,不要依賴文章內容。截至 October 2026,Ollama Modelfile 參考文件將預設值列為 -1,表示生成不設上限;該項目是在長期記載 128 後才更正的。在 Ollama v0.40.11 中,這個開放式預設值與任何負值一樣,實際上會在 num_ctx 的 10 倍處停止。負值是 sentinel,而不是數量;同一張表格的較舊版本也曾列出 -2,表示填滿剩餘的 context。請查看適用於你版本的 Modelfile 參數參考,再使用 ollama show --parameters 和一個 curl 請求確認。
提高 num_predict 會讓模型寫出更長的回答嗎?
不會。它只會移除上限。若回應以 done_reason 的 stop 結束,表示模型判定回答已完成,或其中一個 stop 字串相符;提高上限不會改變結果。此時長度取決於 prompt:請指定結構、段落數量或詳細程度。只有在 done_reason 回傳 length 時,才提高 num_predict。