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

llama-cpp-python est la liaison Python pour llama.cpp. Elle permet de charger des modèles GGUF en mémoire, expose un wrapper ctypes bas niveau ainsi qu’une interface haut niveau sous forme de classe, et intègre un serveur HTTP compatible OpenAI. L’installation par défaut via pip produit une version fonctionnant uniquement sur CPU. 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 n’a aucun effet utile dans une version compilée pour CPU uniquement, ce qui amène souvent les utilisateurs à conclure à tort que leur GPU est « trop lent », alors qu’il n’a jamais été sollicité. Deuxièmement, pip met en cache les wheels compilés. Réexécuter l’installation avec des paramètres différents peut vous renvoyer involontairement le wheel CPU mis en cache — c’est pourquoi chaque commande de recompilation ci-dessous inclut CMAKE_ARGS --no-cache-dir --force-reinstall Option 1 : wheels précompilés (aucun compilateur requis).

Installer llama-cpp-python avec le support GPU

Le projet publie des index de wheels, notamment un index dédié aux processeurs (CPU) à l’adresse

https://abetlen.github.io/llama-cpp-python/whl/cpu et des variantes CUDA dont le segment de chemin indique la version de CUDA utilisée, par exemple .../whl/cu124 . Installez-les à l’aide de la commande suivante :pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124

Les versions de CUDA et les versions de Python prises en charge varient d’une version à l’autre, et les index peuvent parfois ne pas refléter immédiatement la dernière version publiée sur PyPI. Consultez plutôt le fichier README du projet pour connaître les tags actuellement disponibles, plutôt que de faire une hypothèse — un tag erroné entraîne une erreur 404, et pip retombe silencieusement sur une compilation depuis les sources.

Option 2 : compilation depuis les sources (Linux, CUDA)

Vous devez disposer d’une chaîne d’outils C++, de CMake et du kit CUDA, avec l’exécutable

nvcc présent dans votre variable d’environnement PATH. nvcc --version # doit afficher une version, et non « commande introuvable »CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python --no-cache-dir --force-reinstall --upgrade

Le nom du drapeau a évolué au fil du temps : les anciens guides utilisent

-DLLAMA_CUBLAS=on , les guides datant de mi-2024 utilisent-DLLAMA_CUDA=on , tandis que la version actuelle officielle utilise le préfixeGGML_ . Si la compilation échoue avec une erreur liée à une option CMake inconnue, cette incohérence est très probablement la cause. Les autres backends suivent le même schéma : Vulkan utilise -DGGML_VULKAN=on , SYCL utilise-DGGML_SYCL=on , et l’option AMD/ROCm a changé de nom plusieurs fois — consultez donc le README correspondant à votre version installée plutôt que de copier un drapeau depuis un forum.Vous pouvez réduire considérablement le temps de compilation en ciblant uniquement l’architecture de calcul (compute capability) de votre GPU, par exemple

-DCMAKE_CUDA_ARCHITECTURES=89 pour une carte Ada comme le RTX 4090, ou pour un RTX 3090. Consultez la liste officielle de NVIDIA pour identifier l’architecture de calcul de votre carte ; si vous êtes encore en phase de choix matériel, notre 86 guide sur les meilleurs GPU pour exécuter localement des modèles de langage volumineux (LLM) traite des compromis entre capacité de mémoire vidéo (VRAM) et coût. Option 3 : macOS avec Metal

xcode-select --installCMAKE_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 Python x86 via Rosetta :

python -c "import platform; print(platform.machine())" doit afficher arm64 . Un interpréteur x86_64 produira une compilation dépourvue de backend Metal, quelle que soit la valeur de CMAKE_ARGS fournie. Comme le GPU et le CPU partagent la même mémoire sur Apple Silicon,est presque toujours le paramètre approprié dans ce cas. n_gpu_layers=-1 Option 4 : Windows avec CUDA

Installez les « Visual Studio Build Tools 2022 » avec la charge de travail « Développement classique avec C++ »

, puis le kit CUDA, afin que celui-ci installe son intégration MSBuild dans une instance existante de Visual Studio. Ensuite, dans PowerShell : premier$env:CMAKE_ARGS = "-DGGML_CUDA=on" pip install llama-cpp-python --no-cache-dir --force-reinstall --upgrade

cmd.exe

