SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor · 已更新 2026-10-21

Ollama 如何設定 num_ctx 解決提示詞截斷問題

Ollama 預設的上下文長度常導致長提示詞被靜默截斷。本文教您如何透過 API 或 Modelfile 正確設定 num_ctx,並說明如何使用 prompt_eval_count 驗證實際載入的 token 上限。

num_ctx 的作用,以及為何您的長提示詞被截斷

Ollama 的上下文長度是指載入的模型一次能保存在記憶體中的 token 數量,而 num_ctx 則是設定此數值的選項。Ollama 預設的數值遠低於模型所宣稱的最大值,因此較長的提示詞在模型讀取前就會被截斷。回應中不會有任何提示告知您發生了這種情況。

Llama 3.1 8B 在 Ollama 模型庫中標示的上下文視窗為 128k。標準伺服器配置不會直接提供此數值。Ollama 官方文件在不同頁面記載了不同的預設值:FAQ 頁面稱是 4096 個 token,Modelfile 參考頁面稱 num_ctx 預設為 2048,而 上下文長度頁面 則指出預設值是根據可用 VRAM(視訊記憶體)決定:小於 24 GiB 為 4k,24 GiB 至 48 GiB 為 32k,48 GiB 以上則為 256k。上述每個數值在不同版本中都曾是正確的。這裡的教訓是:請直接從您正在執行的伺服器讀取該數值,不要輕信任何網頁(包括本頁)的資訊。

截斷過程是靜默的,因為模型仍會給出回應,且回應讀起來也很通順。這通常是因為回應是根據您輸入內容的結尾部分所產生的。若摘要遺漏了文件的前半部分,看起來會像是模型能力不足,但這通常只是上下文視窗過小的問題。

確認伺服器實際套用的 Ollama context length

在任何 build 上都能使用的檢查方式是 prompt_eval_count。這是伺服器回報已處理的 prompt token 數量。傳送超過 context 可容納的內容後,該數值會停在上限。

sudo apt update && sudo apt install -y jq
LONG=$(python3 -c "print('the quick brown fox jumps over the lazy dog. ' * 2000)")
jq -n --arg p "$LONG" '{model:"llama3.1:8b", prompt:$p, stream:false, options:{num_ctx:4096}}' |
  curl -s http://localhost:11434/api/generate -d @- |
  jq '{prompt_eval_count, prompt_eval_duration}'

該 prompt 約有 18,000 個單字,遠超過 4096 個 token。因此 prompt_eval_count 顯示的數值會接近 4096,而不是實際的 token 總數,因為伺服器捨棄了其餘內容。改用 "num_ctx":16384 再執行一次,計數就會上升。如果你的 build 回傳錯誤而不是截斷內容,這代表相同的結果,只是訊號更明顯。

ollama ps

在會顯示該欄位的 build 上,CONTEXT 欄會顯示目前載入模型所使用的 context length。旁邊的 PROCESSOR 欄會顯示模型的配置位置。VPS 沒有 GPU 時,100% CPU 屬於正常情況。在配備 GPU 的伺服器上,如果顯示 30%/70% CPU/GPU 之類的分割配置,表示權重與 cache 已無法一併放入 VRAM,而提高 num_ctx 通常就是原因。

journalctl -u ollama --no-pager | grep -i n_ctx | tail -n 5

inference runner 會在包含 n_ctx 的行中顯示 context size。不同 release 的確切文字可能不同,因此找不到該行時,應先視為名稱變更,而不是據此判定其他結論。

設定 num_ctx 的 4 個位置

在請求中。 將 "options": {"num_ctx": 16384} 傳送至 /api/generate 或 /api/chat。這會覆寫所有其他設定,且只套用至該次呼叫。如果此值與已載入模型目前使用的值不同,伺服器會先重新載入模型。你可以在回應的 load_duration 中看到這點:數值會從接近 0 跳升至數秒。模型閒置足夠時間而卸載時,也會出現相同的等待時間。因此,確定 context size 後,建議透過 keep_alive 讓模型常駐。

在互動工作階段中。 在 ollama run 內輸入 /set parameter num_ctx 16384。此設定只會持續該工作階段。

在 Modelfile 中。 這會將值寫入具名模型,因此所有 client 都會取得該設定,無須在 client 端變更。

