Llama.cpp Python: Installation, GPU-Build und Parameter

llama-cpp-python ist die Python-Bindung für llama.cpp. Sie lädt GGUF-Modelle im gleichen Prozess, stellt einen Low-Level-ctypes-Wrapper plus ein High-Level- Llama -Klasse bereit und enthält einen OpenAI-kompatiblen HTTP-Server. Die Standard-pip-Installation kompiliert eine CPU-only-Version. Um die GPU zu nutzen, installieren Sie entweder ein GPU-wheel oder erstellen Sie die Bibliothek neu aus dem Quellcode mit CMAKE_ARGS, und übergeben Sie dann n_gpu_layers.

Warum die Standardinstallation CPU-only ist

Das Paket ist eine dünne Bindung um eine C++-Bibliothek, die mit Backend-Unterstützung zur Build-Zeit kompiliert werden muss. Es gibt kein Laufzeit-Flag, das CUDA nachträglich aktiviert. Wenn pip das sdist ohne CMAKE_ARGS erstellt, konfiguriert CMake das generische CPU-Backend und das ist alles, was du bekommst – dauerhaft, bis du neu buildest. Auf macOS arm64 ist das weniger problematisch, da neuere Versionen das Metal-Backend standardmäßig aktivieren, aber auf Linux und Windows führt eine bloße Installation vollständig auf deiner CPU aus.

Zwei Konsequenzen sind wichtig zu verstehen: Erstens, n_gpu_layers=-1 bei einem CPU-Only-Build funktioniert stillschweigend nicht richtig, deshalb schließen viele Menschen, ihre GPU sei „zu langsam“, obwohl sie gar nicht benutzt wurde. Zweitens speichert pip erstellte Wheels. Das Neuinstallieren mit verschiedenen CMAKE_ARGS kann dir das zwischengespeicherte CPU-Wheel erneut liefern, deshalb beinhalten alle Rebuild-Befehle unten --no-cache-dir --force-reinstall.

So installieren Sie llama-cpp-python mit GPU-Unterstützung

Option 1: vorgefertigte Wheels (kein Compiler nötig)

Das Projekt veröffentlicht Wheel-Indizes, einschließlich eines CPU-Index unter https://abetlen.github.io/llama-cpp-python/whl/cpu und CUDA-Varianten, deren Pfadsegment die CUDA-Version kodiert, zum Beispiel .../whl/cu124. Installiere mit:

pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124

Welche CUDA-Tags und Python-Versionen veröffentlicht werden, ändert sich von Release zu Release, und die Indizes hinken manchmal der neuesten PyPI-Version hinterher. Überprüfe die Projekt-README auf die Tags, die derzeit existieren, statt einen anzunehmen – ein falscher Tag gibt einen 404 zurück und pip fällt stillschweigend auf das Bauen aus dem Quelltext zurück.

Option 2: aus dem Quelltext bauen (Linux, CUDA)

Du benötigst eine C++-Toolchain, CMake und das CUDA Toolkit mit nvcc in deinem PATH.

nvcc --version   # muss eine Version ausgeben, nicht "command not found"

CMAKE_ARGS="-DGGML_CUDA=on" 
  pip install llama-cpp-python --no-cache-dir --force-reinstall --upgrade

Der Flag-Name hat sich im Laufe des Projekts geändert: sehr alte Anleitungen verwenden -DLLAMA_CUBLAS=on, Mitte-2024-Anleitungen verwenden -DLLAMA_CUDA=on, und das aktuelle Upstream verwendet das GGML_ Präfix. Wenn ein Build bei einer unbekannten CMake-Option fehlschlägt, ist diese Nichtübereinstimmung normalerweise der Grund. Andere Backends folgen dem gleichen Muster – Vulkan ist -DGGML_VULKAN=on, SYCL ist -DGGML_SYCL=on, und die AMD/ROCm-Option wurde mehr als einmal umbenannt, also lies die README für deine installierte Version, statt ein Flag aus einem Forumsbeitrag zu kopieren.