Dans l’équivalent est set CMAKE_ARGS=-DGGML_CUDA=on sur une ligne séparée. Les compilations natives sous Windows sont la méthode la plus sujette à échec parmi les trois plateformes ; si vous souhaitez uniquement effectuer des inférences — et non créer une version personnalisée — les wheels CUDA précompilés ou WSL2 constituent des alternatives bien moins contraignantes. Le moyen le plus fiable de vérifier le bon fonctionnement est la sortie détaillée du chargeur, indépendante de la version :

Comment identifier la version installée

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

Dans une version compilée avec CUDA, vous verrez des lignes d’initialisation mentionnant CUDA ainsi qu’un nom de périphérique, accompagnées d’une ligne indiquant combien de couches du modèle ont été transférées vers le GPU. Avec Metal, vous verrez à la place des lignes relatives au périphérique Metal. Une version CPU uniquement n’affichera ni l’un ni l’autre, et signalera zéro couche transférée. Vérifiez également avec

Dans une compilation CUDA, vous verrez des lignes d’initialisation du backend mentionnant CUDA et un nom de périphérique, ainsi qu’une ligne de chargement de tenseur indiquant combien de couches du modèle ont été déchargées vers le GPU. Sur Metal, vous verrez à la place des lignes relatives au périphérique Metal. Une compilation destinée uniquement au CPU n’affiche aucune de ces lignes et signale zéro couche déchargée. Vérifiez cela en recoupant avec nvidia-smi pendant la génération : si votre processus Python n'occupe pas de VRAM, rien ne s'exécute sur le GPU.

Les versions récentes exposent également une vérification directe des fonctionnalités :

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

Si cet attribut déclenche une AttributeError, votre version compilée est antérieure à son introduction — revenez alors à la méthode basée sur les journaux verbeux.

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

Point model_path vers n’importe quel fichier GGUF. Si vous préférez télécharger depuis Hugging Face, Llama.from_pretrained(repo_id=..., filename="*Q4_K_M.gguf", ...) effectue automatiquement le téléchargement dès lors que 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": "Expliquez ce qu’est un cache KV en deux phrases."}],
    max_tokens=256,
    temperature=0.7,
)
print(out["choices"][0]["message"]["content"])

Pour une continuation brute de texte, appelez directement l’objet : llm("Q : Qu’est-ce qu’un fichier GGUF ? R :", max_tokens=128, stop=["Q:"]) et lire out["choices"][0]["text"].

Diffusion en continu des jetons

Spécifiez stream=True et itérez. La structure de la réponse suit le format de diffusion en continu d’OpenAI : le premier fragment contient généralement uniquement le rôle, tandis que les fragments suivants contiennent des deltas de content (contenu) :

stream = llm.create_chat_completion(
    messages=[{"role": "user", "content": "Rédigez un haïku sur les fichiers GGUF."}],
    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 intègrent un modèle de discussion (chat template) appliqué automatiquement par llama-cpp-python. Lorsque la sortie semble corrompue ou que le modèle ne s’arrête jamais, ce modèle est le premier suspect — remplacez-le à l’aide de l’argument chat_format Consultez les options quantifiées et leurs tailles dans notre Base de données des modèles IA.

Les paramètres qui comptent

Notez que l’attention flash et la quantification du cache KV (type_k / type_v) ont changé d’emplacement entre les versions — le commutateur flash-attention a été un booléen dans certaines versions et un paramètre à trois états (auto/activé/désactivé) 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.

Ajustement en pratique

Les deux paramètres qui interagissent sont n_gpu_layers et n_ctx. Les poids et le cache KV se font concurrence pour la même mémoire VRAM, et la taille du cache KV augmente approximativement de façon linéaire avec la longueur du contexte. Réduire de moitié n_ctx de 8192 à 4096 libère souvent suffisamment de mémoire pour décharger plusieurs couches supplémentaires, ce qui constitue généralement un meilleur compromis. Évaluez votre budget mémoire avant de procéder à des essais empiriques à l’aide de notre Calculateur de VRAM, ou consultez les chiffres spécifiques par modèle dans la référence des exigences en VRAM.

Le déchargement partiel fonctionne — c’est même la fonctionnalité phare de llama.cpp — mais attendez-vous à une chute brutale des performances dès qu’une couche reste sur le CPU, car chaque jeton doit traverser le bus PCIe. Si vous pouvez charger toutes les couches sur le GPU, 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 drapeaux du serveur reflètent les arguments du constructeur, y compris les caractères de soulignement. Vous obtenez /v1/chat/completions, /v1/completions, /v1/models, ainsi que de la documentation interactive à l’adresse /docs. Tout client OpenAI est compatible, et le streaming est pris en charge via SSE (Server-Sent Events) :

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",  # ignoré sauf si vous définissez des alias de modèle
    messages=[{"role": "user", "content": "Bonjour"}],
    stream=True,
):
    print(event.choices[0].delta.content or "", end="", flush=True)