FROM llama3.1:8b
PARAMETER num_ctx 16384
ollama create llama3.1-16k -f ./Modelfile
ollama run llama3.1-16k

在伺服器上。 OLLAMA_CONTEXT_LENGTH 會為未攜帶自有 num_ctx 的所有請求設定預設值。在 systemd 下,請新增 drop-in,而不要編輯 unit file。

sudo systemctl edit ollama.service
[Service]
Environment="OLLAMA_CONTEXT_LENGTH=16384"
sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

在除錯其他人的 client 時,優先順序尤其重要。攜帶 num_ctx 的請求會覆寫伺服器預設值,因此 chat 前端或 agent 若自行傳送較小的值,可能會悄悄抵銷你的 systemd 變更。當你將 coding agent 指向 Ollama 伺服器時,請先確認 client 傳送的內容,再判斷問題是否出在伺服器。

為何不能直接將 num_ctx 設為模型的最大值

注意力機制(Attention)會讓每個 Token 都參照其之前的所有 Token。為了避免為每個新 Token 重複計算,系統會保留先前 Token 的鍵(Key)與值(Value),這就是 KV cache(鍵值快取)。它在模型載入時即針對整個 num_ctx 進行分配,而非隨對話增長而動態擴充,因此即便提示詞只有一行,較大的上下文設定仍會佔用相應的記憶體。

每一層都會為每個 Token 的每個鍵值頭(key/value head)保留一個鍵向量與一個值向量,計算公式如下:

kv_bytes_per_token = 2 * layers * kv_heads * head_dim * bytes_per_value

公式中的 2 代表分別計算鍵與值。請從您使用的模型規格中讀取其他數值。

curl -s http://localhost:11434/api/show -d '{"model":"llama3.1:8b"}' |
  jq '.model_info | {ctx: ."llama.context_length", layers: ."llama.block_count", heads: ."llama.attention.head_count", kv_heads: ."llama.attention.head_count_kv", embed: ."llama.embedding_length"}'

Llama 3.1 8B 具有 32 層與 8 個鍵值頭。頭維度(head dimension)為 embed 除以 heads,在此例中為 4096 / 32 = 128,部分模型會直接標示為 llama.attention.key_length。預設快取儲存 f16 數值,因此 bytes_per_value 為 2,計算得出 2 32 8 128 2 = 131,072 bytes。這意味著每增加一個上下文 Token,就會消耗 128 KiB 的快取。將此數值乘以上下文長度,記憶體成本便不再抽象。

圖表Llama 3.1 8B at f16: KV cache and total RAM by context length, in GiB
此圖表背後的資料
[
  {
    "label": "4k",
    "kv_cache_gib": 0.5,
    "total_ram_gib": 5.1
  },
  {
    "label": "8k",
    "kv_cache_gib": 1,
    "total_ram_gib": 5.6
  },
  {
    "label": "16k",
    "kv_cache_gib": 2,
    "total_ram_gib": 6.6
  },
  {
    "label": "32k",
    "kv_cache_gib": 4,
    "total_ram_gib": 8.6
  },
  {
    "label": "64k",
    "kv_cache_gib": 8,
    "total_ram_gib": 12.6
  },
  {
    "label": "128k",
    "kv_cache_gib": 16,
    "total_ram_gib": 20.6
  }
]

表格中的 6 列數是根據上述公式計算所得,而非實際測量值。總計欄位加上了 Ollama 函式庫在 2026 年 10 月列出 llama3.1:8b 的 4.9 GB 下載大小(即 4.6 GiB),且未計入運算緩衝區與伺服器處理程序本身的佔用。請將此視為最低門檻。

重點在於其規模。在 8k 上下文時,快取成本為 1 GiB,相較於模型權重僅屬微量。當達到模型完整的 128k 上下文時,成本高達 16 GiB,是權重大小的三倍以上,總計接近 20.6 GiB。因此,4 GB 的 VPS 無法在任何實用的上下文長度下載入此模型。8 GB 的 VPS 在 8k 上下文時運作順暢。16 GB 的 VPS 可達到 32k 上下文,並保留足夠空間給系統其他程序。上述所有門檻都會隨模型權重增加而提升,因此若您正在評估比此 8B 模型更大的模型,可參考 在純 CPU VPS 上執行 Qwen 27B 的計算方式,即可了解在 8 GB 至 64 GB 記憶體之間,權重會壓縮多少上下文的可用空間。

