llama.cpp 伺服器版本如何固定?
llama.cpp 新增 `vX.Y.Z` 版本標籤,與 `bNNNN` 建置標籤並行。本文說明如何連同 GGUF 與量化方式記錄,並讓每次升級都能回復。
llama.cpp 版本標籤的變更
固定 llama.cpp 版本時,應建置一個指定的標籤,並將該標籤名稱記錄在模型檔案旁。標籤不會自行移動,因此伺服器今天產生的結果,明天仍會維持一致。多年來,只有一種標籤可供選擇:例如 b10502 這類由 master 自動產生的建置編號。自 2026 年起,新增了第二種標籤,也就是 v0.6.0 這類版本標籤,而這兩條版本線不會同步更新。建置標籤幾乎會在每次提交至 master 時建立。版本標籤則由維護者手動建立,頻率較低;每個版本版本釋出都會標示與其相符的建置標籤。
版本標籤初期仍屬試行階段。v0.1.2 的版本說明於 18 August 2026 發布,並以一行文字說明:
語意版本控制仍在開發中。詳情請參閱 https://github.com/ggml-org/ggml/discussions/1579
三天後,v0.2.0 的版本說明確立了這項作法。該說明指出,此版本「標誌著 llama.cpp 一致採用語意版本控制的開始」。其中將 vX.Y.Z 標籤描述為更新頻率較低的穩定版本,建議下游發行套件與一般使用者採用;將 b[NUM] 標籤描述為包含最新功能的 nightly 或開發建置,建議開發者與技術使用者採用。截至 14 November 2026,最新的版本標籤是 v1.0.0,於 13 November 發布;其版本說明將 b12359 列為相符的建置標籤。
該連結背後的 ggml 討論 仍保留這套方案的設計考量;截至 21 October 2026,該討論仍開放回饋。版本編號已進入 1.x,因此每次更新前都應閱讀版本說明,不要只根據變更了哪一位數字來判斷是否升級。
建置標籤中的數字不代表版本。該數字來自提交次數,因此無論是否有任何與你的環境相關的變更,都會自行增加。
切勿在提供服務的機器上從 master 分支進行建置
執行 git pull 並重新建置,會讓您取得過去幾小時內合併的所有變更。這在筆記型電腦上沒問題,但在伺服器上,這會導致您無法回答行為變更時最關鍵的問題:現在執行的是什麼版本,以及上週執行的是什麼版本。模型產出的文字內容及其生成速度,都會隨著建置版本而變動。如果週二的提交紀錄未被記錄下來,那麼針對「週二回答品質變差」的抱怨,將無從查證。
請改用標籤(tag)進行鎖定。專案會為您建立標籤,且預先建置的發行壓縮檔(release archives)會在檔名中包含建置標籤,Windows CUDA 執行階段套件(cudart-llama-bin-win-...)除外。
llama.cpp 發布版本應固定哪個標籤?
如果需要固定在某個已知狀態,請固定 build tag。這是歷史最悠久的追蹤方式,也是發布封存檔案所使用的命名依據。多數錯誤回報也會引用這個標籤,因此 build number 最容易與其他人的版本進行比對。
如果希望追蹤較短且經過明確選定的版本清單,請固定 version tag。這是專案目前建議下游發行版採用的追蹤方式。每個 version release 都會列出對應的 build tag,而預先建置的二進位檔也位於該 build tag,因此請將 build number 記錄在 version 旁邊。即使編號已達到 1.x,升級前仍應先閱讀變更說明。
無論採用哪種方式,作業規則都相同。標籤字串存放在檔案中。只有在該字串變更時才重新建置主機。每次變更都必須是經過明確決定的操作。
建置固定標籤
sudo apt update
sudo apt install -y build-essential cmake git
git clone --depth 1 --branch b10502 https://github.com/ggml-org/llama.cpp.git ~/src/llama.cpp-b10502
cd ~/src/llama.cpp-b10502
git describe --tagsgit describe --tags 應輸出 b10502。在標籤建立淺層複製只會包含該提交,不會包含其後的內容,因此不慎執行 git pull 也無法在之後移動它。如果 configure 步驟因缺少相依項目而停止,請安裝訊息中列出的項目,再重新執行。
請依硬體需求使用建置選項。僅使用 CPU:
cmake -B build
cmake --build build --config Release -j $(nproc)NVIDIA GPU,必須先安裝 CUDA toolkit:
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j $(nproc)僅使用 CPU 的主機搭配 OpenBLAS:
cmake -B build -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS
cmake --build build --config Release -j $(nproc)二進位檔會放在 build/bin,與其載入的共用函式庫放在一起(libllama.so 和 libggml 檔案)。安裝前先確認建置結果可以執行:
./build/bin/llama-server --version將整個目錄安裝到以標籤命名的路徑下,再以一個 symlink 指向該目錄:
sudo install -d /opt/llama.cpp/b10502
sudo cp -a build/bin /opt/llama.cpp/b10502/bin
sudo ln -sfn /opt/llama.cpp/b10502 /opt/llama.cpp/current請複製目錄,不要只複製單一檔案。單獨的 llama-server 第一次執行就會因 error while loading shared libraries: libllama.so: cannot open shared object file 而失敗,因為所需的函式庫位於該目錄中,與它放在一起。
讓服務指向 symlink,不要指向標籤目錄:
[Service]
ExecStart=/opt/llama.cpp/current/bin/llama-server -m /srv/models/model-q4_k_m.gguf -c 8192 -ngl 99 --host 127.0.0.1 --port 8080systemd 啟動程序時會解析 symlink,因此切換建置版本只需變更 symlink 目標,再執行 sudo systemctl restart llama-server。其餘 unit 檔案與前端的反向代理,請參閱VPS 上 llama.cpp 伺服器的完整操作說明。
記錄 GGUF 檔案旁的標籤與量化版本
建置版本決定了一半的輸出結果,模型檔案則是另一半。GGUF (GGML universal file format) 是權重封裝的容器格式,同一模型會發布多種量化等級。因此,即使兩台伺服器使用相同的標籤,結果仍可能不一致,因為一台可能使用 Q4_K_M 檔案,另一台則使用 Q8_0。請在模型旁保留一個小檔案,記錄重建環境所需的所有資訊:
tag: b10502
commit: 0adcc3b
model_file: model-q4_k_m.gguf
model_sha256: <output of sha256sum>
quant: Q4_K_M
cmake_args: -DGGML_CUDA=ON
cuda: <output of nvcc --version>
bench_cmd: llama-bench -p 512 -n 128 -r 5
bench_result: <fill in from the run on this box>在固定的 checkout 中使用 git rev-parse --short HEAD 取得 commit。使用 sha256sum model-q4_k_m.gguf 取得校驗和,並在下載時與發布者的數值進行比對,因為 比對下載檔案與其發布的校驗和 能在檔案損毀導致難解的錯誤前先行攔截。至於量化等級本身對答案的影響程度則是另一個問題,各量化等級的代價 涵蓋了相關說明。
如何升級而不影響伺服器?
將升級當成演練。把新標籤建置在舊版本旁邊,測量兩者,並保留舊版本,直到新版本確認運作正常。
- 將新標籤複製到專用目錄。不要重複使用舊的 checkout。
- 使用 manifest 中記錄的相同 cmake 引數進行建置。
- 使用相同的 model file、相同的 prompt 長度及相同的重複次數,對兩個建置執行
llama-bench。 - 將你熟悉答案的 prompt 傳送至兩台伺服器,並讀取兩個回覆。
- 移動 symlink,重新啟動服務,並將舊目錄保留在磁碟上。
/opt/llama.cpp/b10502/bin/llama-bench -m /srv/models/model-q4_k_m.gguf -p 512 -n 128 -r 5
/opt/llama.cpp/<new tag>/bin/llama-bench -m /srv/models/model-q4_k_m.gguf -p 512 -n 128 -r 5llama-bench 會為每項測試列印一列,其中包含 backend 欄、ngl 欄,以及帶有標準差的每秒 tokens 欄。請比較兩個建置中的相同列,不要將一個建置的 prompt 列與另一個建置的 generation 列比較。在不同 prompt 長度下取得的數值屬於不同測量結果,因此 每次都以相同方式測量每秒 tokens 比數值本身更重要。
回復只需執行兩個命令,而且只有在舊目錄仍然存在時才能運作:
sudo ln -sfn /opt/llama.cpp/b10502 /opt/llama.cpp/current
sudo systemctl restart llama-server至少保留上一個建置版本。相較於它旁邊已使用的 model file,這只會占用一小部分磁碟空間。
llama.cpp 升級後會出現的問題
模型檔案停止載入。 這通常是促使人員升級的原因:新發布的模型使用了固定版本建置不支援的架構,因此完全無法載入。llama-server 會在啟動期間結束。 截至 21 October 2026,伺服器原始碼會為此記錄 failed to load model, '/srv/models/model-q4_k_m.gguf',其中包含逗號及以單引號括住的路徑;它輸出的最後一行是 exiting due to model loading error,該行不包含路徑。請在 journal 中搜尋 failed to load model,不要搜尋整行訊息。查看它之前輸出的行,包括載入器本身的 error loading model: 行;這些內容會顯示載入器執行到哪個階段,以及停止的原因。GGUF 標頭也包含格式版本(規格目前的值為 3,而版本 2 將長度欄位從 32 位元擴充為 64 位元),但實務上,未知的架構名稱通常會在格式版本造成問題之前就中止載入。修正方式是改用較新的 tag,並記錄所選用的 tag。
伺服器旗標重新命名或遭到棄用。 未辨識的旗標會使 llama-server 在啟動時停止,而不是直接忽略;在 systemd 下,這會呈現為服務反覆啟動後立即結束。journalctl -u llama-server -n 50 會顯示實際訊息。截至 19 August 2026,伺服器文件已將 --mlock 和 --mmap 標示為棄用,改用 -lm, --load-mode。截至 21 October 2026,這兩個旗標已不再出現在伺服器文件或 master 的引數清單中,因此請使用 --load-mode 延續相同行為;它接受 auto(預設值)、none、mmap、mlock、mmap+mlock 和 dio。GPU offload 旗標記載為 -ngl, --gpu-layers, --n-gpu-layers,因此舊版指南中的長格式仍可使用。預設值也會變更:自 v0.7.0 起,llama-server 預設監聽 9931 埠,而不是 8080(Docker 映像檔在容器內仍使用 8080),因此未設定 --port 的 unit file 將不再在反向代理預期的位置回應。v1.0.0 release 也移除了已棄用的 --defrag-thold 旗標。移動 symlink 前,請先執行 /opt/llama.cpp/<new tag>/bin/llama-server --help,並逐一核對 unit file 中的所有旗標。
建置選項重新命名。 CMake 選項的前綴已從 LLAMA_ 改為 GGML_,而根目錄中的 CMakeLists.txt 仍保留對應關係。現在,LLAMA_CUBLAS 會以致命錯誤指出替代選項為 GGML_CUDA;LLAMA_CUDA 和 LLAMA_METAL 則會產生警告,並自動為你轉換。建置指令碼在 configure 階段停止,反而是較好的結果。較難察覺的失敗更嚴重:若不慎省略 -DGGML_CUDA=ON,建置會成功、伺服器會啟動,但所有工作都在 CPU 上執行。llama-bench 可立即顯示這個問題,因為 backend 欄會讀取為 CPU。
加速器建置不具可攜性。 截至 19 August 2026,附加至 build tag 的 Linux 資產包括 CPU、Vulkan、SYCL 和 OpenVINO 變體,支援 x64、arm64 和 s390x,但沒有 Linux 的 CUDA archive。此後情況已變更。截至 21 October 2026,b11669(v0.7.0 背後所使用的 build tag)也包含 Ubuntu CUDA archive:x64 支援 CUDA 12.8 和 13.4,arm64 支援 CUDA 13.4;每個 archive 都有相符的 cudart- runtime archive,另外也提供 ROCm build。Linux 和 Windows 都會依 toolkit 版本發布 CUDA archive。這提供了一項實用提示:toolkit 版本是識別 binary 的必要資訊之一,因此請將它與 cmake 引數一併記錄。
改用固定容器映像
規則相同,只是對象不同。已發布的映像(ghcr.io/ggml-org/llama.cpp:server及其加速器變體)使用的是會變動的名稱,因此下個月拉取 :server 時,會在相同標籤下取得不同的程式。先拉取一次並讀取摘要:
docker pull ghcr.io/ggml-org/llama.cpp:serverdocker pull會輸出一行 Digest: sha256:...。將該摘要放入 compose 檔案,取代標籤。下次有人執行 docker compose pull 時,映像就不會在未察覺的情況下變更。將先前的摘要保留在註解中,這樣只需修改一處即可回復;處理方式與Compose 堆疊的升級與回復程序處理其他服務相同。
固定版本的用途
固定版本能讓你精確確認目前執行的內容,也能在變更造成問題時,於 1 分鐘內還原上一個 build。llama.cpp 要求你分別記錄兩項資訊:build tag 和 model file,因為它會將兩者分開提供。將兩者打包在一起的 runtime,處理方式則不同;Ollama 與 llama.cpp 作為伺服器的比較說明了這項取捨:整體只使用一個版本號,較容易記錄,也較容易控管。
FAQ
我應該固定 bNNNN build tag,還是固定 v0.x tag?
兩者皆可,前提是你確實固定了某個 tag。像 b10502 這類 build tag 是長期維護的追蹤線:預先建置的 release archive 會在檔名中包含該 tag(Windows CUDA runtime bundle 除外),而且大多數錯誤回報也會引用它,因此 build number 最容易與其他維運人員比對。像 v0.6.0 這類 version tag 則是專案建議下游發行使用的精選版本,適合每年只維護幾次的伺服器。每個 version tag 都會標示對應的 build tag,因此請同時記錄兩者。比起選擇哪一種 tag,更重要的是將 tag string 記錄在 model file 旁,並確保升級是明確決策,而不是 git pull 的副作用。
llama.cpp 現在遵循 semantic versioning 嗎?
是,自 v0.2.0 起,於 21 August 2026 開始遵循。其 release notes 表示,這代表 llama.cpp 開始一致採用 semantic versioning,取代 v0.1.2 所帶有的 work-in-progress 注意事項。截至 14 November 2026,版本編號已進入 1.x,最新版本為 v1.0.0,於 13 November 發布。升級前請先閱讀 release notes,並以你自己的 model file 測試新的 tag,再切換到該版本;無論變更的是哪一位數字,都應如此處理。
如何確認伺服器執行的是哪個 llama.cpp build?
llama-server --version 會輸出版本與 build 資訊,因此請對服務實際使用的 binary 執行:/opt/llama.cpp/current/bin/llama-server --version。截至 21 October 2026,包含 build number、commit hash 與 compiler 的啟動行會以 trace level 記錄,因此不要預期在預設 log level 下於 journalctl -u llama-server 找到它。在 source install 中,於已固定版本的 checkout 內執行 git describe --tags 可輸出 tag,而 readlink /opt/llama.cpp/current 會顯示服務實際指向的目錄。
為什麼升級 llama.cpp 後,model 無法載入?
升級後立即發生載入失敗,表示 build 與 GGUF file 不相容。log 會包含一行 failed to load model, '<path>',其中列出檔案名稱,並以 exiting due to model loading error 結尾;其上方幾行則顯示 loader 已讀取到哪個階段。向前升級時,新的 model file 需要由支援其 architecture 的 build 載入。向後回復時,若 rollback 到低於建立該檔案所用 tag 的版本,原本昨天仍能運作的檔案可能會失效。請將 symlink 指向前一個 build、重新啟動,並確認哪個 build 與哪個 file 能正確配對,再決定要變更其中哪一個。
是否有可固定版本、無須自行建置的預先建置 Linux binary?
有。每個 build tag 都會提供以該 tag 命名的 release archive,例如 llama-b10502-bin-ubuntu-x64.tar.gz,因此 tag 會出現在檔名中,容易固定版本。19 August 2026 的 Linux 組合包括 CPU、arm64、s390x、Vulkan、SYCL 與 OpenVINO,但沒有 CUDA archive。截至 21 October 2026,較新的 b11669 也提供 Ubuntu CUDA 12.8 與 13.4 archive,以及相符的 cudart- runtime bundle;因此,使用較新 tag 的 NVIDIA 伺服器不再需要透過 -DGGML_CUDA=ON 從 source build,或執行 CUDA container image。若你固定的是 version tag,請從其 release notes 指定的 build tag 下載 archive。