llama.cpp-Versionen auf dem Server festlegen

Was sich an der Versionierung von llama.cpp geändert hat

Das Festlegen von llama.cpp-Releases bedeutet, einen benannten Tag zu bauen und diesen Namen neben der Modelldatei zu dokumentieren. Der Tag ändert sich nicht von selbst. Dadurch erzeugt der Server morgen weiterhin dasselbe wie heute. Über Jahre gab es nur eine Art von Tag: eine Build-Nummer wie b10502, die automatisch aus master erstellt wurde. Seit 2026 gibt es eine zweite Art, einen Versionstag wie v0.1.2. Beide Entwicklungszweige werden gleichzeitig aus derselben Historie erstellt.

Die Versionstags bedeuten noch nicht das, was eine Versionsnummer normalerweise bedeutet. In den Release Notes unter v0.1.2 steht dazu ein einzelner Satz:

Semantic versioning is still work in progress. More info can be found in https://github.com/ggml-org/ggml/discussions/1579

Nehmen Sie diese Aussage wörtlich. Die ggml-Diskussion hinter diesem Link ist der Ort, an dem das Schema noch ausgearbeitet wird. Dazu gehört auch, wie häufig ein Release erstellt wird und was als Patch gilt. Ein Tag wie v0. zeigt, dass das Projekt einen bestimmten Punkt in der Historie markiert hat. Er verspricht nicht, dass der nächste Release problemlos als Ersatz verwendet werden kann, nur weil sich die letzte Ziffer um eins erhöht hat.

Auch die Zahl in einem Build-Tag hat keine Versionsbedeutung. Sie stammt aus der Anzahl der Commits und steigt daher von selbst, unabhängig davon, ob sich für Ihre Umgebung etwas Relevantes geändert hat. Am 19. August 2026 enthielt die Startseite der Release-Liste neun Build-Tags, von b10455 bis b10502, darunter auch v0.1.2.

Bauen Sie niemals aus dem master-Zweig auf einem Server, der Dienste bereitstellt

git pull gefolgt von einem erneuten Build liefert Ihnen alles, was in den letzten Stunden hinzugekommen ist. Auf einem Laptop ist das unproblematisch. Auf einem Server verlieren Sie dadurch die Möglichkeit, die entscheidende Frage zu beantworten, wenn sich das Verhalten ändert: Was läuft jetzt, und was lief letzte Woche? Der von einem Modell erzeugte Text und die Geschwindigkeit, mit der es ihn erzeugt, ändern sich mit dem Build. Eine Meldung, dass die Antworten am vergangenen Dienstag schlechter wurden, lässt sich nicht nachvollziehen, wenn der Commit vom Dienstag nie dokumentiert wurde.

Verwenden Sie stattdessen ein festgelegtes Tag. Das Projekt erstellt diese Tags für Sie, und jedes vorgefertigte Release-Archiv trägt den Namen eines solchen Tags.

An welchen Tag sollten Sie llama.cpp-Releases anheften?

Heften Sie einen Build-Tag an, wenn Sie einen bestimmten, bekannten Stand verwenden möchten. Diese Reihe hat die längere Historie. Nach ihr sind die Release-Archive benannt. Die meisten Fehlerberichte beziehen sich ebenfalls darauf. Deshalb lässt sich eine Build-Nummer am einfachsten mit der Angabe einer anderen Person vergleichen.

Heften Sie einen Versions-Tag an, wenn Sie lieber einer kürzeren Liste bewusst gesetzter Stände folgen möchten. Lesen Sie die Hinweise, bevor Sie wechseln. Berücksichtigen Sie außerdem den obigen Vorbehalt, da die Nummerierung noch kein Kompatibilitätsversprechen darstellt.

In beiden Fällen gilt dieselbe Betriebsregel. Die Tag-Zeichenfolge steht in einer Datei. Das System wird nur neu erstellt, wenn sich diese Zeichenfolge ändert. Die Änderung muss bewusst entschieden worden sein.

Den fixierten Tag erstellen

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 sollte b10502 ausgeben. Ein flacher Klon eines Tags enthält diesen Commit und keine späteren Commits. Dadurch kann ihn später niemand versehentlich mit git pull verschieben. Wenn der Konfigurationsschritt wegen einer fehlenden Abhängigkeit abbricht, installieren Sie das genannte Paket und führen Sie den Schritt erneut aus.

Erstellen Sie den Build mit den für Ihre Hardware erforderlichen Optionen. Nur CPU:

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

NVIDIA-GPU; dafür muss zuerst das CUDA toolkit installiert werden:

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

