SSD Nodes Learn Hosting plans →
Przewodniki Matt ConnorAutor: Matt Connor

Jak przypiąć wersję llama.cpp na serwerze

Dowiedz się, jak zarządzać wersjami llama.cpp poprzez tagi vX.Y.Z oraz bNNNN. Zapewnij powtarzalność wyników, przypisując konkretny build do plików GGUF i kwantyzacji.

Zmiany w wersjonowaniu llama.cpp

Przypinanie wydań llama.cpp oznacza zbudowanie konkretnego tagu i zapisanie jego nazwy obok pliku modelu. Tag ten nie zmienia się samoczynnie, dzięki czemu serwer generuje te same wyniki dzisiaj i w przyszłości. Przez lata dostępny był tylko jeden rodzaj tagów: numer kompilacji, taki jak b10502, tworzony automatycznie z gałęzi master. Od 2026 roku istnieje drugi rodzaj, tag wersji, taki jak v0.6.0, a obie ścieżki nie są ze sobą zsynchronizowane. Tagi kompilacji powstają przy niemal każdym commicie do master. Tagi wersji są tworzone ręcznie przez opiekunów projektu w wolniejszym tempie, a każde wydanie wersji wskazuje odpowiadający mu tag kompilacji.

Tagi wersji początkowo miały charakter próbny. Informacje o wydaniu v0.1.2, opublikowane 18 sierpnia 2026 roku, zawierały jedno zdanie:

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

Trzy dni później v0.2.0 uregulowało tę kwestię. Informacje o wydaniu wskazują, że wersja ta „stanowi początek spójnego wersjonowania semantycznego dla llama.cpp”. Opisują one tagi vX.Y.Z jako stabilne wersje o wolniejszym cyklu wydawniczym, zalecane dla dystrybucji downstream oraz użytkowników końcowych, natomiast tagi b[NUM] jako kompilacje typu nightly lub deweloperskie z najnowszymi funkcjami, zalecane dla programistów i użytkowników technicznych. Według stanu na 14 listopada 2026 roku najnowszym tagiem wersji jest v1.0.0, wydany 13 listopada, a w jego notatkach jako odpowiadający mu tag kompilacji wskazano b12359.

Dyskusja ggml pod tym linkiem nadal zawiera uzasadnienie tego schematu i według stanu na 21 października 2026 roku pozostaje otwarta na opinie. Numeracja wersji osiągnęła poziom 1.x, dlatego przed każdą aktualizacją należy zapoznać się z notatkami, zamiast oceniać zmianę wyłącznie na podstawie tego, która cyfra uległa zmianie.

Liczba w tagu kompilacji nie niesie ze sobą znaczenia wersji. Wynika ona z liczby commitów, więc rośnie samoistnie niezależnie od tego, czy zmiany mają znaczenie dla danej konfiguracji.

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

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

Zamiast tego należy przypiąć konkretny tag. Projekt udostępnia je automatycznie, a gotowe archiwa z wydaniami zawierają tag kompilacji w nazwach plików, z wyjątkiem pakietów Windows CUDA runtime (cudart-llama-bin-win-...).

Do którego tagu wydań llama.cpp należy przypiąć wersję?

Przypnij tag build, jeśli chcesz uzyskać jeden konkretny, znany stan. Jest to ścieżka z długą historią, od której pochodzą nazwy archiwów wydań i którą cytuje większość zgłoszeń błędów, więc numer kompilacji jest najłatwiejszym punktem odniesienia przy porównywaniu wersji z innymi użytkownikami.

Przypnij tag wersji, jeśli wolisz śledzić krótszą listę celowo wybranych punktów. Jest to ścieżka, którą projekt obecnie zaleca dla dystrybucji typu downstream. Każde wydanie wersji wskazuje odpowiadający mu tag build, a gotowe pliki binarne znajdują się pod tym tagiem build, dlatego należy zapisać numer kompilacji obok wersji. Przed aktualizacją przeczytaj notatki, nawet jeśli numeracja osiągnęła poziom 1.x.

