> ## Documentation Index > Fetch the complete documentation index at: https://docs.tokios.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Tokios exposes private local models through https://api.tokios.com using an outbound-only connector tunnel. > Use 'connector' for the local tokios-connector process. > Use 'deployment' for the public model name in the API model field. > Use 'upstream model id' for the model served by Ollama, llama.cpp, vLLM, LM Studio, or another local backend. > API keys use the prefix sk-tok-. Connector tokens use the prefix ct-tok-. # Optimisez llama.cpp pour la vitesse et la mémoire > Réglez llama.cpp pour des performances maximales — flash attention, mmap contre mlock, réglage des threads, stratégie de délestage GPU, taille de lot, précision du cache KV et placement des experts MoE. llama.cpp est l'environnement d'inférence locale le plus portable. Il fonctionne sur CPU, GPU NVIDIA, GPU AMD et Apple Silicon — souvent à partir du même binaire. Cette flexibilité s'accompagne d'une longue liste de drapeaux, et les valeurs par défaut ne sont pas toujours optimales pour votre matériel. Ce guide couvre les drapeaux les plus importants et les compromis derrière chacun. > [!NOTE] > > Dernière vérification : 2026-10-14 — llama.cpp build b11609. > [!NOTE] > > Tous les drapeaux de ce guide s'appliquent à `llama-server` et `llama-cli` à partir du build llama.cpp **b11609** (14 octobre 2026). Les noms de drapeaux peuvent changer entre les builds — exécutez `llama-server --help` pour confirmer ce que votre binaire prend en charge. ## Flash attention Activez la flash attention avec `-fa` ou `--flash-attn on`. Dans la plupart des benchmarks, c'est ce qui se rapproche le plus d'une amélioration de performance gratuite offerte par llama.cpp — vous obtenez une inférence plus rapide avec la même utilisation mémoire voire moins, pour un coût en qualité négligeable. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf -fa ``` La flash attention retravaille la façon dont le modèle calcule les scores d'attention entre les tokens. Au lieu de matérialiser la matrice d'attention complète en mémoire, elle calcule l'attention par blocs en tuiles qui tiennent dans la SRAM rapide. Le résultat : * **Utilisation mémoire réduite** pour le cache KV — le gain le plus important à de longues longueurs de contexte. * **Inférence plus rapide** — surtout sur GPU, où le calcul en tuiles correspond bien aux tensor cores. * **Même qualité de sortie** — la flash attention est mathématiquement équivalente à l'attention standard, pas une approximation. > [!TIP] > > **Commencez toujours par `-fa`.** Il n'y a aucune raison de le laisser désactivé sauf si vous rencontrez un problème de compatibilité avec un modèle ou une plateforme spécifique. C'est le drapeau à l'impact le plus élevé dans ce guide. ## mmap vs mlock llama.cpp charge les poids du modèle en mémoire en utilisant l'une des 2 stratégies. Par défaut, c'est `--mmap`, qui mappe le fichier modèle directement dans l'espace d'adresses virtuelles du processus. L'alternative est `--mlock`, qui épingle l'intégralité du modèle dans la RAM physique. | Drapeau | Ce qu'il fait | Idéal pour | | - | - | - | | `--mmap` (par défaut) | Mappe le fichier ; l'OS pagine les données en entrée/sortie selon les besoins | Exécutions ponctuelles, machines à mémoire contrainte, expériences rapides | | `--mlock` | Épingle chaque octet en RAM physique ; rien n'est paginé | Inférence répétée, serveurs d'inférence dédiés, modèles que vous exécutez toute la journée | ### Quand mmap l'emporte `--mmap` est la valeur par défaut car il fonctionne bien pour la plupart des usages interactifs. L'OS charge les pages du modèle à la demande, donc le démarrage est rapide et le fichier modèle ne double-compte pas dans votre RAM jusqu'à ce que les pages soient effectivement touchées. Si vous testez des modèles ou exécutez des sessions courtes, la valeur par défaut convient. ### Quand mlock l'emporte `--mlock` empêche l'OS d'évincer les pages du modèle vers le swap. Cela importe quand : * Vous exécutez le même modèle toute la journée et voulez une latence constante — pas de pénalité de démarrage à froid due aux défauts de page. * Votre système est sous pression mémoire d'autres processus et pourrait paginer les poids du modèle. * Vous êtes sur une machine avec un swap lent (ou sans swap) et un défaut de page bloquerait l'inférence pendant des secondes. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf -fa --mlock ``` > [!WARNING] > > `--mlock` nécessite que l'intégralité du modèle tienne dans la RAM physique disponible. S'il ne tient pas, le processus ne démarre pas. Vérifiez votre mémoire disponible avec `free -h` sur Linux ou le Moniteur d'activité sur macOS avant de l'activer. ## Réglage des threads Le drapeau `-t` définit le nombre de threads CPU utilisés pour l'inférence. La bonne valeur dépend de la quantité de travail que le CPU effectue réellement. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf -t 8 ``` | Scénario | Recommandation de threads | | - | - | | Déchargement GPU complet (toutes les couches sur GPU) | `-t 2` à `-t 4` — le CPU gère l'orchestration et la tokenisation, pas les calculs | | Déchargement GPU partiel (certaines couches sur CPU) | Définissez `-t` au nombre de cœurs physiques de votre CPU — pas les hyperthreads | | CPU uniquement (pas de GPU) | Définissez `-t` au nombre de cœurs physiques | > [!TIP] > > Plus de threads n'est pas toujours plus rapide. Au-delà du nombre de cœurs physiques, les threads se disputent le cache et la bande passante mémoire et peuvent ralentir l'inférence. En cas de doute, commencez par le nombre de cœurs physiques et benchmarkez à partir de là. Sur Apple Silicon, le réglage des threads importe moins car le GPU et le CPU partagent la mémoire unifiée et le backend Metal gère la planification. La valeur par défaut fonctionne généralement bien. ## Stratégie de déchargement GPU Le drapeau `-ngl` contrôle le nombre de couches du modèle que vous déchargez sur le GPU. Plus de couches sur le GPU signifie une inférence plus rapide, mais chaque couche consomme de la VRAM. ### Déchargement partiel Définissez `-ngl` au nombre de couches que vous pouvez faire tenir en mémoire GPU. Les couches restantes s'exécutent sur le CPU. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf -ngl 20 -fa ``` Utilisez le déchargement partiel quand le modèle complet ne tient pas dans la VRAM. Commencez par une valeur élevée et réduisez jusqu'à ce que le serveur démarre sans épuiser la mémoire. ### Déchargement complet Définissez `-ngl 999` pour décharger toutes les couches. llama.cpp utilise 999 comme « toutes les couches restantes » — il n'essaie pas littéralement de décharger 999 couches. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf -ngl 999 -fa ``` Le déchargement complet donne la meilleure vitesse d'inférence car chaque passe avant s'exécute sur le GPU. Les poids du modèle et le cache KV doivent tous deux tenir en VRAM. ### Budget mémoire par couche Chaque couche déchargée consomme de la VRAM pour les poids et le cache KV. Une estimation approximative : ``` VRAM per layer ≈ (parameter_count_per_layer × bytes_per_weight) + KV_cache_per_layer ``` Pour un modèle 7B en Q4\_K\_M (\~4.5 bits par poids, \~40 couches) : | Composant | Par couche | Total 40 couches | | - | - | - | | Poids | \~0.15 GB | \~6 GB | | Cache KV (f16, ctx 4K) | \~0.05 GB | \~2 GB | | **Total** | | **\~8 GB** | Laissez 1 à 2 GB de marge VRAM pour le contexte CUDA et la surcharge. ## Réglage de la taille de lot Deux drapeaux contrôlent le nombre de tokens que llama.cpp traite à la fois pendant la phase de pré-remplissage : | Drapeau | Ce qu'il contrôle | | - | - | | `-b` (taille de lot) | Total de tokens traités en un lot pendant l'ingestion du prompt | | `-ub` (taille UBatch) | Maximum de tokens par micro-lot dans un seul lot | ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf -b 512 -ub 512 -fa ``` ### Comment ils interagissent * **`-b`** définit la limite extérieure. Si un prompt a plus de tokens que `-b`, llama.cpp le divise en plusieurs lots. * **`-ub`** définit la taille de morceau intérieure. llama.cpp traite le lot en micro-lots d'un maximum de `-ub` tokens. * `-ub` doit être inférieur ou égal à `-b`. ### Compromis | Paramètre | Effet | | - | - | | Plus grand `-b` (512-2048) | Pré-remplissage plus rapide pour les longs prompts — plus de tokens traités par passe avant | | Plus grand `-b` | Plus de VRAM/RAM consommée pendant l'ingestion du prompt | | Plus petit `-b` (128-256) | Utilisation mémoire plus faible, pré-remplissage plus lent | | `-ub` égal à `-b` | Configuration la plus simple ; un seul micro-lot couvre le lot complet | | `-ub` plus petit que `-b` | Plafonne la mémoire par micro-lot ; utile quand `-b` est grand mais la VRAM est limitée | > [!TIP] > > Pour le chat interactif avec des prompts courts (moins de 1K tokens), la valeur par défaut `-b 512` convient. Augmentez-la seulement si vous ingérez régulièrement de longs documents et voulez un temps jusqu'au premier token plus rapide. ## Précision du cache KV Le cache KV stocke les tenseurs de clés et de valeurs pour chaque token dans chaque séquence active. Par défaut, llama.cpp utilise f16 (virgule flottante 16 bits) pour les clés et les valeurs. Vous pouvez passer à une précision quantifiée pour réduire l'utilisation mémoire avec un léger coût en qualité. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf -fa \ --cache-type-k q8_0 --cache-type-v q8_0 ``` | Précision | Mémoire par élément | Qualité | Quand utiliser | | - | - | - | - | | `f16` (par défaut) | 2 bytes | Référence | Qualité maximale ; vous avez beaucoup de mémoire | | `q8_0` | 1 byte | Quasi identique à f16 | Meilleur équilibre — divise par deux la mémoire du cache KV avec une perte de qualité négligeable | | `q4_0` | 0.5 bytes | Légère dégradation | Mémoire limitée ; contexte long ou nombreuses séquences concurrentes | Vous pouvez définir les clés et les valeurs indépendamment. Un schéma courant est `q8_0` pour les deux, ce qui divise par deux l'empreinte du cache KV avec moins de 1% de différence de qualité sur la plupart des benchmarks. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Aggressive: quarter the KV cache memory llama-server -m model.gguf -fa \ --cache-type-k q4_0 --cache-type-v q4_0 ``` > [!WARNING] > > `q4_0` dans le cache KV introduit une perte de qualité mesurable sur les tâches qui reposent sur une attention précise sur un contexte long — récupération needle-in-a-haystack, résumé multi-documents et longues conversations. Testez votre charge de travail spécifique avant de vous engager sur `q4_0`. ## Optimisation MoE Les modèles mixture-of-experts comme Qwen3.5-35B-A3B ou Mixtral stockent un grand nombre de sous-réseaux d'experts dans chaque couche, mais n'en activent que quelques-uns par token. Les poids des experts restent en mémoire même lorsqu'ils sont inactifs, ce qui rend les modèles MoE disproportionnément grands par rapport à leur nombre de paramètres actifs. Sur les systèmes multi-GPU, vous pouvez placer les couches d'experts sur le CPU quand la mémoire GPU est limitée : ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf -ngl 999 --n-cpu-moe 4 -fa ``` `--n-cpu-moe ` garde le nombre spécifié de sous-couches d'experts sur le CPU tandis que le reste du modèle s'exécute sur GPU. Cela échange une légère augmentation de latence contre la possibilité de faire tenir un modèle plus grand en VRAM. | Scénario | Configuration | | - | - | | Le MoE tient entièrement en VRAM | `-ngl 999` — pas d'experts CPU nécessaires | | Le MoE tient presque, quelques experts débordent | `--n-cpu-moe 2` à `--n-cpu-moe 8` | | Le MoE est trop grand pour toute configuration GPU raisonnable | Combinez `--n-cpu-moe` avec un partiel `-ngl` | > [!TIP] > > Commencez avec `--n-cpu-moe 0` (tous les experts sur GPU) et augmentez seulement lorsque vous manquez de VRAM. Chaque expert déplacé vers le CPU ajoute de la latence car les données doivent traverser le bus PCIe pendant la passe avant. ## Configurations exemples ### Apple Silicon — optimisé pour les Mac série M ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf \ -fa \ --mlock \ -b 512 \ -ub 512 \ --cache-type-k q8_0 \ --cache-type-v q8_0 \ -ngl 999 \ --port 8080 ``` Cela épingle le modèle dans la mémoire unifiée, active la flash attention et quantifie le cache KV pour optimiser votre budget mémoire. La mémoire unifiée d'Apple Silicon signifie que le GPU peut accéder à l'ensemble du pool de RAM, donc le déchargement complet (`-ngl 999`) fonctionne tant que le modèle et le cache KV tiennent. > [!NOTE] > > llama.cpp fonctionne bien sur Apple Silicon, mais si vous déployez exclusivement sur Mac, [MLX](https://github.com/ml-explore/mlx) est optimisé pour le backend Metal d'Apple et peut offrir une inférence plus rapide pour le même modèle. Utilisez llama.cpp quand vous avez besoin de portabilité multiplateforme ou d'un serveur compatible OpenAI. ### Déchargement GPU — GPU discret NVIDIA ou AMD ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf \ -fa \ -ngl 999 \ -b 512 \ -ub 512 \ --cache-type-k q8_0 \ --cache-type-v q8_0 \ -t 4 \ --port 8080 ``` Déchargement GPU complet avec flash attention et cache KV quantifié. Les 4 threads CPU gèrent l'orchestration et la tokenisation. Réduisez `-ngl` si le modèle ne tient pas — commencez au nombre total de couches et diminuez de 5 jusqu'à ce qu'il charge. ### CPU uniquement — pas de GPU disponible ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} llama-server -m model.gguf \ -t 8 \ -b 256 \ -ub 256 \ --cache-type-k q8_0 \ --cache-type-v q8_0 \ --port 8080 ``` Pas de déchargement GPU, donc le CPU fait tout le travail. Le nombre de threads correspond aux cœurs physiques. La taille de lot plus petite maintient l'utilisation mémoire gérable. Utilisez une quantification Q4\_K\_M ou Q5\_K\_M pour les poids du modèle afin de garder l'empreinte réduite. ## Prochaines étapes > **[Accès à distance llama.cpp](/fr/guides/llama-cpp-remote-access.md)** > > Exposez votre serveur llama.cpp à vos coéquipiers et agents via Tokios — sans ouvrir de ports. > **[Décodage spéculatif](/fr/guides/speculative-decoding.md)** > > Accélérez le décodage avec des modèles brouillon, des n-grammes et EAGLE — fonctionne avec les backends llama.cpp. > **[Testez votre déploiement](/fr/guides/benchmark-your-deployment.md)** > > Mesurez la latence et le débit après le réglage pour confirmer l'amélioration. > **[Cache KV et contexte](/fr/concepts/kv-cache-and-context.md)** > > Explication plus approfondie du fonctionnement du cache KV à travers les architectures de modèles et les environnements d'exécution. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.