Pour plus d’un modèle, passez --config_file config.json contenant un tableau dans lequel chaque entrée possède un champ modèles path modèle (chemin d’accès), un champ model_alias que les clients peuvent utiliser pour demander le modèle par nom, ainsi que ses propres n_gpu_layers / n_ctxparamètres. Ajoutez --api_key si le port est accessible depuis d’autres machines que localhost. Pour comparer cette solution à un point de terminaison hébergé ? Le calculateur d’auto-hébergement vs seuil de rentabilité d’une API fournit des chiffres concrets.

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

Questions fréquemment posées

Est-ce que llama-cpp-python est identique à llama.cpp ?

Non. llama.cpp est le moteur d’inférence en C/C++ ; llama-cpp-python intègre (« vend ») un commit spécifique de ce projet et l’enveloppe pour une utilisation en Python. Comme la version intégrée est figée (« pinned ») pour chaque version publiée, les liaisons (bindings) peuvent présenter un retard de plusieurs jours ou semaines par rapport à la branche principale (upstream). Cela revêt une importance particulière lorsqu’une toute nouvelle architecture de modèle vient d’être intégrée dans llama.cpp, mais n’est pas encore disponible dans une version publiée des liaisons.

Comment vérifier que le GPU est bien utilisé ?

Chargez le modèle avec verbose=True et recherchez les lignes d’initialisation du backend ainsi qu’un rapport indiquant le nombre de couches déchargées vers le GPU. Ensuite, surveillez nvidia-smi (ou l’historique GPU du Moniteur d’activité sur macOS) pendant une génération. Si l’utilisation de la VRAM ne monte pas et que le débit de jetons par seconde correspond à des valeurs typiques du CPU, cela signifie que vous utilisez une version compilée pour CPU uniquement.

Puis-je éviter complètement la compilation ?

Souvent, oui — utilisez les index de wheels précompilés du projet avec l’option --extra-index-url, en veillant à faire correspondre l’étiquette CUDA à votre kit d’outils. Lorsqu’aucun wheel compatible n’est disponible pour votre version de Python et votre plateforme, pip retombe automatiquement sur une compilation depuis les sources, qui prend généralement plusieurs minutes lorsque CUDA est activé.

Faut-il privilégier llama-cpp-python, Ollama ou LM Studio?

Utilisez llama-cpp-python lorsque vous souhaitez intégrer le modèle directement dans votre propre processus Python, avec un contrôle précis des paramètres d’échantillonnage, des logits et des grammaires. Préférez Ollama pour un démon géré, prenant en charge le téléchargement automatique des modèles et la gestion mémoire dynamique, ou LM Studio pour une interface graphique (GUI). Les trois solutions reposent sur llama.cpp, donc la qualité des résultats est comparable ; la différence réside uniquement dans leur ergonomie.

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

Oui. Définissez n_gpu_layers à une valeur inférieure au nombre total de couches du modèle : les couches restantes s’exécuteront alors sur le CPU, en utilisant la mémoire système (RAM). Cette méthode fonctionne de façon fiable, mais la pénalité en termes de vitesse devient sévère dès lors qu’une part significative des couches reste sur le CPU. Dans la plupart des cas, un modèle plus petit, mais quantifié à un niveau plus élevé, offre de meilleures performances qu’un modèle très volumineux partiellement déchargé sur le GPU.

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

Oui. Vous pouvez soit installer un wheel CUDA précompilé, soit compiler depuis les sources à l’aide des « Visual Studio Build Tools 2022 » (avec la charge de travail « Développement pour le poste de travail avec C++ ») installés avant le kit CUDA, puis définir la variable d’environnement $env:CMAKE_ARGS dans PowerShell. Toutefois, WSL2 demeure la solution la plus fluide si vous êtes à l’aise avec cet environnement, car les instructions de compilation sous Linux sont mieux documentées et éprouvées.