SSD Nodes Learn Hosting plans →
Hướng dẫn Matt ConnorBởi Matt Connor

Cách pin release llama.cpp trên server

llama.cpp nay có version tag như v0.6.0 bên cạnh build tag bNNNN. Chọn một tag, ghi cùng file GGUF và quant, rồi nâng cấp theo quy trình có thể rollback.

Thay đổi trong cách đánh số phiên bản của llama.cpp

Pin release của llama.cpp nghĩa là build một tag có tên cụ thể và ghi lại tên đó bên cạnh file model. Tag không tự di chuyển, nên server vẫn tạo ra cùng một kết quả vào ngày mai như hôm nay. Trong nhiều năm, chỉ có một loại tag để chọn: build number như b10502, được tự động tạo từ master. Từ năm 2026 có thêm loại thứ hai là version tag như v0.6.0, và hai nhánh này không tăng đồng bộ. Build tag được tạo gần như sau mỗi commit vào master. Version tag do maintainer tạo thủ công với tốc độ chậm hơn, và mỗi version release đều ghi rõ build tag tương ứng.

Ban đầu, version tag chỉ mang tính thử nghiệm. Release note của v0.1.2, được công bố ngày 18 August 2026, nêu rõ điều này trong một dòng:

Semantic versioning vẫn đang trong quá trình hoàn thiện. Có thêm thông tin tại https://github.com/ggml-org/ggml/discussions/1579

Ba ngày sau, v0.2.0 đã xác định rõ cách này. Release note của bản đó cho biết release này “đánh dấu thời điểm bắt đầu áp dụng semantic versioning nhất quán cho llama.cpp”. Tài liệu mô tả tag vX.Y.Z là các version ổn định, có chu kỳ release chậm hơn, phù hợp để phân phối downstream và cho người dùng thông thường. Tag b[NUM] là nightly hoặc dev build với chức năng mới nhất, phù hợp cho developer và người dùng kỹ thuật. Tính đến ngày 14 November 2026, version tag mới nhất là v1.0.0, được release ngày 13 November, và release note ghi b12359 là build tag tương ứng.

Thảo luận trên ggml đứng sau liên kết đó vẫn giải thích lý do của cách đánh số này, và tính đến ngày 21 October 2026 vẫn đang mở để nhận phản hồi. Việc đánh số version đã đạt đến 1.x, vì vậy hãy đọc release note trước mỗi lần chuyển version, thay vì đánh giá một lần nâng cấp chỉ dựa vào chữ số nào đã thay đổi.

Con số trong build tag không mang ý nghĩa về version. Nó được tính từ số lượng commit, nên tự tăng dù có hoặc không có thay đổi liên quan đến setup của bạn.

Không bao giờ build từ master trên máy chủ đang phục vụ bất kỳ dịch vụ nào

git pull rồi build lại sẽ lấy mọi thay đổi đã được đưa vào trong vài giờ gần nhất. Cách này phù hợp trên laptop. Trên server, cách này khiến bạn không thể trả lời câu hỏi quan trọng khi hành vi thay đổi: hiện đang chạy phiên bản nào và tuần trước đã chạy phiên bản nào. Nội dung model tạo ra và tốc độ tạo nội dung đều thay đổi theo build. Nếu có phản ánh rằng câu trả lời kém hơn vào thứ Ba tuần trước, bạn sẽ không thể xác định nguyên nhân nếu commit của thứ Ba chưa từng được ghi lại.

Thay vào đó, hãy cố định một tag. Project tạo tag cho bạn, còn các archive release dựng sẵn có build tag trong tên file, ngoại trừ các bundle Windows CUDA runtime (cudart-llama-bin-win-...).

Nên pin llama.cpp releases vào tag nào?

Hãy pin vào build tag khi bạn cần một trạng thái cụ thể đã biết. Đây là nhánh có lịch sử lâu nhất, là nhánh mà tên của các release archive dựa trên đó, và cũng là nhánh được nhắc đến trong phần lớn bug report. Vì vậy, build number là giá trị dễ so sánh nhất với người khác.

Hãy pin vào version tag nếu bạn muốn theo dõi một danh sách ngắn hơn gồm các mốc được chọn có chủ đích. Đây là nhánh mà project hiện khuyến nghị cho việc phân phối downstream. Mỗi version release đều ghi rõ build tag tương ứng, còn các prebuilt binary nằm trên build tag đó, nên hãy ghi build number cùng với version. Hãy đọc notes trước khi chuyển tag, dù cách đánh số đã lên 1.x.

Dù chọn cách nào, quy tắc vận hành vẫn giống nhau. Chuỗi tag nằm trong một file, máy chỉ được build lại khi chuỗi đó thay đổi, và thay đổi này phải là một quyết định có chủ đích.