Du kannst die Kompilierungszeit erheblich verkürzen, indem du nur für die Compute-Fähigkeit deiner GPU buildest, zum Beispiel -DCMAKE_CUDA_ARCHITECTURES=89 für eine Ada-Karte wie die RTX 4090, oder 86 für eine 3090. Schau die Compute-Fähigkeit deiner Karte in NVIDIAs offiziellem Verzeichnis nach; wenn du noch Hardware wählst, deckt unser Leitfaden für die besten GPUs zum lokalen Ausführen von LLMs die VRAM-pro-Dollar-Abwägungen ab.

Option 3: macOS mit Metal

xcode-select --install

CMAKE_ARGS="-DGGML_METAL=on" 
  pip install llama-cpp-python --no-cache-dir --force-reinstall

Auf Apple Silicon, stelle sicher, dass du keinen Rosetta x86 Python ausführst: python -c "import platform; print(platform.machine())" muss ausgeben arm64. Ein x86_64-Interpreter erzeugt einen Build ohne Metal-Backend, egal welche CMAKE_ARGS du übergibst. Da GPU und CPU Speicher auf Apple Silicon teilen, ist n_gpu_layers=-1 fast immer die richtige Einstellung dort.

Option 4: Windows mit CUDA

Installieren Sie Visual Studio Build Tools 2022 mit der Workload „Desktop development with C++" erstes, dann das CUDA Toolkit, damit CUDA seine MSBuild-Integration in ein bestehendes Visual Studio installiert. Dann in PowerShell:

$env:CMAKE_ARGS = "-DGGML_CUDA=on"
pip install llama-cpp-python --no-cache-dir --force-reinstall --upgrade

In cmd.exe ist das Äquivalent set CMAKE_ARGS=-DGGML_CUDA=on auf einer eigenen Zeile. Windows-Quelltext-Builds sind der fehleranfälligste Weg der drei Plattformen; wenn du nur Inferenz willst und keinen benutzerdefinierten Build, sind die vorgefertigten CUDA-Wheels oder WSL2 beide weniger schmerzhaft.

Wie Sie erkennen, welche Build-Variante Sie verwenden

Die zuverlässigste Überprüfung ist die ausführliche Loader-Ausgabe, die versionsunabhängig ist:

from llama_cpp import Llama
llm = Llama(model_path="./models/model.gguf", n_gpu_layers=-1, verbose=True)

Bei einem CUDA-Build wirst du Backend-Initialisierungszeilen sehen, die CUDA und einen Gerätenamen erwähnen, plus eine Tensor-Lade-Zeile, die meldet, wie viele der Modell-Layer auf die GPU ausgelagert wurden. Auf Metal wirst du stattdessen Metal-Gerätzeilen sehen. Ein CPU-Only-Build gibt weder das eine noch das andere aus und meldet null ausgelagerte Layer. Kreuzkontrolle mit nvidia-smi während der Generierung: Wenn dein Python-Prozess keinen VRAM hält, läuft nichts auf der GPU.

Neuere Versionen stellen auch eine direkte Capability-Prüfung bereit:

from llama_cpp import llama_cpp, __version__
print(__version__)
print(llama_cpp.llama_supports_gpu_offload())

Falls dieses Attribut einen AttributeErrorauslöst, stammt dein Build von davor — verwende die Verbose-Log-Methode.

Laden einer GGUF-Datei und Ausführen einer ersten Textgenerierung

Punkt model_path bei einer beliebigen GGUF-Datei. Wenn du lieber von Hugging Face ziehen möchtest, Llama.from_pretrained(repo_id=..., filename="*Q4_K_M.gguf", ...) führt den Download für dich durch, wenn huggingface-hub installiert ist.

from llama_cpp import Llama

llm = Llama(
    model_path="./models/qwen2.5-7b-instruct-q4_k_m.gguf",
    n_gpu_layers=-1,
    n_ctx=4096,
    n_batch=512,
    verbose=False,
)

