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

Những thay đổi trong cách đánh version 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 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.1.2, và cả hai track đều được tạo từ cùng một lịch sử tại cùng thời điểm.

Version tag hiện chưa mang ý nghĩa như version number thông thường. Release note tại v0.1.2 nêu rõ điều này trong một dòng:

Semantic versioning vẫn đang được hoàn thiện. Có thêm thông tin tại https://github.com/ggml-org/ggml/discussions/1579

Hãy hiểu đúng theo nghĩa đen. Cuộc thảo luận của ggml phía sau liên kết đó là nơi scheme này vẫn đang được xây dựng, bao gồm tần suất tạo release và tiêu chí xác định một patch. Tag v0. chỉ cho biết project đã chọn đánh dấu một điểm trong lịch sử. Nó không đảm bảo release tiếp theo là bản thay thế trực tiếp an toàn chỉ vì chữ số cuối tăng thêm một.

Con số trong build tag cũng không mang ý nghĩa về version. Nó xuất phát từ số lượng commit, nên tự tăng dù có hay không có thay đổi liên quan đến setup của bạn. Tính đến ngày 19 August 2026, trang đầu của danh sách release có chín build tag, từ b10455 đến b10502, trong đó có v0.1.2.

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 rebuild 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, nó 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 không ghi lại commit của thứ Ba, bạn sẽ không thể xác định nguyên nhân khi có phản ánh rằng câu trả lời đã kém hơn vào thứ Ba tuần trước.

Thay vào đó, hãy pin một tag. Project tạo tag cho bạn, và mọi release archive dựng sẵn đều được đặt tên theo tag đó.

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

Hãy pin một 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 dài, là nhánh mà các release archive được đặt tên theo, và là nhánh được nhắc đến trong phần lớn bug report. Vì vậy, build number là giá trị dễ nhất để so sánh với người khác.

Hãy pin một 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. Đọc notes của tag trước khi chuyển sang tag đó và ghi nhớ lưu ý ở trên, vì cách đánh số hiện chưa phải là một cam kết về compatibility.

Trong cả hai trường hợp, quy tắc vận hành là giống nhau. Chuỗi tag được lưu trong một file. Máy chỉ được build lại khi chuỗi đó thay đổi. Việc thay đổi 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 lại tag bên cạnh file GGUF và quant

Build chỉ quyết định một nửa output. File model quyết định nửa còn lại. GGUF (GGML universal file format) là container chứa weights mà model được phát hành cùng, và cùng một model thường được phát hành ở nhiều mức quantisation. Vì vậy, 2 server dùng cùng một 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 giữ một file nhỏ bên cạnh model, chứa mọi thông tin cần thiết để dựng lại setup chính xác:

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>

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

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.

Điều 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 khiến người dùng nâng cấp ngay từ đầu: model mới được phát hành sử dụng một architecture mà build đang được pin không nhận biết, nên model không bao giờ tải được. llama-server thoát trong lúc khởi động và log có dòng failed to load model from /srv/models/model-q4_k_m.gguf. Hãy đọc các dòng được in ngay trước đó. Chúng cho biết loader đã chạy đến đâu. GGUF cũng lưu version của format trong header (giá trị hiện tại trong 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ế, một tên architecture không được nhận biết sẽ làm quá trình dừng từ lâu trước khi version của format trở thành vấn đề. Cách sửa là chọn một tag mới hơn và ghi lại tag đó.

Một flag của server bị đổi tên hoặc deprecated. Flag không được nhận biết sẽ khiến llama-server dừng ngay khi khởi động thay vì bị bỏ qua. Khi chạy dưới systemd, điều 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 ngày 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 thay thế. Flag này nhận các giá trị như auto, mmap, mlock và dio. Tài liệu ghi flag GPU offload là -ngl, --gpu-layers, trong khi các hướng dẫn cũ viết là --n-gpu-layers. Trước khi di chuyển symlink, hãy chạy /opt/llama.cpp/<new tag>/bin/llama-server --help và đối chiếu mọi flag trong unit file với output của lệnh.

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

Build cho accelerator không portable. Tính đến ngày 19 August 2026, các asset Linux gắn với một build tag gồm các biến thể CPU, Vulkan, SYCL và OpenVINO cho x64, arm64 và s390x. Danh sách này không có archive CUDA cho Linux. Vì vậy, server NVIDIA phải build từ source hoặc chạy một container image. Các archive CUDA cho Windows được phát hành riêng theo từng version của toolkit. Đây là một gợi ý hữu ích: version của toolkit là một phần thông tin nhận diện binary của bạn, nên hãy ghi lại nó cùng với các argument của cmake.

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: mọi release archive dựng sẵn đều được đặt tên theo tag này và hầu hết báo cáo lỗi đều ghi tag tương ứng, nên build number là thông tin dễ đối chiếu nhất với operator khác. Các version tag như v0.1.2 là danh sách ngắn hơn gồm những mốc được chọn có chủ đích, phù hợp với server mà bạn chỉ vận hành vài lần mỗi năm. Điều quan trọng hơn việc chọn loại tag nào là chuỗi tag phải được ghi lại ngay cạnh model file, đồng thời việc nâng cấp phải là một quyết định rõ ràng thay vì tác dụng phụ của git pull.

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

Chưa, theo tuyên bố của chính dự án. Release notes v0.1.2 nói rằng semantic versioning vẫn đang được hoàn thiện và dẫn đến một cuộc thảo luận trên ggml, nơi scheme này đang được xây dựng, bao gồm chu kỳ release và tiêu chí xác định một patch. Hãy xem version tag là một mốc do maintainer chọn để đánh dấu. Đừng giả định rằng thay đổi ở chữ số cuối luôn bảo đảm có thể nâng cấp trực tiếp, và hãy test tag mới với model file của bạn trước khi chuyển sang dùng tag đó.

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

llama-server --version in ra version và thông tin build. Startup log cũng mở đầu bằng một dòng build chứa build number, commit hash và compiler được sử dụng, nên journalctl -u llama-server có thể tìm dòng này trong log của service đang chạy. Với source install, chạy 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 directory nào.

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

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

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

Có, với một số setup. Mỗi build tag đi kèm các release archive được đặt tên theo tag đó, chẳng hạn llama-b10502-bin-ubuntu-x64.tar.gz, cùng các variant arm64, s390x, Vulkan, SYCL và OpenVINO tính đến 19 August 2026. Cách đặt tên này giúp pin dễ dàng vì tag nằm ngay trong filename. Danh sách đó không có CUDA archive cho Linux, nên server NVIDIA vẫn cần build từ source bằng -DGGML_CUDA=ON hoặc chạy một trong các CUDA container image.