W obu przypadkach zasada operacyjna jest identyczna. Ciąg znaków tagu znajduje się w pliku, serwer jest przebudowywany tylko wtedy, gdy ten ciąg ulegnie zmianie, a zmiana ta jest decyzją podjętą przez kogoś celowo.

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. Obok modelu należy przechowywać mały plik zawierający wszystkie dane niezbędne do dokładnego odtworzenia konfiguracji:

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>

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ą trudnych do zdiagnozowania błędów. Kwestia tego, w jakim stopniu sam poziom kwantyzacji zmienia odpowiedzi, jest osobnym zagadnieniem, które zostało omówione w kosztach poszczególnych poziomów 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 powód, dla którego użytkownicy decydują się na aktualizację: nowo opublikowany model wykorzystuje architekturę, której używana wersja nie obsługuje, więc wczytywanie kończy się niepowodzeniem. llama-server kończy działanie podczas uruchamiania. Według stanu na 21 października 2026 dziennik serwera rejestruje dla tego zdarzenia failed to load model, '/srv/models/model-q4_k_m.gguf', wraz z przecinkiem i ścieżką w pojedynczym cudzysłowie, a ostatnia drukowana linia to exiting due to model loading error, która nie zawiera ścieżki. Należy przeszukać dziennik za pomocą grep pod kątem failed to load model, zamiast szukać pełnej linii. Należy przeczytać linie wydrukowane bezpośrednio przed tym komunikatem, w tym linię error loading model: samego modułu ładującego, które wskazują, na jakim etapie proces został przerwany i dlaczego. 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 działanie znacznie wcześniej niż wersja formatu. Rozwiązaniem jest nowszy tag, wybrany i odnotowany w dokumentacji.

Flaga serwera zostaje zmieniona lub wycofana. Nierozpoznana flaga powoduje zatrzymanie llama-server podczas uruchamiania, zamiast być ignorowaną, co w systemd wygląda jak 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 oznaczyła --mlock oraz --mmap jako przestarzałe na rzecz -lm, --load-mode. Według stanu na 21 października 2026 żadna z tych flag nie występuje już w dokumentacji serwera ani na liście argumentów w gałęzi master, więc należy przenieść zachowanie za pomocą --load-mode, która przyjmuje auto (wartość domyślna), none, mmap, mlock, mmap+mlock oraz dio. Flaga odciążania GPU jest udokumentowana jako -ngl, --gpu-layers, --n-gpu-layers, więc dłuższa pisownia ze starszych poradników jest nadal akceptowana. Wartości domyślne również ulegają zmianie: od v0.7.0 llama-server domyślnie nasłuchuje na porcie 9931 zamiast 8080 (obrazy Docker zachowują 8080 wewnątrz kontenera), więc plik jednostki, który pomija --port, przestaje odpowiadać tam, gdzie oczekuje tego reverse proxy. Wydanie v1.0.0 usuwa również przestarzałą flagę --defrag-thold. Przed przeniesieniem dowiązania symbolicznego należy uruchomić /opt/llama.cpp/<new tag>/bin/llama-server --help i sprawdzić każdą flagę w pliku jednostki pod kątem zgodności.

Opcja budowania zostaje zmieniona. Opcje CMake zostały przeniesione z prefiksu LLAMA_ na prefiks GGML_, a główny plik CMakeLists.txt nadal zawiera mapowanie. LLAMA_CUBLAS jest teraz błędem krytycznym wskazującym GGML_CUDA jako zamiennik, podczas gdy LLAMA_CUDA i LLAMA_METAL generują ostrzeżenie i są tłumaczone automatycznie. Skrypt budowania, który zatrzymuje się na etapie konfiguracji, jest pożądanym wynikiem. Cicha awaria jest gorsza: pominięcie -DGGML_CUDA=ON przez przypadek powoduje, że budowanie kończy się sukcesem, serwer startuje, a wszystko działa na CPU. llama-bench pokazuje to natychmiast, ponieważ kolumna backend wskazuje CPU.

Budowanie akceleratora nie jest przenośne. Według stanu na 19 sierpnia 2026 zasoby Linux dołączone do tagu budowania obejmowały warianty CPU, Vulkan, SYCL i OpenVINO dla architektur x64, arm64 oraz s390x, bez archiwum CUDA dla systemu Linux. Od tego czasu sytuacja uległa zmianie. Według stanu na 21 października 2026 b11669, tag budowania stojący za v0.7.0, zawiera również archiwa Ubuntu CUDA dla CUDA 12.8 i 13.4 na x64 oraz CUDA 13.4 na arm64, każde z pasującym archiwum środowiska uruchomieniowego cudart-, a także budowanie ROCm. Archiwa CUDA są publikowane dla każdej wersji zestawu narzędzi zarówno w systemie Linux, jak i Windows, co stanowi użyteczną wskazówkę: wersja zestawu narzędzi jest częścią identyfikatora pliku binarnego, więc należy ją odnotować obok argumentów 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 należy przypiąć tag kompilacji bNNNN czy tag v0.x?