當 KV cache 容量不足時會發生什麼事

在僅使用 CPU 的 VPS 上,行程記憶體用量會持續增加。請在模型載入及執行長請求時監控記憶體使用狀況。

free -m
ps -eo rss,comm --sort=-rss | head -n 5

RSS (resident set size) 的單位為 KB。若 free -m 中的 swap 使用量開始攀升,請調降 context 設定。若 KV cache 存放在 swap 中,生成速度會因每個新 token 都需讀取整個 cache,導致每個 token 的生成需耗時數秒。

若伺服器記憶體完全耗盡,核心會挑選一個行程將其終止,通常是佔用最多記憶體的行程。

sudo dmesg | grep -i "killed process"

若出現顯示 Out of memory: Killed process 1234 (ollama) 的日誌行,代表核心選中了 Ollama 作為終止目標,但不一定代表是該行程耗盡了記憶體。在僅有 Ollama 一個大型行程的伺服器上,context 設定過大通常是主因。在調降 num_ctx 之前,請先檢查還有哪些行程在執行。Ollama 通常會在達到該臨界點前拒絕請求,此時請求會失敗並顯示錯誤訊息,列出所需記憶體與剩餘可用記憶體。

在 GPU 伺服器上,失敗的過程較為隱蔽。層級會溢出至系統 RAM,ollama ps 會顯示 CPU 與 GPU 的分配狀況,且吞吐量會急劇下降。下降幅度取決於您的硬體規格,因此建議在各個 context 設定下自行測量每秒生成的 token 數量,而非直接參考他人機器上的數據。

Prefill 時間成長速度高於 prompt 長度

Prefill 是在第一個輸出 token 出現前,處理輸入內容的工作。每個 prompt token 都會關注它之前的所有 token,因此總工作量會隨輸入長度的平方增加。prompt 長度加倍時,等待第一個 token 的時間會超過 2 倍。

回應中會提供測量結果,因此不必直接相信這項說法。

jq -n --arg p "$LONG" '{model:"llama3.1:8b", prompt:$p, stream:false, options:{num_ctx:16384}}' |
  curl -s http://localhost:11434/api/generate -d @- |
  jq '{tokens: .prompt_eval_count, prefill_seconds: (.prompt_eval_duration/1000000000)}'

使用短 prompt 執行一次,再使用長 prompt 執行一次,然後分別以 token 數除以秒數。在僅使用 CPU 的 VPS 上,對長上下文請求而言,prefill 通常是最慢的階段,而根據短 prompt 取得的每秒 token 數,無法預測長 prompt 的表現。若 prefill 時間超過前方任何一層設定的 timeout,長 prompt 通常會回傳 context deadline exceeded,而不是答案。因此,應先找出是哪一層放棄請求,再縮短上下文。

Concurrency 會讓這個問題最嚴重。每個處理中的請求都需要自己的 cache,因此上方圖表中的記憶體用量是以每個請求計算,而不是以每台伺服器計算;一個長請求可能占用整台主機,使短請求排在後面等待。請審慎設定 OLLAMA_NUM_PARALLEL,並先閱讀 一台自架 LLM 能服務多少個並行使用者,再同時提高這兩個數值。

透過較小的快取取回上下文

公式中的 bytes_per_value 是您可以控制的設定。Ollama 的 FAQ 文件說明了 OLLAMA_KV_CACHE_TYPE,其中 f16 為預設值,q8_0 約為 f16 記憶體用量的一半,而 q4_0 則約為四分之一。q8_0 的確切數值略高於一半:llama.cpp 將每 32 個值的區塊儲存為 32 個 1 位元組的值加上一個 2 位元組的縮放比例,因此佔用 34 位元組,而 f16 需要 64 位元組。因此,改用 q8_0 可將 32k 的列從 4 GiB 降至約 2.1 GiB。量化權重可從相同預算中釋放另一側的記憶體,若您傾向於此權衡,實際適用於 VPS 的 GLM 標籤 已針對各個量化層級進行了詳細說明。同一份 FAQ 指出,只有在啟用 Flash Attention 時才會對快取進行量化,並記載了 OLLAMA_FLASH_ATTENTION=1 以強制啟用此功能。

[Service]
Environment="OLLAMA_FLASH_ATTENTION=1"
Environment="OLLAMA_KV_CACHE_TYPE=q8_0"

