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

llama-cpp-python ist die Python-Bindung für llama.cpp. Sie lädt GGUF-Modelle direkt im Prozess, stellt sowohl eine Low-Level-ctypes-Schnittstelle als auch eine 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 an eine C++-Bibliothek, die zum Zeitpunkt des Builds mit Backend-Unterstützung kompiliert werden muss. Es gibt keine Laufzeitoption, um CUDA nachträglich zu aktivieren. Wenn pip das Source-Distribution-Archiv (sdist) ohne gesetzte Umgebungsvariable erstellt, konfiguriert CMake standardmäßig das generische CPU-Backend – und genau das erhalten Sie dauerhaft, bis Sie das Paket neu bauen. Auf macOS arm64 stellt dies weniger ein Problem dar, da neuere Versionen standardmäßig das Metal-Backend aktivieren; unter Linux und Windows führt eine einfache Installation jedoch ausschließlich auf der CPU statt. CMAKE_ARGS Zwei Folgen, die man sich bewusst machen sollte: Erstens

führt n_gpu_layers=-1 bei einem reinen CPU-Build stillschweigend nichts Nützliches aus, weshalb Nutzer oft fälschlicherweise schlussfolgern, ihre GPU sei ‚zu langsam‘, obwohl sie gar nicht angesprochen wurde. Zweitens speichert pip kompilierte Wheel-Pakete im Cache. Ein erneuter Aufruf von install mit anderen CMAKE_ARGS Umgebungsvariablen kann Ihnen erneut das zwischengespeicherte CPU-Wheel liefern – daher enthält jeder unten angegebene Neubefehl die Optionen --no-cache-dir --force-reinstall.

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

Option 1: Vorkompilierte Wheel-Pakete (kein Compiler erforderlich)

Das Projekt veröffentlicht Wheel-Indizes, darunter einen CPU-Index unter https://abetlen.github.io/llama-cpp-python/whl/cpu sowie CUDA-Varianten, deren Pfadsegment die CUDA-Version kodiert, z. B. .../whl/cu124. Installation mittels:

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 sind manchmal nicht sofort auf dem neuesten Stand der PyPI-Version. Prüfen Sie daher stets das Projekt-README auf die aktuell verfügbaren Tags, statt vorschnell davon auszugehen – ein falsches Tag führt zu einem HTTP-404-Fehler, und pip wechselt stillschweigend zurück zum Quellcode-Build.

Option 2: Build aus dem Quellcode (Linux, CUDA)

Sie benötigen eine C++-Toolchain, CMake sowie das CUDA-Toolkit mit nvcc im Systempfad (PATH).

nvcc --version   # muss eine Versionsnummer ausgeben, nicht "Befehl nicht gefunden"

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

Der Name der CMake-Flagge hat sich im Laufe der Projektentwicklung geändert: Sehr alte Anleitungen verwenden -DLLAMA_CUBLAS=on, Anleitungen aus Mitte 2024 verwenden -DLLAMA_CUDA=on, während die aktuelle Hauptentwicklung (upstream) das Präfix GGML_ verwendet. Wenn ein Build mit einer unbekannten CMake-Option fehlschlägt, liegt dies meist an dieser Inkonsistenz. Andere Backends folgen demselben Muster – Vulkan wird aktiviert mit -DGGML_VULKAN=on, SYCL mit -DGGML_SYCL=on, und die AMD/ROCm-Option wurde bereits mehrfach umbenannt; lesen Sie daher stets das README Ihrer installierten Version, statt eine Flagge aus einem Forenbeitrag zu kopieren.

Sie können die Kompilierzeit deutlich verkürzen, indem Sie ausschließlich für die Compute-Kapazität Ihrer GPU bauen, z. B. -DCMAKE_CUDA_ARCHITECTURES=89 für eine Ada-basierte Karte wie die RTX 4090 oder 86 für eine RTX 3090. Die Compute-Kapazität Ihrer Grafikkarte finden Sie in der offiziellen Liste von NVIDIA; falls Sie noch Hardware auswählen, behandelt unser Leitfaden zu den besten GPUs für lokales LLM-Hosting die Kosten-Nutzen-Relation zwischen VRAM und Preis.

Option 3: macOS mit Metal

xcode-select --install

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

Überprüfen Sie auf Apple Silicon, ob Sie nicht versehentlich eine Rosetta-basierte x86-Python-Installation nutzen: python -c "import platform; print(platform.machine())" muss arm64ausgeben. Ein x86_64-Interpreter erzeugt unabhängig von den übergebenen CMAKE_ARGS keinen Build mit Metal-Backend. Da GPU und CPU auf Apple Silicon denselben Arbeitsspeicher teilen, ist n_gpu_layers=-1 n_gpu_layers=-1

auf diesem System nahezu immer die richtige Einstellung.

Option 4: Windows mit CUDA erstesInstallieren Sie zunächst die Visual Studio Build Tools 2022 mit der Workload ‚Desktopentwicklung mit C++‘

und danach das CUDA-Toolkit, damit CUDA seine MSBuild-Integration in die vorhandene Visual Studio-Installation einbinden kann. Führen Sie dann in PowerShell folgenden Befehl aus:

In $env:CMAKE_ARGS = "-DGGML_CUDA=on" pip install llama-cpp-python --no-cache-dir --force-reinstall --upgrade In cmd.exe lautet die entsprechende Anweisung set CMAKE_ARGS=-DGGML_CUDA=on in einer separaten Zeile. Windows-Quellcode-Builds sind der fehleranfälligste Weg unter den drei Plattformen; wenn Sie lediglich Inferenz benötigen und keinen benutzerdefinierten Build, sind vorkompilierte CUDA-Wheels oder WSL2 deutlich weniger problematisch.

Wie Sie erkennen, welche Build-Variante Sie verwenden

Die zuverlässigste Überprüfungsmethode ist die ausführliche Ausgabe des Modell-Loaders – diese ist versionsunabhängig:

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

Bei einem CUDA-Build sehen Sie Initialisierungszeilen des Backends mit Hinweisen auf CUDA und einen Gerätenamen sowie eine Zeile zum Laden der Tensoren, die angibt, wie viele Schichten des Modells auf die GPU ausgelagert wurden. Bei Metal erscheinen stattdessen Zeilen mit Metal-Geräteinformationen. Ein rein CPU-basierter Build zeigt weder das eine noch das andere an und meldet null ausgelagerte Schichten. Ergänzen Sie diese Prüfung durch nvidia-smi während der Generierung: Wenn Ihr Python-Prozess keinen VRAM belegt, läuft nichts auf der GPU.

Neuere Versionen bieten zudem eine direkte Funktionsprüfung an:

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

Wenn dieses Attribut eine AttributeErrorauslöst, stammt Ihr Build aus einer älteren Zeit – verwenden Sie stattdessen die Methode mit ausführlicher Protokollierung.

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

Punkt model_path auf jede GGUF-Datei. Falls Sie lieber von Hugging Face herunterladen möchten, Llama.from_pretrained(repo_id=..., filename="*Q4_K_M.gguf", ...) führt den Download automatisch durch, sobald 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": "Erklären Sie einen KV-Cache in zwei Sätzen."}],
    max_tokens=256,
    temperature=0.7,
)
print(out["choices"][0]["message"]["content"])

Für reine Textfortsetzung rufen Sie das Objekt direkt auf: llm("F: Was ist eine GGUF-Datei? A:", max_tokens=128, stop=["F:"]) und lesen out["choices"][0]["text"].

Token-Streaming

Übergeben Sie stream=True und durchlaufen Sie die Ergebnisse. Das Antwortformat entspricht dem OpenAI-Streaming-Format; typischerweise enthält der erste Chunk lediglich die Rolle, während spätere Chunks content -Deltas enthalten:

stream = llm.create_chat_completion(
    messages=[{"role": "user", "content": "Schreiben Sie ein Haiku über GGUF-Dateien."}],
    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 fehlerhaft erscheint oder das Modell niemals stoppt, ist die Vorlage der erste Verdächtige – überschreiben Sie sie mit dem Argument chat_format . Durchsuchen Sie quantisierte Optionen und deren Größen in unserer Datenbank für KI-Modelle.

Die entscheidenden Parameter

Beachten Sie, dass Flash Attention und KV-Cache-Quantisierung (type_k / type_v) haben sich zwischen den Versionen geändert – die Flash-Attention-Einstellung war in einigen Versionen ein einfacher Boolescher Wert, in anderen hingegen eine dreistufige Einstellung (auto/on/off). Führen Sie help(Llama) mit Ihrer installierten Version aus, anstatt sich auf einen Flag-Namen aus einem Blogbeitrag zu verlassen.

Feinabstimmung in der Praxis

Die beiden interagierenden Einstellungen sind n_gpu_layers und n_ctx. Gewichte und KV-Cache konkurrieren um denselben VRAM, wobei der KV-Cache annähernd linear mit der Kontextlänge skaliert. Die Halbierung von n_ctx von 8192 auf 4096 befreit oft genug Speicher, um mehrere weitere Layer auf die GPU auszulagern – dies ist in der Regel die bessere Kompromisslösung. Berechnen Sie vorab Ihr VRAM-Budget, bevor Sie mit unseren VRAM-Rechner, oder prüfen Sie modellspezifische Werte in der Referenz zu VRAM-Anforderungen.

Teilweise Auslagerung funktioniert – sie ist das Markenzeichen von llama.cpp – doch rechnen Sie mit einem starken Leistungseinbruch, sobald auch nur ein Layer auf der CPU verbleibt, da jedes Token die PCIe-Schnittstelle überqueren muss. Falls alle Layer in den VRAM passen, belassen Sie sie dort.

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

Die Server-Flags spiegeln die Konstruktorargumente wider, inklusive Unterstrichen. Sie erhalten /v1/chat/completions, /v1/completions, /v1/models, sowie interaktive Dokumentation unter /docs. Jeder OpenAI-kompatible Client funktioniert; 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",  # wird ignoriert, es sei denn, Sie definieren Modell-Aliase
    messages=[{"role": "user", "content": "Hallo"}],
    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 ein Modell path model_alias enthält, unter dem Clients das Modell namentlich anfordern können, sowie eigene n_gpu_layers / n_ctx. Fügen Sie --api_key hinzu, falls der Port außerhalb von localhost erreichbar sein soll. Abwägung gegenüber einem gehosteten Endpoint? Der Rechner für die Break-even-Analyse zwischen Self-Hosting und API-Nutzung veranschaulicht dies anhand konkreter Zahlen.

Häufige Build-Fehler und deren Behebung

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.

Sollte ich llama-cpp-python, Ollama oder 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.