Oba rozwiązania są poprawne, o ile zostanie zastosowane jakiekolwiek przypięcie. Tagi kompilacji, takie jak b10502, stanowią ścieżkę długoterminową: gotowe archiwa wydań zawierają je w nazwach plików (z wyłączeniem pakietów środowiska uruchomieniowego CUDA dla Windows), a większość zgłoszeń błędów odwołuje się właśnie do nich, co czyni numer kompilacji najwygodniejszym punktem odniesienia dla operatora. Tagi wersji, takie jak v0.6.0, to krótsza lista przemyślanych punktów kontrolnych zalecanych przez projekt dla dystrybucji zewnętrznych, co sprawdza się w przypadku serwerów aktualizowanych rzadko. Każdy z nich wskazuje odpowiadający mu tag kompilacji, dlatego należy odnotować oba. Ważniejsze od wyboru jest zapisanie ciągu tagu obok pliku modelu oraz traktowanie aktualizacji jako świadomej decyzji, a nie efektu ubocznego git pull.

Czy llama.cpp stosuje teraz wersjonowanie semantyczne?

Tak, od v0.2.0 z dnia 21 sierpnia 2026 roku. Informacje o wydaniu wskazują, że oznacza to początek spójnego wersjonowania semantycznego dla llama.cpp, zastępując zastrzeżenie o pracy w toku, które niosło ze sobą v0.1.2. Według stanu na 14 listopada 2026 roku numeracja wersji osiągnęła poziom 1.x, a najnowsza wersja to v1.0.0, wydana 13 listopada. Przed aktualizacją należy zapoznać się z informacjami o wydaniu i przetestować nowy tag z własnym plikiem modelu, niezależnie od tego, która cyfra uległa zmianie.

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

llama-server --version wyświetla informacje o wersji i kompilacji, dlatego należy uruchomić to polecenie dla pliku binarnego używanego przez usługę: /opt/llama.cpp/current/bin/llama-server --version. Od 21 października 2026 roku linia startowa zawierająca numer kompilacji, skrót commitu oraz kompilator jest rejestrowana na poziomie trace, więc nie należy oczekiwać znalezienia jej w journalctl -u llama-server przy domyślnym poziomie logowania. W przypadku instalacji ze źródeł, git describe --tags wewnątrz przypiętego katalogu wyświetla tag, a readlink /opt/llama.cpp/current wskazuje, do którego katalogu faktycznie odwołuje się usługa.

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

Błąd ładowania bezpośrednio po aktualizacji wynika z niedopasowania między kompilacją a plikiem GGUF. Dziennik zawiera linię failed to load model, '<path>' z nazwą pliku i kończy się komunikatem exiting due to model loading error, a linie powyżej wskazują, jak daleko dotarł moduł ładujący. Przy aktualizacji do nowszej wersji, nowy plik modelu wymaga kompilacji obsługującej jego architekturę. Przy przywracaniu starszej wersji, wycofanie do kompilacji poniżej tagu, dla którego plik został utworzony, może spowodować błąd w pliku, który działał wcześniej. Należy skierować dowiązanie symboliczne na poprzednią kompilację, zrestartować usługę i potwierdzić poprawność pary kompilacja-plik przed podjęciem decyzji o zmianie jednego z nich.

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

Tak. Każdy tag kompilacji posiada odpowiadające mu archiwa wydań, takie jak llama-b10502-bin-ubuntu-x64.tar.gz, więc tag znajduje się w nazwie pliku i przypięcie jest proste. W dniu 19 sierpnia 2026 roku zestaw dla Linux obejmował CPU, arm64, s390x, Vulkan, SYCL oraz OpenVINO, bez archiwum CUDA. Od 21 października 2026 roku nowsze b11669 zawiera również archiwa Ubuntu CUDA 12.8 oraz 13.4 z pasującymi pakietami środowiska uruchomieniowego cudart-, dzięki czemu serwer NVIDIA z nowszym tagiem nie musi być kompilowany ze źródeł za pomocą -DGGML_CUDA=ON ani uruchamiany z obrazu kontenera CUDA. W przypadku przypięcia tagu wersji, należy pobrać archiwa z tagu kompilacji wskazanego w informacjach o wydaniu.

Czy ten artykuł był przydatny?