out = llm.create_chat_completion(
    messages=[{"role": "user", "content": "Explain a KV cache in two sentences."}],
    max_tokens=256,
    temperature=0.7,
)
print(out["choices"][0]["message"]["content"])

Für reine Textfortsetzung rufe das Objekt direkt auf: llm("Q: What is a GGUF file? A:", max_tokens=128, stop=["Q:"]) und lesen out["choices"][0]["text"].

Token streamen

Übergebe stream=True und iteriere. Die Antwortstruktur entspricht dem OpenAI-Streaming-Format, daher trägt der erste Chunk normalerweise nur die Rolle und spätere Chunks tragen content Deltas:

stream = llm.create_chat_completion(
    messages=[{"role": "user", "content": "Write a haiku about GGUF files."}],
    stream=True,
)
for chunk in stream:
    delta = chunk["choices"][0]["delta"]
    if "content" in delta:
        print(delta["content"], end="", flush=True)

Die meisten GGUF-Dateien enthalten eine Chat-Vorlage, die llama-cpp-python automatisch anwendet. Wenn die Ausgabe verzerrt aussieht oder das Modell nie stoppt, ist die Vorlage der erste Verdächtige — überschreibe sie mit dem chat_format Argument. Durchsuche quantisierte Optionen und ihre Größen in unserem Datenbank für KI-Modelle.

Die Parameter, die zählen

Parameter	Was es tut	Praktische Anleitung
n_gpu_layers	Wie viele Transformer-Schichten auf die GPU ausgelagert werden. Standardmäßig 0, d. h. nur CPU. -1 bedeutet alle.	Beginne bei -1. Wenn du einen Out-of-Memory-Fehler beim Laden erhältst, reduziere es schrittweise, bis es passt.
n_ctx	Kontextfenster in Tokens. Der Standard ist bewusst klein gesetzt (512 in aktuellen Versionen). Wenn du 0 übergibst, verwendet llama.cpp den Wert aus den eigenen Metadaten des Modells.	Setze es explizit. 0 ist zulässig, aber ein Modell, das für einen 128K-Kontext trainiert wurde, wird versuchen, einen KV-Cache für 128K Tokens zuzuweisen, was normalerweise dein VRAM zum Explodieren bringt.
n_batch	Logische Batch-Größe für die Prompt-Verarbeitung (Prefill), nicht für die Generierung.	512 ist der häufige Standard. Eine Erhöhung auf 1024–2048 beschleunigt lange Prompts auf der GPU auf Kosten von mehr Speicher; senke sie, wenn du Puffer-Allokationsfehler siehst.
n_ubatch	Physische Micro-Batch, die tatsächlich zum Backend eingereicht wird.	Lass es in Ruhe, es sei denn, du bist speicherbegrenzt — dann reduziert ein kleinerer Wert die maximale Compute-Puffergröße.
n_threads	Threads für die Generierung. n_threads_batch deckt die Prompt-Verarbeitung ab.	Ist nur relevant für Arbeiten, die noch auf der CPU laufen. Setze es auf physische Kerne, nicht auf logische (Hyperthreaded-) Kerne.
offload_kqv	Ob der KV-Cache auf der GPU lebt.	Standardmäßig aktiviert und normalerweise das, was du haben möchtest; eine Deaktivierung spart VRAM, kostet aber viel Geschwindigkeit.
use_mmap / use_mlock	Memory-Map die Datei; sperren sie im RAM.	Halte mmap aktiviert. Verwende mlock nur, wenn das Betriebssystem Modellgewichte auslagert.
chat_format	Überschreibt die eingebettete Chat-Vorlage.	Setze es, wenn die integrierte Vorlage des Modells fehlt oder falsch ist.

Beachte, dass Flash Attention und KV-Cache-Quantisierung (type_k / type_v) sich zwischen Versionen verschoben haben — der Flash-Attention-Schalter war in einigen Versionen ein Boolean und in anderen eine Drei-Wege-Einstellung auto/on/off. Führe aus help(Llama) gegen Ihre installierte Version, anstatt einem Flag-Namen aus einem Blog-Post zu vertrauen.

