Jak przypiąć wersję llama.cpp na serwerze

Co zmieniło się w wersjonowaniu llama.cpp

Przypinanie wydań llama.cpp oznacza zbudowanie konkretnego tagu i zapisanie jego nazwy obok pliku modelu. Tag ten nigdy nie zmienia się samoczynnie, dzięki czemu serwer będzie generował jutro to samo, co generuje dzisiaj. Przez lata dostępny był tylko jeden rodzaj tagu: numer kompilacji, taki jak b10502, tworzony automatycznie z gałęzi master. Od 2026 roku istnieje drugi rodzaj, tag wersji, taki jak v0.1.2, przy czym obie ścieżki są tworzone z tej samej historii w tym samym czasie.

Tagi wersji nie oznaczają jeszcze tego, co zazwyczaj oznacza numer wersji. Informacje o wydaniu na v0.1.2 określają to w jednym zdaniu:

Wersjonowanie semantyczne jest wciąż w fazie prac. Więcej informacji można znaleźć pod adresem https://github.com/ggml-org/ggml/discussions/1579

Należy traktować to dosłownie. Dyskusja w ggml pod tym linkiem to miejsce, w którym schemat jest nadal opracowywany, w tym kwestie częstotliwości tworzenia wydań oraz tego, co kwalifikuje się jako poprawka. Tag v0. informuje jedynie, że projekt zdecydował się oznaczyć dany punkt w historii. Nie gwarantuje on, że kolejne wydanie będzie bezpiecznym zamiennikiem tylko dlatego, że ostatnia cyfra zmieniła się o jeden.

Numer w tagu kompilacji również nie niesie ze sobą żadnego znaczenia wersyjnego. Wynika on z liczby commitów, więc rośnie samoczynnie niezależnie od tego, czy w danej konfiguracji zaszły istotne zmiany. Na dzień 19 sierpnia 2026 roku strona główna listy wydań zawierała dziewięć tagów kompilacji, od b10455 do b10502, z tagiem v0.1.2 umieszczonym pomiędzy nimi.

Nigdy nie buduj oprogramowania z gałęzi master na serwerze produkcyjnym

git pull połączone z przebudowaniem powoduje wdrożenie kodu, który trafił do repozytorium w ciągu ostatnich kilku godzin. Jest to dopuszczalne na komputerze osobistym. Na serwerze uniemożliwia to udzielenie odpowiedzi na kluczowe pytanie w przypadku zmiany zachowania systemu: co jest uruchomione teraz, a co działało w zeszłym tygodniu. Treść generowana przez model oraz szybkość jego pracy zmieniają się wraz z każdą kompilacją. Reklamacja dotycząca pogorszenia jakości odpowiedzi w miniony wtorek pozostaje bez odpowiedzi, jeśli wtorkowy commit nie został w żaden sposób zarejestrowany.

Zamiast tego należy przypiąć konkretny tag. Projekt udostępnia je automatycznie, a każde gotowe archiwum wydania jest nazwane zgodnie z jednym z nich.

Do którego tagu przypinać wydania llama.cpp?

Przypnij tag kompilacji (build tag), gdy wymagany jest jeden konkretny, znany stan. Jest to ścieżka z długą historią, od której pochodzą nazwy archiwów wydań i do której odnosi się większość zgłoszeń błędów, dlatego numer kompilacji jest najłatwiejszym punktem odniesienia przy porównywaniu wersji z innymi użytkownikami.

Przypnij tag wersji (version tag), jeśli preferowane jest śledzenie krótszej listy przemyślanych punktów kontrolnych. Przed zmianą należy zapoznać się z informacjami o wydaniu i pamiętać o powyższym zastrzeżeniu, ponieważ numeracja nie stanowi jeszcze gwarancji kompatybilności.

W obu przypadkach zasada operacyjna pozostaje identyczna. Ciąg znaków tagu znajduje się w pliku, kontener jest przebudowywany tylko wtedy, gdy ten ciąg ulegnie zmianie, a sama zmiana jest celową decyzją administratora.

Budowa przypiętej wersji (tagu)

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 powinno wypisać b10502. Płytki klon (shallow clone) na konkretnym tagu przechowuje tylko ten commit i nic poza nim, więc nikt nie może go później przesunąć przez nieostrożne git pull. Jeśli krok konfiguracji zatrzyma się z powodu brakującej zależności, zainstaluj wskazany pakiet i uruchom proces ponownie.

