llama.cpp 伺服器版本怎麼固定？

llama.cpp 版本標記的變更

固定 llama.cpp 發行版本，表示建置一個指定的標籤，並將該標籤名稱記錄在模型檔案旁。標籤不會自行移動，因此伺服器明天產生的結果會與今天相同。多年來，只有一種標籤可供選擇：例如 b10502 這類由 master 自動產生的建置編號。自 2026 年起，新增第二種標籤，即 v0.1.2 這類版本標籤；兩條版本線會在相同時間，從相同的歷史記錄產生。

版本標籤目前尚不具備版本號通常代表的意義。v0.1.2 的發行說明以一行文字明確表示：

Semantic versioning 仍在開發中。更多資訊請參閱 https://github.com/ggml-org/ggml/discussions/1579

請按字面理解這段說明。該連結所指向的 ggml 討論 仍在制定這套規則，包括發行版本的頻率，以及哪些變更可算是修補版本。v0. 標籤只表示專案選擇在歷史記錄中標記某個時間點。它不保證下一個標籤的最後一位增加 1 後，就能安全地直接替換。

建置標籤中的數字也不代表版本意義。該數字來自 commit 計數，因此無論是否有任何與環境相關的變更，都會自行增加。截至 19 August 2026，發行版本清單首頁共有 9 個建置標籤，範圍從 b10455 到 b10502，其中包含 v0.1.2。

請勿在提供任何服務的主機上直接從 master 建置

執行 git pull 後重新建置，會取得過去幾小時內加入的所有變更。這在筆記型電腦上沒有問題。但在伺服器上，這會讓你無法回答行為變更時最重要的問題：目前執行的是什麼版本，上週執行的又是什麼版本。模型產生的文字及其產生速度，都會隨建置版本變動。如果有人反映上週二的回答品質變差，而當天的 commit 從未記錄，就無法找出原因。

請改用固定的 tag。專案會替你建立 tag，每個預先建置的 release archive 也都以其中一個 tag 命名。

llama.cpp 發行版本應固定在哪一種標籤？

如果需要固定在某個已知狀態，請固定使用 build tag。這是具有完整歷史紀錄的版本線，也是發行檔案命名所依據的版本線；多數錯誤回報也會引用這個版本線，因此 build number 最容易與其他人的環境進行比對。

如果希望只追蹤較短、經過明確規劃的版本節點，請固定使用 version tag。更新前先閱讀版本說明，並注意前文提到的限制，因為目前的編號尚未構成相容性契約。

無論採用哪一種方式，作業規則都相同。標籤字串儲存在檔案中，只有該字串變更時才重新建置伺服器，而每次變更都必須是明確決定的結果。

建置固定標籤

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 --tags

git 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 8080

systemd 啟動程序時會解析 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: 7c1f2a9
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 取得 checksum，並在下載時與發布者提供的值比對。將下載檔案與發布的 checksum 比對，可在檔案截斷而形成難以診斷的錯誤前發現問題。量化層級本身對回答的影響程度是另一個問題；各量化層級的代價會進一步說明。

如何升級而不影響伺服器？

將升級當成演練。把新標籤建置在舊版本旁邊，測量兩者，並保留舊版本，直到新版本確認運作正常。

1. 將新標籤複製到專用目錄。不要重複使用舊的 checkout。
2. 使用 manifest 中記錄的相同 cmake 引數進行建置。
3. 使用相同的 model file、相同的 prompt 長度及相同的重複次數，對兩個建置執行 llama-bench。
4. 將你熟悉答案的 prompt 傳送至兩台伺服器，並讀取兩個回覆。
5. 移動 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 5

llama-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 會在啟動期間結束，日誌中會出現 failed to load model from /srv/models/model-q4_k_m.gguf 行。請查看這行之前輸出的內容，以確認載入器執行到哪個階段。GGUF 標頭也包含格式版本（規格目前的值為 3；版本 2 將長度欄位從 32 位元擴大為 64 位元），但實務上，未知的架構名稱通常會早於格式版本檢查造成停止。解決方式是改用較新的 tag，並記錄所選版本。