Biên dịch tag đã pin

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 phải in ra b10502. Shallow clone tại một tag chứa commit đó và không chứa các commit sau nó, nên không ai có thể vô tình di chuyển tag bằng git pull về sau. Nếu bước configure dừng vì thiếu dependency, hãy cài dependency được nêu rồi chạy lại.

Biên dịch với các tùy chọn phù hợp với phần cứng của bạn. Chỉ dùng CPU:

cmake -B build
cmake --build build --config Release -j $(nproc)

GPU NVIDIA, cần cài CUDA toolkit trước:

cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j $(nproc)

OpenBLAS trên máy chỉ dùng CPU:

cmake -B build -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS
cmake --build build --config Release -j $(nproc)

Các binary được đặt trong build/bin, cùng với các shared library mà chúng load (libllama.so và các file libggml). Xác nhận bản build chạy được trước khi cài:

./build/bin/llama-server --version

Cài toàn bộ thư mục vào một path đặt theo tên tag, rồi trỏ một symlink vào đó:

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

Hãy copy cả thư mục, không chỉ copy một file. Một llama-server riêng lẻ sẽ fail ngay lần chạy đầu tiên với error while loading shared libraries: libllama.so: cannot open shared object file, vì các library cần thiết nằm cạnh nó trong thư mục đó.

Trỏ service vào symlink, không bao giờ trỏ vào thư mục tag:

[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 resolve symlink khi khởi động process, nên để chuyển build, chỉ cần đổi target của symlink rồi chạy sudo systemctl restart llama-server. Phần còn lại của unit file và reverse proxy phía trước được trình bày trong hướng dẫn đầy đủ về llama.cpp server trên VPS.

Ghi tag bên cạnh file GGUF và quant

Bản build chỉ quyết định một phần output. File model quyết định phần còn lại. GGUF (GGML universal file format) là container chứa weights mà model được phát hành trong đó. Cùng một model có thể được phát hành ở nhiều mức quantisation. Vì vậy, hai server dùng cùng tag vẫn có thể cho kết quả khác nhau nếu một server có file Q4_K_M còn server kia có file Q8_0. Hãy đặt một file nhỏ bên cạnh model. File này phải chứa mọi thông tin cần thiết để dựng lại chính xác setup:

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>

Lấy commit bằng git rev-parse --short HEAD trong checkout đã pin. Lấy checksum bằng sha256sum model-q4_k_m.gguf và cũng so sánh với giá trị do publisher cung cấp tại thời điểm download. Việc kiểm tra file download với checksum đã công bố giúp phát hiện file bị cắt ngắn trước khi lỗi này trở thành một bug khó xác định. Mức quantisation tự nó ảnh hưởng đến câu trả lời nhiều đến đâu là một vấn đề riêng. Nội dung chi phí của từng mức quantisation trình bày vấn đề đó.

Nâng cấp thế nào mà không làm hỏng server?

Hãy thực hiện nâng cấp như một bài diễn tập. Build tag mới bên cạnh tag cũ, đo cả hai và giữ lại bản cũ cho đến khi bản mới hoạt động ổn định hơn.

  1. Clone tag mới vào thư mục riêng. Không dùng lại checkout cũ.
  2. Build bằng đúng các đối số cmake đã ghi trong manifest.
  3. Chạy llama-bench trên cả hai bản build với cùng một model file, cùng độ dài prompt và cùng số lần lặp.
  4. Gửi một prompt mà bạn biết rõ câu trả lời đến cả hai server, rồi đọc hai phản hồi.
  5. Di chuyển symlink, restart service và giữ thư mục cũ trên disk.
/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 in một dòng cho mỗi bài test, có cột backend, cột ngl và một cột tokens per second kèm độ lệch chuẩn. Hãy so sánh cùng một dòng giữa hai bản build, không so sánh dòng prompt của bản build này với dòng generation của bản build kia. Một số liệu được lấy ở độ dài prompt khác là một phép đo khác. Vì vậy, đo tokens per second theo cùng một cách mỗi lần quan trọng hơn bản thân con số đó.

Rollback chỉ cần hai lệnh và chỉ hoạt động vì thư mục cũ vẫn còn:

sudo ln -sfn /opt/llama.cpp/b10502 /opt/llama.cpp/current
sudo systemctl restart llama-server

Luôn giữ lại ít nhất bản build trước đó. Dung lượng của nó chỉ chiếm một phần nhỏ so với dung lượng mà model file bên cạnh đã sử dụng.

Những gì có thể hỏng khi nâng cấp llama.cpp

File model không tải được. Đây thường là lý do người dùng nâng cấp ngay từ đầu: model mới được phát hành dùng một architecture mà bản build đang cố định không biết, nên không bao giờ tải được. llama-server thoát trong lúc khởi động. Tính đến 21 October 2026, source của server ghi log failed to load model, '/srv/models/model-q4_k_m.gguf' cho lỗi này, kèm dấu phẩy và path trong dấu nháy đơn; dòng cuối cùng nó in ra là exiting due to model loading error, không chứa path. Hãy grep journal cho failed to load model thay vì tìm toàn bộ dòng log. Đọc các dòng được in ngay trước đó, bao gồm dòng error loading model: của loader, để biết loader đã xử lý đến đâu và dừng vì lý do gì. GGUF cũng chứa version của format trong header (giá trị hiện tại của spec là 3, còn version 2 đã mở rộng các trường độ dài từ 32 lên 64 bit), nhưng trên thực tế, tên architecture không được nhận diện sẽ làm quá trình dừng từ lâu trước khi kiểm tra version của format. Cách xử lý là dùng một tag mới hơn và ghi lại tag đó.

Flag của server bị đổi tên hoặc deprecated. Flag không được nhận diện sẽ làm llama-server dừng ngay khi khởi động thay vì bị bỏ qua. Khi chạy dưới systemd, lỗi này trông giống một service khởi động rồi chết trong vòng lặp. journalctl -u llama-server -n 50 hiển thị thông báo thực tế. Tính đến 19 August 2026, tài liệu server đánh dấu --mlock và --mmap là deprecated và khuyến nghị dùng -lm, --load-mode. Tính đến 21 October 2026, cả hai flag không còn xuất hiện trong tài liệu server hoặc danh sách argument trên master. Hãy chuyển hành vi tương ứng sang --load-mode, flag này nhận auto (giá trị mặc định), none, mmap, mlock, mmap+mlock và dio. Flag offload GPU được ghi trong tài liệu là -ngl, --gpu-layers, --n-gpu-layers, nên cách viết đầy đủ trong các hướng dẫn cũ vẫn được chấp nhận. Giá trị mặc định cũng thay đổi: kể từ v0.7.0, llama-server mặc định listen trên port 9931 thay vì 8080 (Docker image vẫn dùng port 8080 bên trong container). Vì vậy, unit file không khai báo --port sẽ không còn trả lời tại nơi reverse proxy đang trỏ đến. Bản phát hành v1.0.0 cũng loại bỏ flag deprecated --defrag-thold. Trước khi chuyển symlink, hãy chạy /opt/llama.cpp/<new tag>/bin/llama-server --help và kiểm tra từng flag trong unit file với output của lệnh này.

Build option bị đổi tên. Các CMake option đã đổi từ prefix LLAMA_ sang prefix GGML_, còn root CMakeLists.txt vẫn chứa mapping. LLAMA_CUBLAS hiện là lỗi fatal và nêu GGML_CUDA là option thay thế. LLAMA_CUDA và LLAMA_METAL tạo warning rồi tự được chuyển đổi. Một build script dừng ở bước configure là kết quả tốt. Lỗi âm thầm còn nguy hiểm hơn: vô tình bỏ qua -DGGML_CUDA=ON thì build vẫn thành công, server vẫn khởi động, nhưng mọi thứ chạy trên CPU. llama-bench hiển thị ngay điều này, vì cột backend có giá trị CPU.

Build cho accelerator không portable. Tính đến 19 August 2026, các Linux asset đính kèm build tag gồm các biến thể CPU, Vulkan, SYCL và OpenVINO cho x64, arm64 và s390x, nhưng không có CUDA archive cho Linux. Điều này đã thay đổi. Tính đến 21 October 2026, b11669, build tag đứng sau v0.7.0, cũng có Ubuntu CUDA archive cho CUDA 12.8 và 13.4 trên x64, CUDA 13.4 trên arm64, mỗi archive có một cudart- runtime archive tương ứng, cùng với một ROCm build. Trên cả Linux và Windows, CUDA archive được phát hành riêng theo từng toolkit version. Đây là một dấu hiệu hữu ích: toolkit version là một phần thông tin xác định binary của bạn, nên hãy ghi lại nó cùng với các CMake argument.

Thay vào đó, pin container image

Cùng một nguyên tắc, chỉ khác danh từ. Các image được publish (ghcr.io/ggml-org/llama.cpp:server và những biến thể accelerator của nó) là các tên có thể thay đổi, nên pull :server vào tháng sau có thể nhận một program khác dưới cùng label. Pull một lần rồi đọc digest:

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

docker pull in ra một dòng Digest: sha256:.... Đặt digest đó vào file compose thay cho tag. Image sẽ không thể tự thay đổi vào lần tiếp theo có người chạy docker compose pull. Giữ digest trước đó trong một comment để rollback chỉ cần sửa một dòng, giống như quy trình upgrade và rollback cho một Compose stack áp dụng cho mọi service khác.

Mục đích của việc pin phiên bản

Pin phiên bản giúp bạn xác định chính xác những gì đang chạy. Nó cũng cho phép khôi phục build trước đó trong vòng một phút khi một thay đổi gây ra lỗi.

llama.cpp yêu cầu bạn theo dõi 2 thành phần cho việc này: build tag và file model, vì nó cung cấp riêng từng thành phần. Các runtime đóng gói cả hai hoạt động khác nhau. Phần so sánh Ollama và llama.cpp khi làm server phân tích sự đánh đổi đó: một số phiên bản chung cho toàn bộ hệ thống sẽ dễ ghi lại và ít cần kiểm soát hơn.

FAQ

Tôi nên pin build tag bNNNN hay tag v0.x?

Cả hai đều được, miễn là bạn pin một tag cụ thể. Các build tag như b10502 là nhánh được duy trì lâu dài: các archive release dựng sẵn có tag này trong tên file (trừ các bundle CUDA runtime cho Windows), và phần lớn báo cáo lỗi cũng ghi tag này. Vì vậy, build number là thông tin dễ nhất để so sánh với máy chủ của người khác. Các version tag như v0.6.0 là danh sách ngắn hơn gồm những mốc được project chủ động chọn để phân phối downstream, phù hợp với máy chủ mà bạn chỉ thao tác vài lần mỗi năm. Mỗi version tag đều ghi build tag tương ứng, nên hãy lưu cả hai. Điều quan trọng hơn việc chọn loại tag nào là chuỗi tag phải được ghi cạnh file model, và việc nâng cấp phải là một quyết định rõ ràng thay vì là tác động phụ của git pull.

llama.cpp hiện đã tuân theo semantic versioning chưa?

Có, kể từ v0.2.0 vào ngày 21 August 2026. Release notes cho biết đây là điểm bắt đầu của việc áp dụng semantic versioning nhất quán cho llama.cpp, thay thế ghi chú đang trong quá trình hoàn thiện mà v0.1.2 từng mang. Tính đến ngày 14 November 2026, cách đánh version đã đạt 1.x; bản mới nhất là v1.0.0, được phát hành vào ngày 13 November. Đọc release notes trước khi chuyển sang bản mới, rồi test tag mới với chính file model của bạn trước khi chuyển hẳn sang, bất kể chữ số nào đã thay đổi.

Làm sao biết server đang chạy build llama.cpp nào?

llama-server --version in ra version và thông tin build, nên hãy chạy lệnh này với binary mà service sử dụng: /opt/llama.cpp/current/bin/llama-server --version. Tính đến ngày 21 October 2026, dòng khởi động chứa build number, commit hash và compiler được ghi ở trace level. Vì vậy, đừng mặc định rằng bạn sẽ thấy dòng này trong journalctl -u llama-server khi log vẫn ở log level mặc định. Với source install, git describe --tags bên trong checkout đã pin sẽ in ra tag, còn readlink /opt/llama.cpp/current cho biết service thực tế đang trỏ đến thư mục nào.

Vì sao model không còn load được sau khi tôi nâng cấp llama.cpp?

Lỗi load xảy ra ngay sau khi nâng cấp thường là do build không tương thích với file GGUF. Log có một dòng failed to load model, '<path>' ghi tên file và kết thúc bằng exiting due to model loading error; các dòng phía trên cho biết loader đã đọc đến đâu. Khi nâng cấp, file model mới có thể cần một build biết architecture của nó. Khi rollback, nếu lùi xuống dưới tag dùng để tạo file, một file vẫn chạy được hôm qua có thể bị lỗi. Hãy trỏ symlink về build trước đó, restart service, rồi xác nhận build nào ghép đúng với file nào trước khi quyết định thay đổi một trong hai.

Có binary Linux dựng sẵn để pin thay vì tự build không?

Có. Mỗi build tag đều có các archive release mang tên tag đó, chẳng hạn llama-b10502-bin-ubuntu-x64.tar.gz. Vì vậy, tag nằm ngay trong tên file và việc pin rất đơn giản. Vào ngày 19 August 2026, bộ Linux gồm CPU, arm64, s390x, Vulkan, SYCL và OpenVINO, không có archive CUDA. Tính đến ngày 21 October 2026, b11669 mới hơn cũng có archive Ubuntu CUDA 12.8 và 13.4, kèm các bundle cudart- runtime tương ứng. Vì vậy, server NVIDIA dùng tag mới không còn phải build từ source bằng -DGGML_CUDA=ON hoặc chạy CUDA container image. Nếu pin version tag, hãy tải archive từ build tag được ghi trong release notes của version đó.

Bài viết này có hữu ích không?