Buduj z opcjami wymaganymi przez posiadany sprzęt. Tylko CPU:

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

NVIDIA GPU, co wymaga wcześniejszej instalacji CUDA toolkit:

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

OpenBLAS na maszynie tylko z CPU:

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

Pliki binarne trafiają do build/bin, obok współdzielonych bibliotek, które ładują (libllama.so oraz pliki libggml). Przed instalacją potwierdź, że kompilacja działa poprawnie:

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

Zainstaluj cały katalog w ścieżce nazwanej zgodnie z tagiem, a następnie wskaż go za pomocą dowiązania symbolicznego (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

Kopiuj cały katalog, a nie pojedynczy plik. Samotny llama-server nie uruchomi się przy pierwszej próbie, zwracając error while loading shared libraries: libllama.so: cannot open shared object file, ponieważ potrzebne mu biblioteki znajdują się obok niego w tym samym katalogu.

Skieruj usługę na dowiązanie symboliczne, nigdy bezpośrednio na katalog z tagiem:

[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 rozwiązuje dowiązanie symboliczne w momencie uruchamiania procesu, więc przełączenie wersji sprowadza się do zmiany celu dowiązania i wykonania sudo systemctl restart llama-server. Pozostała część pliku jednostki oraz konfiguracja reverse proxy przed nim zostały opisane w pełnym przewodniku po serwerze llama.cpp na VPS.

Zapisz tag obok pliku GGUF oraz poziom kwantyzacji

Kompilacja decyduje o wyniku w połowie. Drugą połowę stanowi plik modelu. GGUF (GGML universal file format) to kontener, w którym dostarczane są wagi. Ten sam model jest publikowany na wielu poziomach kwantyzacji, więc dwa serwery korzystające z tego samego tagu mogą generować różne wyniki, jeśli jeden używa pliku Q4_K_M, a drugi Q8_0. Przechowuj mały plik obok modelu, zawierający wszystkie dane niezbędne do dokładnego odtworzenia konfiguracji:

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>

Pobierz commit za pomocą git rev-parse --short HEAD wewnątrz przypiętego checkoutu. Pobierz sumę kontrolną za pomocą sha256sum model-q4_k_m.gguf i porównaj ją z wartością podaną przez wydawcę w momencie pobierania, ponieważ weryfikacja pobranego pliku względem opublikowanej sumy kontrolnej pozwala wykryć obcięty plik, zanim stanie się on przyczyną trudnego do zdiagnozowania błędu. Kwestia tego, w jakim stopniu sam poziom kwantyzacji zmienia odpowiedzi, jest osobnym zagadnieniem, które opisuje koszt każdego poziomu kwantyzacji.

Jak przeprowadzić aktualizację bez uszkodzenia serwera?

Aktualizację należy przeprowadzić w trybie próbnym. Należy zbudować nową wersję obok starej, porównać wyniki obu i zachować starą wersję do momentu potwierdzenia poprawności nowej.

1. Sklonuj nową wersję do oddzielnego katalogu. Nie używaj ponownie starego katalogu roboczego.
2. Przeprowadź budowanie z tymi samymi argumentami cmake, które zapisano w manifeście.
3. Uruchom llama-bench dla obu kompilacji, używając tego samego pliku modelu, tej samej długości promptu oraz tej samej liczby powtórzeń.
4. Wyślij prompt, którego odpowiedź jest znana, do obu serwerów i porównaj otrzymane odpowiedzi.
5. Przełącz dowiązanie symboliczne (symlink), zrestartuj usługę i pozostaw stary katalog na dysku.

/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 drukuje jeden wiersz na test, zawierający kolumnę backend, kolumnę ngl oraz kolumnę liczby tokenów na sekundę wraz z odchyleniem standardowym. Należy porównywać ten sam wiersz między dwiema kompilacjami, a nie wiersz promptu jednej kompilacji z wierszem generowania drugiej. Wynik uzyskany przy innej długości promptu stanowi inny pomiar, dlatego mierzenie liczby tokenów na sekundę w ten sam sposób za każdym razem jest ważniejsze niż sama wartość liczbowa.

Wycofanie zmian wymaga dwóch poleceń i działa tylko dlatego, że stary katalog nadal znajduje się na dysku:

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

Należy zachować co najmniej poprzednią wersję kompilacji. Zajmuje ona ułamek miejsca na dysku, które i tak jest już wykorzystywane przez plik modelu.

Co ulega awarii podczas aktualizacji llama.cpp

Plik modelu przestaje się wczytywać. Jest to zazwyczaj główny powód aktualizacji: nowo opublikowany model wykorzystuje architekturę, której nie obsługuje zainstalowana wersja, więc wczytywanie kończy się niepowodzeniem. llama-server wyłącza się podczas uruchamiania, a dziennik zawiera linię failed to load model from /srv/models/model-q4_k_m.gguf. Należy przeanalizować linie wyświetlone bezpośrednio przed tym komunikatem, które wskazują etap, na którym zatrzymał się moduł ładujący. Format GGUF zawiera również wersję formatu w nagłówku (obecna wartość specyfikacji to 3, a wersja 2 rozszerzyła pola długości z 32 do 64 bitów), choć w praktyce nieznana nazwa architektury blokuje proces znacznie wcześniej niż wersja formatu. Rozwiązaniem jest wybór nowszego tagu i odnotowanie go.

Flaga serwera zostaje zmieniona lub uznana za przestarzałą. Nierozpoznana flaga powoduje zatrzymanie llama-server podczas startu, zamiast być ignorowaną, co w systemd objawia się jako usługa uruchamiająca się i wyłączająca w pętli. journalctl -u llama-server -n 50 wyświetla rzeczywisty komunikat o błędzie. Według stanu na 19 sierpnia 2026 dokumentacja serwera oznacza --mlock oraz --mmap jako przestarzałe na rzecz -lm, --load-mode, która przyjmuje wartości takie jak auto, mmap, mlock oraz dio. Flaga odciążania GPU jest udokumentowana jako -ngl, --gpu-layers, podczas gdy starsze poradniki używają --n-gpu-layers. Przed przeniesieniem dowiązania symbolicznego należy uruchomić /opt/llama.cpp/<new tag>/bin/llama-server --help i porównać każdą flagę w pliku jednostki z wynikami tego polecenia.

Opcja kompilacji zostaje zmieniona. Opcje CMake przeniesiono z prefiksu LLAMA_ na prefiks GGML_, a główny plik CMakeLists.txt nadal zawiera mapowanie. LLAMA_CUBLAS jest obecnie błędem krytycznym wskazującym GGML_CUDA jako zamiennik, podczas gdy LLAMA_CUDA oraz LLAMA_METAL generują ostrzeżenie i są automatycznie tłumaczone. Skrypt budowania, który zatrzymuje się na etapie konfiguracji, jest pożądanym wynikiem. Cicha awaria jest gorsza: przypadkowe pominięcie -DGGML_CUDA=ON sprawia, że kompilacja kończy się sukcesem, serwer startuje, a wszystko działa na procesorze CPU. llama-bench wykazuje to natychmiast, ponieważ kolumna backend zawiera wartość CPU.

Kompilacja akceleratora nie jest przenośna. Według stanu na 19 sierpnia 2026 zasoby dla systemu Linux przypisane do tagu kompilacji obejmują warianty CPU, Vulkan, SYCL oraz OpenVINO dla architektur x64, arm64 i s390x. Na tej liście nie ma archiwum CUDA dla systemu Linux, więc w przypadku serwera z NVIDIA konieczne jest budowanie ze źródeł lub uruchomienie obrazu kontenera. Archiwa CUDA dla systemu Windows są publikowane dla każdej wersji zestawu narzędzi, co stanowi przydatną wskazówkę: wersja zestawu narzędzi jest częścią identyfikatora pliku binarnego, dlatego należy ją zapisać wraz z argumentami cmake.

Przypinanie obrazu kontenera zamiast tego

Obowiązuje ta sama zasada, lecz dotyczy innego obiektu. Publikowane obrazy (ghcr.io/ggml-org/llama.cpp:server oraz jego warianty akcelerowane) to nazwy zmienne, więc pobranie :server w przyszłym miesiącu dostarczy inny program pod tą samą etykietą. Należy pobrać obraz raz i odczytać jego skrót (digest):

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

docker pull wyświetla linię Digest: sha256:.... Należy umieścić ten skrót w pliku compose zamiast tagu, dzięki czemu obraz nie zmieni się w sposób niekontrolowany przy kolejnym uruchomieniu docker compose pull. Warto zachować poprzedni skrót w komentarzu, aby wycofanie zmian wymagało tylko jednej edycji, w sposób analogiczny do tego, jak procedura aktualizacji i wycofywania zmian dla stosu Compose traktuje każdą inną usługę.

Istota przypięcia wersji

Przypięcie wersji pozwala precyzyjnie określić, co jest uruchomione, oraz umożliwia przywrócenie poprzedniej kompilacji w ciągu minuty, jeśli wprowadzona zmiana pogarsza działanie systemu. W przypadku llama.cpp należy śledzić dwa elementy: tag kompilacji oraz plik modelu, ponieważ są one dostarczane oddzielnie. Środowiska uruchomieniowe, które łączą te elementy w jeden pakiet, działają inaczej, a porównanie Ollama i llama.cpp jako serwerów omawia ten kompromis: jeden numer wersji dla całości oznacza mniej danych do zapisania i łatwiejszą kontrolę.

FAQ

Czy powinienem przypiąć tag kompilacji bNNNN czy tag v0.x?

Oba rozwiązania są poprawne, o ile zostanie zastosowane przypięcie. Tagi kompilacji, takie jak b10502, stanowią ścieżkę długoterminową: każde gotowe archiwum z wydaniem jest tak nazywane, a większość zgłoszeń błędów odwołuje się do tego oznaczenia, więc numer kompilacji jest najłatwiejszy do porównania z innym operatorem. Tagi wersji, takie jak v0.1.2, to krótsza lista przemyślanych punktów kontrolnych, co sprawdza się w przypadku serwera obsługiwanego kilka razy w roku. Ważniejsze od wyboru jest to, aby ciąg znaków tagu był zapisany obok pliku modelu, a aktualizacja była świadomą decyzją, a nie skutkiem ubocznym git pull.

Czy llama.cpp stosuje obecnie wersjonowanie semantyczne?

Jeszcze nie, zgodnie z deklaracją twórców projektu. Informacje o wydaniu v0.1.2 wskazują, że wersjonowanie semantyczne jest wciąż w fazie prac i odsyłają do dyskusji w ramach ggml, gdzie opracowywany jest schemat, w tym częstotliwość wydań oraz definicja poprawki. Tag wersji należy traktować jako punkt wybrany przez opiekunów projektu. Nie należy zakładać, że zmiana ostatniej cyfry gwarantuje bezproblemową aktualizację; przed przełączeniem należy przetestować nowy tag z własnym plikiem modelu.

Jak sprawdzić, która kompilacja llama.cpp działa na serwerze?

llama-server --version wyświetla informacje o wersji i kompilacji. Dziennik uruchomienia rozpoczyna się również linią build, zawierającą numer kompilacji, skrót commitu oraz użyty kompilator, więc journalctl -u llama-server pozwala odnaleźć te dane dla działającej usługi. W przypadku instalacji ze źródeł, git describe --tags wewnątrz przypiętego katalogu wyświetla tag, a readlink /opt/llama.cpp/current wskazuje, na który katalog faktycznie wskazuje usługa.

Dlaczego mój model przestał się ładować po aktualizacji llama.cpp?

Błąd ładowania bezpośrednio po aktualizacji wynika z niedopasowania kompilacji do pliku GGUF. Dziennik kończy się linią failed to load model from wskazującą ścieżkę, a linie powyżej pokazują, jak daleko dotarł moduł ładujący. W przypadku aktualizacji do nowszej wersji, bardzo nowy plik modelu wymaga kompilacji obsługującej jego architekturę. W przypadku cofnięcia wersji, powrót poniżej tagu, dla którego plik został utworzony, może spowodować błąd pliku, który działał wcześniej. Należy skierować dowiązanie symboliczne na poprzednią kompilację, zrestartować usługę i potwierdzić, która para kompilacji i pliku działa poprawnie, przed podjęciem decyzji o zmianie jednego z nich.

Czy istnieją gotowe pliki binarne dla Linux, które można przypiąć zamiast kompilować?

Tak, dla niektórych konfiguracji. Każdy tag kompilacji zawiera archiwa wydań nazwane zgodnie z nim, takie jak llama-b10502-bin-ubuntu-x64.tar.gz, wraz z wariantami arm64, s390x, Vulkan, SYCL oraz OpenVINO, według stanu na 19 sierpnia 2026. Nazewnictwo ułatwia przypinanie, ponieważ tag znajduje się w nazwie pliku. Na tej liście nie było archiwum CUDA dla Linux, więc serwer z NVIDIA nadal wymaga kompilacji ze źródeł za pomocą -DGGML_CUDA=ON lub uruchomienia jednego z obrazów kontenerowych CUDA.