真正重要的引擎參數

多數引擎預設值對展示合理、對真實使用是錯的。三四個旋鈕改變結果：上下文長度、GPU 卸載、KV 快取類型與 flash attention。其他都是邊際調校。這一頁用 llama.cpp 的旗標名稱，最後附 Ollama 對應——概念適用於每個引擎。

上下文長度：無聲預設的陷阱

引擎出貨時用的是保守預設：llama.cpp 歷史上先是 512 再 4096，Ollama 依版本 2048–4096（截至目前 OLLAMA_CONTEXT_LENGTH 落在 4k 左右）。而你的模型可能原生支援 32k–128k。把 20k token 的文件貼進 4k 上下文，會發生兩件事之一，兩件都很糟：硬錯誤（「request exceeds available context」）或最舊訊息被無聲截斷。兩種錯誤訊息對新手都不解釋自己。

實例：你把約 12k token 的合約加一個問題，載入預設的 4096 視窗。引擎保留最近的內容、丟掉文件開頭，然後模型自信地回答關於檔案錯的那一半的問題。這看起來像笨模型；其實是被截斷的提示詞。

修法很機械：每次啟動都明確傳入上下文大小，按真實提示詞加預期輸出設定，然後確認啟動日誌顯示 n_ctx = 16384（或你選的值）。韓文註記：同一個分詞器下，韓文的分詞密度常低於英文——一頁韓文的 token 數可能多於一頁英文（見 token 與分詞器）——所以上下文壓力比你預期的更早到達。

# 陷阱：預設值因引擎與版本而異
llama-server -m model.gguf                  # starts with n_ctx = 4096 or so

# the fix: explicit, and verified in the startup log
llama-server -m model.gguf -c 16384         # log prints: n_ctx = 16384

GPU 卸載：n_gpu_layers

-ngl／--n-gpu-layers 設定多少 transformer 層住在 GPU 上；用 99 這種大數字（支援的地方用 -1）表示「全部」。部分卸載的症狀很有辨識度：有不錯 GPU 的機器上只有 3–10 tok/s。用載入日誌行驗證，例如 offloaded 33/33 layers to GPU。如果 VRAM 裝不下模型加 KV 快取，誠實的選項是更小的量化、量化過的 KV 快取、或卸載少一點層——但要知道每個留在 CPU 上的層都會把整個迴圈拖到 CPU 的節奏（見 速度）。幾乎裝得下的模型只卸載一半，通常比降一級量化更糟。

也往另一個方向做健全性檢查：-ngl 0 強制純 CPU，如果它跟你的「GPU」設定跑得一樣快，代表 GPU 根本沒做事。

執行緒（僅 CPU 模式）

CPU 模式下把 -t 設成實體核心數，不是 SMT 執行緒數：8 核心／16 執行緒的晶片就用 8。執行緒多於實體核心會造成爭用並拖慢解碼。提示詞處理有另一個旋鈕（--threads-batch）；同樣的規則適用。

記憶體：mmap 與 --mlock

llama.cpp 預設對模型檔做記憶體映射：啟動快、沒碰到的層不占 RAM。代價是 OS 可能在記憶體壓力下逐出分頁，造成連線數小時後的神秘停頓。--mlock 把模型釘住不讓逐出——在忙碌的機器上有用，代價是把數 GB 鎖走、別的東西不能用。Ollama 內部會處理；在共享機器上用原生 llama.cpp 的人應該知道這個旗標存在。

Flash attention

-fa／--flash-attn 減少注意力步驟的記憶體流量，近期的 llama.cpp 版本預設開啟（或自動）。它在長上下文時影響最大，而且目前的版本量化 V 快取需要它。如果新版在你的 GPU 後端行為異常，這是第一個該撥的開關——而且在任何近期版本上，第一件該檢查的是它有沒有默默自己關掉。

KV 快取量化

--cache-type-k q8_0 --cache-type-v q5_0 把 KV 快取從 16-bit 浮點存成 8-bit／5-bit，以輕微品質代價把 KV 記憶體砍到約一半或更好——也就是同樣 VRAM 能塞更長的上下文。KV 快取是什麼與精確的大小計算：KV 快取。

典型收益：q8_0 的 K 加 q5_0 的 V 大約把 KV 大小減半，對話任務上幾乎看不出變化——信任它之前先在自己的工作負載上驗證。

提示詞批次大小

-b／--batch-size 是預填（提示詞處理）的區塊大小。更大的批次讓長提示詞的首 token 時間更快，代價是一點峰值 VRAM。如果長貼文起頭感覺慢，先調它再怪模型。

拉長上下文：rope scaling 與 YaRN

--rope-scaling yarn --rope-factor 2.0 透過重新縮放位置頻率，把 32k 原生的模型往 64k 拉。可行，但有一條品質斜坡：靠近原生視窗時退化很小，越拉過頭越大。重要的事，優先選原生上下文已涵蓋需求的模型，而不是拉長小視窗（見 如何選模型）。

截至目前 Ollama 的 Modelfile 沒有暴露 rope scaling；拉長上下文的實驗要直接啟動 llama.cpp。

一行有註解的啟動指令

llama-server -m qwen3-8b-q4_k_m.gguf --host 127.0.0.1 --port 8080 -c 16384 -ngl 99 -fa on -b 2048 --cache-type-k q8_0 --cache-type-v q5_0

Ollama 對應

# per-model, in a Modelfile:
PARAMETER num_ctx 16384
PARAMETER num_gpu 99

# or globally, before the service starts:
export OLLAMA_CONTEXT_LENGTH=16384
export OLLAMA_FLASH_ATTENTION=1
export OLLAMA_KV_CACHE_TYPE=q8_0

請求超過 num_ctx 時 Ollama 會記警告——改過任何一項之後把日誌讀一次。透過環境變數的變更需要重啟服務。

要看 Ollama 實際套用了什麼：ollama show model --modelfile 印出解析後的參數，OLLAMA_DEBUG=1 讓服務把真實的上下文與卸載數量寫進日誌。

取樣器不是引擎參數

溫度、top-p、重複懲罰——那些決定選哪個 token，不是多快、記憶體塞多少。它們住在 取樣。如果輸出怪但速度與記憶體正常，你要的是那一頁，不是這一頁。

原則

明確設定上下文。每次改啟動設定，都用日誌行驗證——n_ctx = ... 與 offloaded N/N layers。預設值的調校目標是讓第一次展示能跑，不是服務你的工作負載。

llm_load_tensors: offloaded 33/33 layers to GPU
n_ctx = 16384

兩行都會在啟動後幾秒內印出。grep 一次，設定就不再是民俗傳說。

相關章節： 速度 · KV 快取 · 取樣 · 端點服務