OpenBLAS auf einem Rechner, der nur die CPU verwendet:

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

Die Binärdateien werden in build/bin abgelegt, neben den gemeinsam verwendeten Bibliotheken, die sie laden (libllama.so und die libggml-Dateien). Prüfen Sie vor der Installation, ob der Build ausgeführt werden kann:

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

Installieren Sie das gesamte Verzeichnis unter einem nach dem Tag benannten Pfad. Verweisen Sie anschließend einen Symlink darauf:

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

Kopieren Sie das Verzeichnis, nicht nur die einzelne Datei. Eine einzelne llama-server-Datei schlägt beim ersten Start mit error while loading shared libraries: libllama.so: cannot open shared object file fehl, weil sich die benötigten Bibliotheken daneben in diesem Verzeichnis befinden.

Verweisen Sie beim Dienst auf den Symlink, niemals auf ein Tag-Verzeichnis:

[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 wertet den Symlink auf, wenn es den Prozess startet. Zum Wechseln des Builds benötigen Sie daher nur ein neues Symlink-Ziel und sudo systemctl restart llama-server. Die übrige Unit-Datei und der vorgeschaltete Reverse Proxy werden im vollständigen Leitfaden für einen llama.cpp-Server auf einem VPS behandelt.

Den Tag neben der GGUF-Datei und die Quantisierung dokumentieren

Der Build ist nur zur Hälfte dafür verantwortlich, wie die Ausgabe ausfällt. Die Modelldatei ist die andere Hälfte. GGUF (GGML universal file format) ist der Container, in dem die Gewichte ausgeliefert werden. Dasselbe Modell wird mit vielen Quantisierungsstufen veröffentlicht. Daher können zwei Server mit demselben Tag trotzdem unterschiedliche Ergebnisse liefern, wenn auf dem einen eine Q4_K_M-Datei und auf dem anderen eine Q8_0-Datei liegt. Legen Sie neben dem Modell eine kleine Datei ab, die alle Angaben für eine exakt reproduzierbare Einrichtung enthält:

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>

Ermitteln Sie den Commit mit git rev-parse --short HEAD innerhalb des festgelegten Checkouts. Ermitteln Sie die Prüfsumme mit sha256sum model-q4_k_m.gguf. Vergleichen Sie sie beim Herunterladen zusätzlich mit dem vom Anbieter veröffentlichten Wert. Die Prüfung eines Downloads anhand der veröffentlichten Prüfsumme erkennt eine abgeschnittene Datei, bevor daraus ein schwer nachvollziehbarer Fehler entsteht. Wie stark die Quantisierungsstufe selbst die Antworten verändert, ist eine separate Frage. Welche Kosten die einzelnen Quantisierungsstufen verursachen behandelt dieses Thema.

Wie aktualisieren Sie den Server, ohne ihn zu beschädigen?

Führen Sie das Upgrade als Testlauf durch. Erstellen Sie den neuen Tag neben dem alten, messen Sie beide und behalten Sie den alten, bis der neue sich bewährt hat.

1. Klonen Sie den neuen Tag in ein eigenes Verzeichnis. Verwenden Sie den alten Checkout nicht wieder.
2. Erstellen Sie ihn mit denselben im Manifest dokumentierten cmake-Argumenten.
3. Führen Sie llama-bench für beide Builds mit derselben Modelldatei, derselben Prompt-Länge und derselben Anzahl an Wiederholungen aus.
4. Senden Sie einen Prompt, dessen Antwort Sie genau kennen, an beide Server und lesen Sie die beiden Antworten.
5. Verschieben Sie den Symlink, starten Sie den Dienst neu und lassen Sie das alte Verzeichnis auf dem Datenträger.

/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 gibt eine Zeile pro Test aus. Die Ausgabe enthält eine Spalte backend, eine Spalte ngl und eine Tokens-pro-Sekunde-Spalte mit der Standardabweichung. Vergleichen Sie dieselbe Zeile zwischen den beiden Builds. Vergleichen Sie nicht die Prompt-Zeile des einen Builds mit der Generierungszeile des anderen. Ein Wert, der bei einer anderen Prompt-Länge ermittelt wurde, ist eine andere Messung. Deshalb ist die Tokens-pro-Sekunde-Messung jedes Mal auf dieselbe Weise durchzuführen wichtiger als der Wert selbst.

Ein Rollback besteht aus zwei Befehlen. Es funktioniert nur, weil das alte Verzeichnis noch vorhanden ist:

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

Behalten Sie mindestens den vorherigen Build. Er benötigt nur einen Bruchteil des Speicherplatzes, den die daneben liegende Modelldatei bereits verwendet.

Was bei Upgrades von llama.cpp nicht mehr funktioniert

Eine Modelldatei lässt sich nicht mehr laden. Das ist meist der eigentliche Grund für ein Upgrade: Ein neu veröffentlichtes Modell verwendet eine Architektur, die der festgelegte Build nicht kennt. Deshalb wird es nicht geladen. llama-server wird während des Starts beendet, und im Log steht eine Zeile mit failed to load model from /srv/models/model-q4_k_m.gguf. Lesen Sie die Zeilen direkt davor. Sie zeigen, wie weit der Loader gekommen ist. GGUF enthält außerdem eine Formatversion im Header. Der aktuelle Wert der Spezifikation ist 3. Version 2 hat die Längenfelder von 32 auf 64 Bit erweitert. In der Praxis führt ein unbekannter Architekturname jedoch schon lange vor der Formatversion zum Abbruch. Die Lösung ist ein neuerer Tag, der ausgewählt und dokumentiert wird.

Ein Server-Flag wird umbenannt oder als veraltet markiert. Ein nicht erkanntes Flag beendet llama-server beim Start, anstatt ignoriert zu werden. Unter systemd wirkt das wie ein Dienst, der in einer Schleife startet und wieder beendet wird. journalctl -u llama-server -n 50 zeigt die tatsächliche Meldung. Mit Stand vom 19. August 2026 kennzeichnet die Serverdokumentation --mlock und --mmap als veraltet und empfiehlt stattdessen -lm, --load-mode. Dieses Flag akzeptiert beispielsweise die Werte auto, mmap, mlock und dio. Das GPU-Offload-Flag ist als -ngl, --gpu-layers dokumentiert, während ältere Anleitungen --n-gpu-layers verwenden. Führen Sie vor dem Verschieben des Symlinks /opt/llama.cpp/<new tag>/bin/llama-server --help aus. Prüfen Sie damit jedes Flag in Ihrer Unit-Datei.

Eine Build-Option wird umbenannt. Die CMake-Optionen wechselten vom Präfix LLAMA_ zum Präfix GGML_. Das Root-CMakeLists.txt enthält weiterhin die Zuordnung. LLAMA_CUBLAS ist jetzt ein schwerwiegender Fehler und nennt GGML_CUDA als Ersatz. LLAMA_CUDA und LLAMA_METAL erzeugen dagegen eine Warnung und werden automatisch für Sie übersetzt. Wenn ein Build-Skript beim Konfigurationsschritt abbricht, ist das ein gutes Ergebnis. Schwerwiegender ist ein unbemerkter Fehler: Wenn -DGGML_CUDA=ON versehentlich fehlt, ist der Build erfolgreich, der Server startet und alles läuft auf der CPU. llama-bench zeigt das sofort an, weil die Spalte backend den Wert CPU enthält.

Der Accelerator-Build ist nicht portabel. Mit Stand vom 19. August 2026 sind die Linux-Assets eines Build-Tags die Varianten für CPU, Vulkan, SYCL und OpenVINO, jeweils für x64, arm64 und s390x. In dieser Liste gibt es kein CUDA-Archiv für Linux. Auf einem NVIDIA-Server müssen Sie daher aus dem Quellcode bauen oder ein Container-Image verwenden. Die Windows-CUDA-Archive werden pro Toolkit-Version veröffentlicht. Das ist ein nützlicher Hinweis: Die Toolkit-Version gehört zu den Merkmalen, die Ihre Binärdatei identifizieren. Dokumentieren Sie sie daher zusammen mit den cmake-Argumenten.

Stattdessen das Container-Image pinnen

Die gleiche Regel gilt für einen anderen Namen. Die veröffentlichten Images (ghcr.io/ggml-org/llama.cpp:server und die Varianten für Beschleuniger) verwenden veränderliche Bezeichnungen. Wenn Sie :server im nächsten Monat abrufen, erhalten Sie unter derselben Bezeichnung ein anderes Programm. Rufen Sie das Image einmal ab und lesen Sie den Digest aus:

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

docker pull gibt eine Zeile mit Digest: sha256:... aus. Tragen Sie diesen Digest in der Compose-Datei anstelle des Tags ein. Dadurch kann sich das Image beim nächsten Ausführen von docker compose pull nicht unbemerkt ändern. Bewahren Sie den vorherigen Digest in einem Kommentar auf. So ist ein Rollback mit einer einzigen Änderung möglich, ebenso wie bei der Upgrade- und Rollback-Routine für einen Compose-Stack, die jeden anderen Dienst gleich behandelt.

Der Zweck einer festen Version

Mit einer festen Version können Sie genau angeben, was ausgeführt wird. Verschlechtert eine Änderung das Verhalten, können Sie innerhalb einer Minute den vorherigen Build wiederherstellen. llama.cpp verlangt dafür die Nachverfolgung von zwei Angaben: des Build-Tags und der Modelldatei. Diese werden getrennt übergeben. Laufzeitumgebungen, die beides bündeln, verhalten sich anders. Der Vergleich von Ollama und llama.cpp als Server beschreibt diesen Zielkonflikt: Eine Versionsnummer für das gesamte Paket muss seltener erfasst und weniger separat kontrolliert werden.

FAQ

Sollte ich den bNNNN-Build-Tag oder den v0.x-Tag festlegen?

Beides funktioniert, solange Sie überhaupt einen Tag festlegen. Build-Tags wie b10502 bilden den langfristig gepflegten Zweig: Jedes vorgefertigte Release-Archiv trägt einen solchen Namen, und in den meisten Fehlerberichten wird einer genannt. Daher lässt sich eine Build-Nummer am einfachsten mit der eines anderen Betreibers vergleichen. Version-Tags wie v0.1.2 bilden eine kürzere Liste bewusst gesetzter Versionspunkte. Das eignet sich für einen Server, den Sie nur einige Male im Jahr ändern. Wichtiger als die Auswahl ist, dass die Tag-Zeichenfolge neben der Modelldatei dokumentiert ist und ein Upgrade eine bewusste Entscheidung bleibt, statt durch git pull ausgelöst zu werden.

Verwendet llama.cpp inzwischen Semantic Versioning?

Noch nicht, wie das Projekt selbst angibt. Die v0.1.2-Release-Notes erklären, dass Semantic Versioning noch in Arbeit ist, und verweisen auf eine ggml-Diskussion, in der das Schema einschließlich Release-Zyklus und Definition eines Patch-Releases ausgearbeitet wird. Betrachten Sie einen Version-Tag als einen von den Maintainers markierten Versionspunkt. Gehen Sie nicht davon aus, dass eine Änderung der letzten Ziffer ein kompatibles Upgrade garantiert. Testen Sie den neuen Tag vor dem Wechsel mit Ihrer eigenen Modelldatei.

Wie stelle ich fest, welcher llama.cpp-Build auf meinem Server läuft?

llama-server --version gibt die Versions- und Build-Informationen aus. Auch das Startprotokoll beginnt mit einer build-Zeile, die die Build-Nummer, den Commit-Hash und den verwendeten Compiler enthält. Mit journalctl -u llama-server finden Sie diese Zeile bei einem laufenden Dienst. Bei einer Installation aus dem Quellcode gibt git describe --tags innerhalb des festgelegten Checkouts den Tag aus. readlink /opt/llama.cpp/current zeigt, auf welches Verzeichnis der Dienst tatsächlich verweist.

Warum wird mein Modell nach einem Upgrade von llama.cpp nicht mehr geladen?

Ein Ladefehler direkt nach einem Upgrade bedeutet, dass Build und GGUF-Datei nicht zusammenpassen. Das Protokoll endet mit einer failed to load model from-Zeile, die den Pfad nennt. Die darüberstehenden Zeilen zeigen, wie weit der Loader gelesen hat. Bei einem Wechsel auf eine neuere Version benötigt eine sehr neue Modelldatei einen Build, der ihre Architektur unterstützt. Bei einem Rollback kann ein Build unterhalb des Tags, für den die Datei erstellt wurde, eine Datei beschädigen, die am Vortag noch funktioniert hat. Verweisen Sie den Symlink auf den vorherigen Build, starten Sie den Dienst neu und prüfen Sie, welcher Build korrekt mit welcher Datei zusammenarbeitet. Entscheiden Sie danach, welchen der beiden Werte Sie ändern.

Gibt es vorgefertigte Linux-Binaries, die ich festlegen kann, statt selbst zu kompilieren?

Ja, für einige Setups. Zu jedem Build-Tag gehören Release-Archive mit diesem Namen, beispielsweise llama-b10502-bin-ubuntu-x64.tar.gz. Am 19 August 2026 gab es daneben Varianten für arm64, s390x, Vulkan, SYCL und OpenVINO. Die Benennung vereinfacht das Festlegen einer Version, weil der Tag im Dateinamen enthalten ist. In dieser Liste gab es kein CUDA-Archiv für Linux. Auf einem NVIDIA-Server müssen Sie daher weiterhin mit -DGGML_CUDA=ON aus dem Quellcode bauen oder eines der CUDA-Container-Images verwenden.