Llama Cpp Python : installation, construction GPU et paramètres

llama-cpp-python est la liaison Python pour llama.cpp. Elle charge Modèles GGUF en processus, expose un wrapper ctypes de bas niveau plus un wrapper Llama Pour utiliser le GPU, installez une version précompilée compatible GPU ou recompilez depuis les sources avec CMAKE_ARGS, puis transmettez n_gpu_layers.

Pourquoi l’installation par défaut ne prend en charge que le CPU

Le paquet est une interface légère autour d'une bibliothèque C++ qui doit être compilée avec le support des backends intégré au moment de la compilation. Aucun drapeau d'exécution n'active CUDA a posteriori. Lorsque pip compile le paquet source (sdist) sans aucune variable définie, CMake configure automatiquement le backend générique pour CPU, et c'est ce backend que vous obtenez définitivement — jusqu'à ce que vous reconstruisiez le paquet. CMAKE_ARGS Sur macOS arm64, ce problème est moins critique, car les versions récentes activent par défaut le backend Metal ; en revanche, sur Linux et Windows, une installation standard s'exécutera entièrement sur votre processeur.

Deux conséquences importantes à retenir : premièrement, n_gpu_layers=-1 sur une compilation CPU uniquement ne fait silencieusement rien d'utile, si bien que les gens concluent souvent que leur GPU est « trop lent » alors qu'il n'a jamais été sollicité. Deuxièmement, pip met en cache les roues compilées. Relancer l'installation avec différentes CMAKE_ARGS peut vous rendre la roue CPU mise en cache à nouveau, c'est pourquoi chaque commande de reconstruction ci-dessous inclut --no-cache-dir --force-reinstall.

Installer llama-cpp-python avec le support GPU

Option 1 : roues précompilées (aucun compilateur nécessaire)

Le projet publie des index de roues, incluant un index CPU à https://abetlen.github.io/llama-cpp-python/whl/cpu et des variantes CUDA dont le segment du chemin encode la version CUDA, par exemple .../whl/cu124. Installez avec :

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

Les tags CUDA et les versions Python publiées changent d'une version à l'autre, et les index traînent parfois derrière la version PyPI la plus récente. Consultez le README du projet pour les tags qui existent actuellement au lieu de supposer un tag — un mauvais tag renvoie une erreur 404 et pip revient silencieusement à la compilation à partir des sources.

Option 2 : compiler à partir des sources (Linux, CUDA)

Vous avez besoin d'une chaîne d'outils C++, CMake et du kit d'outils CUDA avec nvcc sur votre PATH.

nvcc --version   # doit afficher une version, pas « command not found »

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

Le nom du flag a changé au cours de la vie du projet : les très anciens guides utilisent -DLLAMA_CUBLAS=on, les guides de mi-2024 utilisent -DLLAMA_CUDA=on, et l'upstream actuel utilise le préfixe GGML_ . Si une compilation échoue sur une option CMake inconnue, cette différence en est généralement la cause. Les autres backends suivent le même schéma — Vulkan est -DGGML_VULKAN=on, SYCL est -DGGML_SYCL=on, et l'option AMD/ROCm a été renommée plus d'une fois, donc consultez le README de votre version installée au lieu de copier un flag depuis un post de forum.

Vous pouvez réduire considérablement le temps de compilation en compilant uniquement pour la capacité de calcul de votre GPU, par exemple -DCMAKE_CUDA_ARCHITECTURES=89 pour une carte Ada comme la RTX 4090, ou 86 pour une 3090. Cherchez la capacité de calcul de votre carte dans la liste officielle de NVIDIA ; si vous choisissez toujours du matériel, notre guide des meilleurs GPU pour exécuter des LLM localement couvre les compromis VRAM par dollar.

Option 3 : macOS avec Metal

xcode-select --install

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

Sur Apple Silicon, vérifiez que vous n'exécutez pas une version Rosetta x86 de Python : python -c "import platform; print(platform.machine())" doit afficher arm64. Un interpréteur x86_64 produit une compilation sans backend Metal peu importe ce que vous passez à CMAKE_ARGS. Comme le GPU et le CPU partagent la mémoire sur Apple Silicon, n_gpu_layers=-1 est presque toujours le bon paramètre là-bas.

Option 4 : Windows avec CUDA

Installez Visual Studio Build Tools 2022 avec la charge de travail « Développement bureau avec C++ » premier, puis le CUDA Toolkit, afin que CUDA installe son intégration MSBuild dans un Visual Studio existant. Ensuite, dans PowerShell :

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

Dans cmd.exe l'équivalent est set CMAKE_ARGS=-DGGML_CUDA=on sur sa propre ligne. Les compilations source Windows sont le chemin le plus sujet aux défaillances des trois plates-formes ; si vous ne voulez que l'inférence et pas une compilation personnalisée, les roues CUDA précompilées ou WSL2 sont tous deux moins pénibles.

Comment identifier la version installée

Le contrôle le plus fiable est la sortie du chargeur détaillée, qui est agnostique de la version :

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