請確認而非假設:重新啟動服務,以與先前相同的 num_ctx 載入模型,並比較 RSS。支援與否取決於模型與後端,若設定後無任何變化,表示您的組合不支援此功能。快取類型為全域選項,因此伺服器上的所有模型都會以該設定執行。關於品質,FAQ 指出 q8_0 通常沒有明顯影響,而 q4_0 會損失較多精度,在較大的上下文長度下最為明顯,因此在依賴它之前,請先針對您的提示詞測試 q4_0。若這些參數是您關注的重點,Ollama 與 llama.cpp 對它們的公開方式有所不同。

設定 num_ctx 的方法

  1. 從 /api/show 讀取模型的最大上下文長度、層數及 key/value head 數量。
  2. 使用公式計算每個 token 所需的位元組數,再乘以所需的上下文長度。
  3. 加上權重大小,與可用 RAM 比較,並至少保留 1 GiB 給伺服器的其他工作。
  4. 設定數值並載入模型,再使用 ollama ps 和 prompt_eval_count 確認實際套用的設定。
  5. 執行實際工作負載並監控 free -m。如果 swap 開始使用,將上下文長度減半。

大多數工作所需的上下文都比使用者設定的短。摘要整理長篇報告時,16k 通常已足夠。會貼入五個文件片段的檢索前端,很少會超過 8k。需要讀取完整檔案的程式碼代理,才是真正需要 64k 或更大上下文的情況。這種情況也應該以上下文需求來規劃機器,而不是反過來。如果伺服器本身仍是新建的,請先從 可正常運作的 VPS 上的 Ollama 安裝 開始,等模型能正常載入後再調整上下文。

FAQ

Ollama 的預設上下文長度是多少?

這取決於建置版本與硬體規格,請務必檢查而非預設。Ollama 的 FAQ 文件記載為 4096 個 token,Modelfile 參考文件記載 num_ctx 預設值為 2048,而上下文長度頁面則記載預設值取決於可用 VRAM:低於 24 GiB 為 4k,24 GiB 至 48 GiB 為 32k,48 GiB 以上則為 256k。僅使用 CPU 的 VPS 通常會落在較小的數值。在支援該欄位的建置版本中,ollama ps 會顯示套用的上下文長度,而在任何版本中,API 回應中的 prompt_eval_count 都能驗證此數值。

為什麼 Ollama 會忽略我長提示詞的開頭?

因為提示詞長度超過了上下文視窗,伺服器在模型讀取前就將其截斷,且未回傳錯誤。請使用更大的 num_ctx 重新發送相同提示詞,並觀察回應中的 prompt_eval_count 是否增加。若該數值未變動,代表您與伺服器之間的某個環節自行設定了 num_ctx,這在聊天前端與代理框架中很常見。

更大的 num_ctx 需要多少額外 RAM?

將上下文長度乘以每個 token 的快取成本,即 2 * layers * kv_heads * head_dim * bytes_per_value。以 f16 格式的 Llama 3.1 8B 為例,每個 token 為 128 KiB,因此 32k 個 token 除了模型權重外,還需額外佔用 4 GiB,完整的 128k 則需 16 GiB。快取會在模型載入時配置,因此即使您的提示詞很短,設定較大的 num_ctx 仍會佔用該記憶體。

更大的上下文視窗會讓 Ollama 變慢嗎?

會,原因有二。預填充(prefill)運算量會隨提示詞長度的平方增加,因此長輸入導致首個 token 產生的延遲,會比長度增加的比例更顯著。較大的快取也會競爭記憶體資源:在 GPU 伺服器上,這會將層(layers)推向系統 RAM;在 CPU 伺服器上,則會導致機器傾向使用 swap。即使您從未填滿過大的 num_ctx,它仍會佔用記憶體,不過不會增加預填充時間。

我可以為單一模型永久設定 num_ctx 嗎?

可以。編寫一個包含 FROM llama3.1:8b 與 PARAMETER num_ctx 16384 的 Modelfile,然後執行 ollama create llama3.1-16k -f ./Modelfile。每個請求 llama3.1-16k 的客戶端都會在無須發送任何選項的情況下獲得該上下文設定。若請求本身帶有 num_ctx,則該請求的設定優先,因此這僅是設定預設值而非上限。

這篇文章對您有幫助嗎?