Tuning in der Praxis

Die zwei Einstellungen, die interagieren, sind n_gpu_layers und n_ctx. Gewichte und KV-Cache konkurrieren um denselben VRAM, und der KV-Cache skaliert ungefähr linear mit der Kontextlänge. Das Halbieren n_ctx von 8192 auf 4096 gibt oft genug Speicher frei, um mehrere Layer mehr auszulagern, was normalerweise der bessere Kompromiss ist. Berechnen Sie das Budget, bevor Sie mit unserem VRAM-Rechneranfangen zu raten, oder überprüfen Sie modellspezifische Werte in der VRAM-Anforderungen-Referenz.

Partielles Auslagern funktioniert – es ist llama.cpp's Kernfeature – aber erwarten Sie einen steilen Leistungsabfall, sobald ein Layer auf der CPU bleibt, da jedes Token den PCIe-Bus überqueren muss. Falls Sie alle Layer passen, nutzen Sie das aus.

OpenAI-kompatibler Servermodus

pip install "llama-cpp-python[server]"

python -m llama_cpp.server 
  --model ./models/qwen2.5-7b-instruct-q4_k_m.gguf 
  --n_gpu_layers -1 
  --n_ctx 4096 
  --host 0.0.0.0 --port 8000

Server-Flags spiegeln die Constructor-Argumente, Unterstriche inklusive. Sie erhalten /v1/chat/completions, /v1/completions, /v1/modelsund interaktive Dokumentation unter /docs. Jeder OpenAI-Client funktioniert, und Streaming wird über SSE unterstützt:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
for event in client.chat.completions.create(
    model="gpt-3.5-turbo",  # ignored unless you set model aliases
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
):
    print(event.choices[0].delta.content or "", end="", flush=True)

Für mehr als ein Modell übergeben Sie --config_file config.json mit einem Modelle Array, wobei jeder Eintrag einen Modell Pfad, einen model_alias erhält, den Clients anfordern können, und sein eigenes n_gpu_layers / n_ctx. Fügen Sie --api_key hinzu, falls der Port über localhost hinaus erreichbar ist. Abwägung gegenüber einem gehosteten Endpoint? Der Selbsthosting- versus-API-Kosten-Grenzwert-Rechner zeigt die Zahlen auf.

Häufige Build-Fehler und deren Behebung

Symptom	Ursache	Lösung
Installation erfolgreich, aber keine GPU-Zeilen in ausführlicher Ausgabe	pip hat ein gecachtes CPU-Wheel wiederverwendet	Neuinstallation mit --no-cache-dir --force-reinstall
Wheel-Erstellung fehlgeschlagen, CMake nicht gefunden	Keine Build-Toolchain	Linux: build-essential plus CMake. macOS: xcode-select --install. Windows: VS Build Tools C++-Arbeitsauslastung
nvcc nicht gefunden während der Konfiguration	Treiber vorhanden, Toolkit fehlt	Installieren Sie das CUDA Toolkit. Die CUDA-Version in nvidia-smi ist das Maximum des Treibers, kein installiertes Toolkit
„unsupported GNU version“ von nvcc	System-gcc ist neuer als von Ihrer CUDA-Version unterstützt	Weisen Sie CUDA einen älteren Compiler mit -DCMAKE_CUDA_HOST_COMPILER=/usr/bin/gcc-12
Maschine friert ein oder meldet OOM während der Kompilierung	Zu viele parallele Kompilierungsaufgaben	Legen Sie CMAKE_BUILD_PARALLEL_LEVEL=4 vor der pip-Installation fest
„unknown model architecture“ beim Laden	GGUF-Format neuer als Ihre llama.cpp-Version	Aktualisieren Sie llama-cpp-python; dazu ist ein Neubau erforderlich, nicht nur eine Konfigurationsänderung
CUDA-Out-of-Memory beim Laden	Gewichte plus KV-Cache überschreiten den verfügbaren VRAM	Niedriger n_ctx zuerst, dann n_gpu_layers
Fehler bei der Zuweisung von Berechnungspuffern	n_batch zu groß für den verfügbaren Arbeitsspeicher	Reduzieren n_batch (und n_ubatch)