Sur une compilation CUDA vous verrez des lignes d'initialisation du backend mentionnant CUDA et un nom de périphérique, plus une ligne de chargement de tenseurs rapportant combien des couches du modèle ont été déchargées sur le GPU. Sur Metal vous verrez plutôt des lignes de périphérique Metal. Une compilation CPU uniquement n'affiche ni l'une ni l'autre et signale zéro couches déchargées. Vérifiez par recoupement avec nvidia-smi pendant la génération : si votre processus Python ne retient pas de VRAM, rien ne s'exécute sur le GPU.

Les versions récentes exposent également un contrôle de capacité direct :

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

Si cet attribut lève AttributeError, votre compilation est antérieure à cela — revenez à la méthode du journal détaillé.

Chargement d'un fichier GGUF et exécution d'une première génération de texte

Point model_path sur n'importe quel fichier GGUF. Si vous préférez extraire de Hugging Face, Llama.from_pretrained(repo_id=..., filename="*Q4_K_M.gguf", ...) effectue le téléchargement pour vous lorsque huggingface-hub est installé.

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"])

Pour la continuation de texte brut, appelez l'objet directement : llm("Q: What is a GGUF file? A:", max_tokens=128, stop=["Q:"]) et lisez out["choices"][0]["text"].

Flux de jetons

Passez stream=True et itérez. La forme de la réponse reflète le format de flux OpenAI, donc le premier bloc porte généralement uniquement le rôle et les blocs ultérieurs portent 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)

La plupart des fichiers GGUF embarquent un modèle de chat que llama-cpp-python applique automatiquement. Lorsque la sortie semble brouillée ou que le modèle ne s'arrête jamais, le modèle est le premier suspect — remplacez-le avec l'argument chat_format . Parcourez les options quantifiées et leurs tailles dans notre Base de données des modèles IA.

Les paramètres qui comptent

Paramètre	À quoi ça sert	Conseils pratiques
n_gpu_layers	Nombre de couches de transformateur à décharger sur le GPU. Par défaut 0, c.-à-d. CPU uniquement. -1 signifie toutes les couches.	Commencez par -1. Si vous rencontrez une erreur de mémoire insuffisante au chargement, diminuez jusqu'à ce que cela rentre.
n_ctx	Fenêtre de contexte en jetons. Par défaut une valeur délibérément petite (512 dans les versions actuelles). Passer 0 dit à llama.cpp de prendre la valeur à partir des métadonnées du modèle lui-même.	Définissez-la explicitement. 0 est légal mais un modèle entraîné pour un contexte de 128K tentera d'allouer un cache KV pour 128K jetons, ce qui c'est généralement ce qui épuise votre VRAM.
n_batch	Taille de lot logique pour le traitement des invites (prefill), pas la génération.	512 est la valeur par défaut courante. L'augmenter à 1024–2048 accélère les longues invites sur GPU au prix de plus de mémoire ; diminuez-la si vous voyez des échecs d'allocation de tampon.
n_ubatch	Micro-lot physique réellement soumis au backend.	Laissez tel quel à moins que vous ne soyez limité en mémoire, auquel cas une valeur plus petite réduit la taille du tampon de calcul de crête.
n_threads	Threads pour la génération. n_threads_batch couvre le traitement des invites.	Importe uniquement pour le travail toujours sur CPU. Définissez-le sur les cœurs physiques, pas les cœurs logiques (hyperthread).
offload_kqv	Indique si le cache KV réside sur le GPU.	Activé par défaut et normalement ce que vous voulez ; le désactiver libère du VRAM mais coûte beaucoup en vitesse.
use_mmap / use_mlock	Mappez le fichier en mémoire ; verrouillez-le en RAM.	Gardez mmap activé. Utilisez mlock uniquement si le système d'exploitation bascule les poids du modèle.
chat_format	Remplace le modèle de chat embarqué.	Définissez-le lorsque le modèle n'a pas de modèle intégré ou que celui-ci est incorrect.

Notez que l'attention flash et la quantification du cache KV (type_k / type_v) ont bougé entre les versions — le commutateur d'attention flash a été un booléen dans certaines versions et un paramètre à trois états auto/on/off dans d'autres. Exécutez help(Llama) sur votre version installée plutôt que de faire confiance à un nom de drapeau provenant d'un article de blog.

Réglage en pratique

Les deux paramètres qui interagissent sont n_gpu_layers et n_ctx. Les poids et le cache KV concurrencent le même VRAM, et le cache KV s'échelonne à peu près linéairement avec la longueur du contexte. Réduire n_ctx de 8192 à 4096 libère souvent assez de mémoire pour décharger plusieurs couches supplémentaires, ce qui est généralement le meilleur échange. Travaillez le budget avant de commencer à deviner avec notre calculatrice VRAMou vérifiez les chiffres par modèle dans le Référence des besoins en VRAM.

Le déchargement partiel fonctionne — c'est la signature feature de llama.cpp — mais attendez-vous à une chute drastique une fois qu'une couche reste sur CPU, car chaque token doit traverser le bus PCIe. Si vous pouvez adapter toutes les couches, faites-le.