伺服器旗標重新命名或已棄用。 未辨識的旗標會讓 llama-server 在啟動時停止，而不是忽略該旗標。在 systemd 下，這看起來像服務反覆啟動後立即結束。journalctl -u llama-server -n 50 會顯示實際訊息。截至 19 August 2026，伺服器文件將 --mlock 與 --mmap 標示為已棄用，建議改用 -lm, --load-mode；該旗標可接受 auto、mmap、mlock 和 dio 等值。GPU offload 旗標在文件中記為 -ngl, --gpu-layers，較舊的指南則寫成 --n-gpu-layers。移動 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 asset 包含 CPU、Vulkan、SYCL 和 OpenVINO 變體，支援 x64、arm64 和 s390x。該清單沒有 Linux 的 CUDA archive，因此 NVIDIA 伺服器必須從原始碼建置，或執行 container image。Windows CUDA archive 會依 toolkit 版本分別發布，這提供了一項實用提示：toolkit 版本是識別 binary 的資訊之一，因此應與 cmake 引數一併記錄。

改用固定容器映像

規則相同，只是對象不同。已發布的映像（ghcr.io/ggml-org/llama.cpp:server及其加速器變體）使用的是會變動的名稱，因此下個月拉取 :server 時，會在相同標籤下取得不同的程式。先拉取一次並讀取摘要：

docker pull ghcr.io/ggml-org/llama.cpp:server

docker 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？

兩者皆可，前提是固定其中一個。像 b10502 這類 build tag 是長期維護軌道：每個預建 release archive 都以它命名，多數錯誤回報也會引用它，因此 build number 最容易讓不同管理者相互比對。像 v0.1.2 這類 version tag 則是較短的明確版本清單，適合一年只維護數次的伺服器。比選擇哪一種更重要的是，將 tag 字串記錄在 model file 旁，並確保升級是經過決定的行為，而不是 git pull 的副作用。

llama.cpp 現在遵循 semantic versioning 嗎？

尚未遵循，這是專案本身的說法。v0.1.2 release notes 表示 semantic versioning 仍在開發中，並指向一個正在制定規範的 ggml 討論，其中包含 release cadence 及 patch 的定義。應將 version tag 視為維護者選定並標記的版本。不要假設最後一位數變更就一定能直接升級；切換前，請先以自己的 model file 測試新的 tag。

如何確認伺服器目前執行哪個 llama.cpp build？

llama-server --version 會輸出 version 與 build information。啟動日誌也會以 build 開頭，其中包含 build number、commit hash 與所使用的 compiler，因此可透過 journalctl -u llama-server 找到執行中服務的資訊。在 source install 中，於固定版本的 checkout 內執行 git describe --tags 可輸出 tag，而 readlink /opt/llama.cpp/current 可顯示服務實際指向的目錄。

為什麼升級 llama.cpp 後，model 不再載入？

升級後立即發生的載入失敗，表示 build 與 GGUF file 不相容。日誌最後會出現 failed to load model from，指出路徑；其上方的內容則顯示 loader 讀取到哪個階段。往前升級時，過新的 model file 需要使用支援其架構的 build。往後回退時，若 rollback 到低於該檔案建立時所用 tag 的版本，原本可用的檔案可能會失效。請將 symlink 指向先前的 build，重新啟動，並確認哪個 build 與 file 能正確配對，再決定要變更其中哪一個。

是否有可固定版本的預建 Linux binaries，無須自行建置？

有，部分環境提供此選項。每個 build tag 都包含以該 tag 命名的 release archives，例如 llama-b10502-bin-ubuntu-x64.tar.gz；截至 19 August 2026，另有 arm64、s390x、Vulkan、SYCL 與 OpenVINO 變體。檔名包含 tag，因此容易固定版本。該清單沒有 Linux 的 CUDA archive，因此 NVIDIA 伺服器仍須使用 -DGGML_CUDA=ON 從 source 建置，或執行其中一個 CUDA container image。