Häufig gestellte Fragen

Ist llama-cpp-python dasselbe wie llama.cpp?

Nein. llama.cpp ist die C/C++-Inferenz-Engine; llama-cpp-python integriert einen bestimmten Commit davon und stellt eine Python-Bindung bereit. Da die integrierte Version pro Release festgelegt ist, können die Bindungen gegenüber dem Hauptentwicklungszweig (upstream) um Tage oder Wochen zurückbleiben – was insbesondere dann relevant ist, wenn gerade eine brandneue Modellarchitektur in llama.cpp eingeführt wurde, aber noch nicht in einer veröffentlichten Bindung enthalten ist.

Wie stelle ich sicher, dass die GPU tatsächlich genutzt wird?

Laden Sie mit verbose=True und achten Sie auf Initialisierungszeilen der Backend-Komponenten sowie auf eine Meldung darüber, welche Layer auf die GPU ausgelagert wurden. Beobachten Sie anschließend nvidia-smi (bzw. die GPU-Auslastung im Aktivitätsmonitor unter macOS) während einer Generierung. Steigt die VRAM-Auslastung nicht an und liegen die Tokens pro Sekunde im Bereich typischer CPU-Werte, handelt es sich um eine rein CPU-basierte Build-Version.

Kann ich das Kompilieren vollständig vermeiden?

Häufig ja – verwenden Sie die vorkompilierten Wheel-Indizes des Projekts mit --extra-index-url, wobei Sie den CUDA-Tag an Ihr Toolkit anpassen müssen. Falls kein passendes Wheel für Ihre Python-Version und Plattform verfügbar ist, greift pip automatisch auf einen Quellcode-Build zurück, der bei aktivierter CUDA-Unterstützung typischerweise mehrere Minuten dauert.

Should I use llama-cpp-python, Ollama, or LM Studio?

Verwenden Sie llama-cpp-python, wenn Sie das Modell direkt in Ihrem eigenen Python-Prozess ausführen möchten und dabei direkte Kontrolle über Sampling, Logits und Grammatiken benötigen. Wählen Sie stattdessen Ollama für einen verwalteten Daemon mit Modell-Downloads und automatischer Speicherverwaltung oder LM Studio für eine grafische Benutzeroberfläche. Alle drei Lösungen basieren auf llama.cpp, sodass die Modellqualität vergleichbar ist; der Unterschied liegt lediglich in der Bedienfreundlichkeit.

Kann ich ein Modell ausführen, das größer ist als mein VRAM?

Ja. Legen Sie n_gpu_layers auf einen Wert unterhalb der Anzahl der Modell-Layer fest, sodass der Rest auf der CPU unter Verwendung des Systemspeichers läuft. Dies funktioniert zuverlässig, allerdings führt bereits ein nennenswerter Anteil an CPU-basierten Layern zu einem starken Geschwindigkeitseinbuße – daher ist ein kleineres Modell mit höherer Quantisierung meist schneller als ein großes Modell, das nur zur Hälfte auf die GPU ausgelagert wird.

Funktioniert die GPU-Unterstützung unter Windows auch ohne WSL?

Ja. Installieren Sie entweder ein vorkompiliertes CUDA-Wheel oder kompilieren Sie aus dem Quellcode mit installierten Visual Studio Build Tools 2022 („Desktopentwicklung mit C++“), bevor Sie das CUDA Toolkit installieren, und setzen Sie in PowerShell $env:CMAKE_ARGS . WSL2 bleibt jedoch der reibungslosere Weg, falls Sie damit vertraut sind, da die Linux-Build-Anleitungen besser dokumentiert und erprobt sind.