Mode serveur compatible OpenAI

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

Les flags du serveur reflètent les arguments du constructeur, tirets bas inclus. Vous obtenez /v1/chat/completions, /v1/completions, /v1/models, et la documentation interactive sur /docs. N'importe quel client OpenAI fonctionne, et le streaming est supporté via SSE :

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)

Pour plus d'un modèle, passez --config_file config.json avec un modèles array, donnant à chaque entrée un modèle path, un model_alias que les clients peuvent demander par nom, et son propre n_gpu_layers / n_ctx. Ajoutez --api_key si le port est accessible au-delà de localhost. En pesant cela contre un endpoint hébergé ? Le Calculatrice du seuil de rentabilité auto-hébergement vs API fournit les chiffres.

Échecs courants lors de la compilation et solutions associées

Symptôme	Cause	Correctif
L'installation réussit mais pas de lignes GPU dans la sortie verbose	pip a réutilisé une wheel CPU en cache	Réinstallez avec --no-cache-dir --force-reinstall
Erreur lors de la construction de la wheel, CMake non trouvé	Pas de toolchain de build	Linux : build-essential plus CMake. macOS : xcode-select --install. Windows : VS Build Tools C++ workload
nvcc non trouvé lors de la configuration	Driver présent, toolkit manquant	Installez le CUDA Toolkit. La version CUDA dans nvidia-smi est le maximum du driver, pas un toolkit installé
« unsupported GNU version » de nvcc	gcc système plus récent que ce que votre CUDA supporte	Pointez CUDA vers un compilateur plus ancien avec -DCMAKE_CUDA_HOST_COMPILER=/usr/bin/gcc-12
La machine se fige ou manque de mémoire pendant la compilation	Trop de tâches de compilation parallèles	Définir CMAKE_BUILD_PARALLEL_LEVEL=4 avant pip install
« unknown model architecture » lors du chargement	GGUF plus récent que votre version llama.cpp	Mettez à jour llama-cpp-python ; une reconstruction est requise, pas juste un changement de config
CUDA à court de mémoire au moment du chargement	Les poids plus le cache KV dépassent la VRAM	Inférieur n_ctx d'abord, puis n_gpu_layers
Échec de l'allocation des buffers de calcul	n_batch trop grand pour la mémoire disponible	Réduisez n_batch (et n_ubatch)

Questions fréquemment posées

llama-cpp-python est-il la même chose que llama.cpp ?

Non. llama.cpp est le moteur d'inférence C/C++ ; llama-cpp-python vendorise un commit spécifique et le wraps pour Python. Parce que la version vendorisée est épinglée par release, les bindings peuvent traîner en amont de quelques jours ou semaines — ce qui importe quand une toute nouvelle architecture de modèle vient de débarquer dans llama.cpp mais pas encore dans une release de binding publiée.

Comment confirmer que le GPU est vraiment utilisé ?

Chargez avec verbose=True et cherchez les lignes d'initialisation du backend et un rapport des couches déchargées vers le GPU. Ensuite, surveillez nvidia-smi (ou l'historique GPU d'Activity Monitor sur macOS) pendant une génération. Si l'utilisation de VRAM n'augmente pas et que les tokens par seconde ressemblent à des chiffres CPU, vous êtes sur une compilation CPU uniquement.

Puis-je éviter de compiler entièrement ?

Souvent, oui — utilisez les index de roues précompilées du projet avec --extra-index-url, en faisant correspondre la balise CUDA à votre kit d'outils. Quand aucune roue correspondante n'existe pour votre version Python et votre plateforme, pip revient à une compilation source, qui prend généralement plusieurs minutes avec CUDA activé.

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

Utilisez llama-cpp-python quand vous voulez le modèle dans votre propre processus Python, avec un contrôle direct sur l'échantillonnage, les logits et les grammaires. Préférez Ollama pour un daemon géré avec des pulls de modèles et une gestion automatique de la mémoire, ou LM Studio pour une interface graphique. Les trois s'appuient sur llama.cpp, donc la qualité est comparable ; la différence réside dans l'ergonomie.

Puis-je exécuter un modèle plus grand que ma VRAM ?

Oui. Définissez n_gpu_layers à une valeur inférieure au nombre de couches du modèle et le reste s'exécute sur CPU avec la RAM système. Cela fonctionne de manière fiable, mais la pénalité de vitesse est sévère une fois qu'une part importante des couches reste sur CPU, donc un modèle plus petit avec une quantification plus élevée surpasse généralement un grand modèle partiellement déchargé.

Le support GPU fonctionne-t-il sur Windows sans WSL ?

Oui. Installez soit une roue CUDA précompilée, soit compilez à partir de la source avec Visual Studio Build Tools 2022 (Desktop development with C++) installé avant CUDA Toolkit, en définissant $env:CMAKE_ARGS dans PowerShell. WSL2 reste le chemin le plus fluide si vous êtes à l'aise avec cela, car les instructions de compilation Linux sont mieux établies.