> ## 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 Ollama pour la vitesse et la mémoire > Réglez Ollama pour une vitesse maximale — fenêtre de contexte, délestage GPU, flash attention, quantification du cache KV et requêtes parallèles. Réduisez la latence de 2-5x avec ces paramètres. Ollama est le moyen le plus rapide de lancer un modèle local — `ollama run llama3` et vous servez déjà. Sous le capot, il enveloppe llama.cpp (et MLX sur Apple Silicon), et expose quelques variables d'environnement et paramètres de modèle qui contrôlent l'utilisation de votre matériel. Les valeurs par défaut fonctionnent pour un usage occasionnel mais laissent des performances significatives sur la table. Ce guide couvre chaque paramètre important et comment le régler pour votre charge de travail. > [!NOTE] > > Dernière vérification : 2026-10-14 — Ollama v0.33.2. > [!NOTE] > > **Apple Silicon utilise MLX.** À partir d'Ollama 0.19, le backend par défaut sur Apple Silicon est le framework MLX d'Apple plutôt que llama.cpp. MLX offre une inférence sensiblement plus rapide sur les puces M-série (voir [Optimisation Apple Silicon et MLX](#apple-silicon-and-mlx-optimization)). La plupart des variables d'environnement de ce guide s'appliquent aux deux backends ; lorsque le comportement diffère, c'est signalé explicitement. ## Réglage de la fenêtre de contexte La fenêtre de contexte (`num_ctx`) contrôle le nombre de tokens que le modèle peut traiter en une seule requête — votre invite plus la réponse générée combinées. C'est le plus gros facteur d'utilisation de la mémoire après les poids du modèle eux-mêmes. ### Comment augmenter la fenêtre de contexte d'Ollama Ollama utilise par défaut une fenêtre de contexte de 2048 tokens. La plupart des modèles modernes prennent en charge 8K, 32K ou même 128K tokens, mais Ollama n'utilise pas le maximum du modèle par défaut — il utilise 2048 pour garder l'utilisation de la mémoire prévisible. Définissez-la de 3 manières, de la plus spécifique à la plus globale : **Par requête (API) :** ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} curl http://localhost:11434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "llama3", "messages": [{"role": "user", "content": "Summarize this document..."}], "options": { "num_ctx": 32768 } }' ``` **Dans un Modelfile (persistant par modèle) :** ```dockerfile theme={"theme":{"light":"github-light","dark":"css-variables"}} FROM llama3 PARAMETER num_ctx 32768 ``` Ensuite, construisez et exécutez le modèle personnalisé : ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} ollama create llama3-32k -f Modelfile ollama run llama3-32k ``` **Globalement (tous les modèles, toutes les requêtes) :** ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Linux (systemd) sudo systemctl edit ollama.service # Add: Environment="OLLAMA_CONTEXT_LENGTH=32768" sudo systemctl daemon-reload && systemctl restart ollama ``` ```powershell Windows theme={"theme":{"light":"github-light","dark":"css-variables"}} [System.Environment]::SetEnvironmentVariable("OLLAMA_CONTEXT_LENGTH", "32768", "User") # Restart Ollama ``` ```bash macOS theme={"theme":{"light":"github-light","dark":"css-variables"}} launchctl setenv OLLAMA_CONTEXT_LENGTH 32768 # Restart Ollama ``` ### Coût mémoire de la fenêtre de contexte Le cache KV croît linéairement avec la longueur du contexte. La formule : ``` KV cache memory = 2 × num_layers × hidden_dim × num_ctx × precision_bytes ``` Pour un modèle 7B (32 couches, dimension cachée 4096) en précision f16 : | Context length | KV cache memory | | - | - | | 2,048 (default) | \~1 GB | | 8,192 | \~4 GB | | 32,768 | \~16 GB | | 128,000 | \~64 GB | > [!TIP] > > Définissez `num_ctx` aussi haut que votre charge de travail en a réellement besoin. Un agent de codage qui envoie des invites de 2K tokens ne bénéficie pas d'une fenêtre de contexte de 128K — il gaspille juste 64 Go d'espace de cache KV qui pourrait servir d'autres requêtes ou accueillir un modèle plus grand. ## Flash attention La flash attention est ce qui se rapproche le plus d'une amélioration de performance gratuite offerte par Ollama. Elle restructure la façon dont le modèle calcule l'attention entre les tokens — au lieu de matérialiser la matrice d'attention complète en mémoire, elle calcule l'attention par morceaux en tuiles qui tiennent dans la SRAM rapide. Le résultat : * **30-50% d'utilisation mémoire en moins** pour le cache KV — le plus gros gain aux longueurs de contexte élevées. * **Inférence plus rapide** — surtout sur GPU, où le calcul par tuiles correspond bien aux tensor cores. * **Même qualité de sortie** — la flash attention est mathématiquement équivalente à l'attention standard, pas une approximation. ### Comment activer la flash attention dans Ollama Définissez la variable d'environnement : ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Linux (systemd) sudo systemctl edit ollama.service # Add: Environment="OLLAMA_FLASH_ATTENTION=1" sudo systemctl daemon-reload && systemctl restart ollama ``` ```powershell Windows theme={"theme":{"light":"github-light","dark":"css-variables"}} [System.Environment]::SetEnvironmentVariable("OLLAMA_FLASH_ATTENTION", "1", "User") # Restart Ollama ``` ```bash macOS theme={"theme":{"light":"github-light","dark":"css-variables"}} launchctl setenv OLLAMA_FLASH_ATTENTION 1 # Restart Ollama ``` > [!TIP] > > **Activez toujours la flash attention.** Il n'y a aucune raison de la laisser désactivée sauf si vous rencontrez un problème de compatibilité avec un modèle ou une plateforme spécifique. C'est le paramètre à l'impact le plus élevé dans ce guide. > [!NOTE] > > Sur Apple Silicon avec le backend MLX, la flash attention est activée par défaut et la variable `OLLAMA_FLASH_ATTENTION` n'a aucun effet — MLX utilise toujours des noyaux d'attention optimisés. ## Stratégie de délestage GPU Ollama délègue automatiquement les couches du modèle à votre GPU. Quand le modèle complet tient dans la VRAM, chaque couche s'exécute sur le GPU pour une vitesse maximale. Quand la VRAM est limitée, Ollama répartit les couches entre GPU et CPU — le GPU exécute ce qu'il peut, et le reste revient à la RAM système. ### Comment Ollama décide des couches GPU La planification GPU d'Ollama fonctionne dans cet ordre : 1. **Délestage complet** — si les poids du modèle + le cache KV tiennent dans la VRAM, toutes les couches vont au GPU. C'est la configuration la plus rapide. 2. **Délestage partiel** — si le modèle ne tient pas entièrement, Ollama place autant de couches que possible sur le GPU et exécute le reste sur CPU. Les performances se dégradent car chaque passe avant doit traverser le bus PCIe pour les couches résidant sur CPU. 3. **CPU uniquement** — si aucun GPU n'est disponible ou si la VRAM est trop petite même pour quelques couches, le modèle entier s'exécute sur CPU. ### Contrôler les couches GPU avec `num_gpu` Le paramètre `num_gpu` définit le nombre de couches à délester sur le GPU. Définissez-le dans un Modelfile ou par requête : ```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}} FROM llama3 PARAMETER num_gpu 35 ``` ```bash API theme={"theme":{"light":"github-light","dark":"css-variables"}} curl http://localhost:11434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "llama3", "messages": [{"role": "user", "content": "Hello"}], "options": { "num_gpu": 35 } }' ``` | `num_gpu` value | Behavior | | - | - | | `-1` | All layers on GPU (same as setting it to the total layer count) | | `0` | No GPU offload — CPU only | | `1` to `N` | Exactly that many layers on GPU, rest on CPU | | Not set (default) | Ollama auto-detects based on available VRAM | > [!TIP] > > Laissez `num_gpu` non défini et laissez Ollama auto-détecter dans la plupart des cas. Ne le définissez manuellement que lorsque vous devez forcer une répartition spécifique — par exemple, pour réserver de la VRAM pour une fenêtre de contexte plus grande ou pour garder quelques couches sur CPU pour un modèle qui tient à peine. ### Budgétisation de la VRAM Chaque couche délestée consomme de la VRAM pour les poids et le cache KV. Une estimation approximative : ``` VRAM per layer ≈ (parameters_per_layer × bytes_per_weight) + (KV_cache_per_layer × num_ctx) ``` Pour un modèle 7B en Q4\_K\_M (\~4.5 bits par poids, \~32 couches) : | Component | Per layer | 32 layers total | | - | - | - | | Weights | \~0.19 GB | \~6 GB | | KV cache (f16, 8K ctx) | \~0.13 GB | \~4 GB | | **Total** | | **\~10 GB** | Laissez 1-2 Go de marge de VRAM pour le contexte CUDA et la surcharge. > [!WARNING] > > Lorsque vous augmentez `num_ctx`, le cache KV grossit et peut pousser des couches hors de la VRAM. Si vous définissez `num_ctx 32768` et qu'Ollama délègue soudainement la moitié des couches au CPU, c'est le cache KV qui a mangé votre budget VRAM. Réduisez `num_ctx`, utilisez une quantification plus petite ou activez la flash attention pour réduire le cache KV. ## Précision du cache KV Le cache KV stocke les tenseurs de clés et valeurs pour chaque token dans chaque séquence active. Par défaut, Ollama utilise `f16` (16-bit floating point). Vous pouvez passer à une précision quantifiée pour réduire l'utilisation de la mémoire avec un léger coût en qualité. Définissez le type de cache avec la variable d'environnement `OLLAMA_KV_CACHE_TYPE` : ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Linux (systemd) sudo systemctl edit ollama.service # Add: Environment="OLLAMA_KV_CACHE_TYPE=q8_0" sudo systemctl daemon-reload && systemctl restart ollama ``` | Cache type | Memory per element | Quality | When to use | | - | - | - | - | | `f16` (default) | 2 bytes | Baseline | Maximum quality; you have plenty of memory | | `q8_0` | 1 byte | Near-identical to f16 | Best balance — halves KV cache memory with negligible quality loss | | `q4_0` | 0.5 bytes | Slight degradation | Tight memory; long context or many concurrent sequences | ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Halve KV cache memory OLLAMA_KV_CACHE_TYPE=q8_0 # Quarter KV cache memory OLLAMA_KV_CACHE_TYPE=q4_0 ``` > [!TIP] > > Combinez `OLLAMA_KV_CACHE_TYPE=q8_0` avec `OLLAMA_FLASH_ATTENTION=1` pour le plus gros gain de mémoire. La flash attention réduit l'empreinte du cache KV de 30-50%, et q8\_0 la réduit de moitié encore — ensemble, elles peuvent réduire la mémoire du cache KV de 60-75% par rapport au défaut. > [!WARNING] > > `q4_0` KV cache introduit une perte de qualité mesurable sur les tâches qui reposent sur une attention précise sur un contexte long — needle-in-a-haystack retrieval, résumé multi-documents et longues conversations. Testez votre charge de travail spécifique avant de passer à `q4_0`. ## Configuration des threads Le paramètre `num_thread` contrôle le nombre de threads CPU qu'Ollama utilise pour l'inférence. La bonne valeur dépend de la quantité de travail que le CPU effectue réellement. Définissez-le dans un Modelfile ou par requête : ```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}} FROM llama3 PARAMETER num_thread 8 ``` ```bash API theme={"theme":{"light":"github-light","dark":"css-variables"}} curl http://localhost:11434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "llama3", "messages": [{"role": "user", "content": "Hello"}], "options": { "num_thread": 8 } }' ``` Vous pouvez aussi le définir globalement avec `OLLAMA_NUM_THREADS` : ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Linux (systemd) sudo systemctl edit ollama.service # Add: Environment="OLLAMA_NUM_THREADS=8" sudo systemctl daemon-reload && systemctl restart ollama ``` | Scenario | Thread guidance | | - | - | | Full GPU offload (all layers on GPU) | `num_thread 2` to `num_thread 4` — the CPU handles orchestration and tokenization, not math | | Partial GPU offload (some layers on CPU) | Set `num_thread` to the number of physical cores on your CPU — not hyperthreads | | CPU-only (no GPU) | Set `num_thread` to the number of physical cores | > [!WARNING] > > Plus de threads n'est pas toujours plus rapide. Au-delà du nombre de cœurs physiques, les threads se font concurrence pour le cache et la bande passante mémoire et peuvent ralentir l'inférence. En cas de doute, commencez avec le nombre de cœurs physiques et benchmarkéz à partir de là. Sur Apple Silicon, le réglage des threads importe moins car le GPU et le CPU partagent une mémoire unifiée et le backend MLX gère la planification. La valeur par défaut fonctionne généralement bien. ## Réglage de la taille de lot Le paramètre `num_batch` contrôle le nombre de tokens qu'Ollama traite à la fois pendant la phase de prefill (ingestion de l'invite). La valeur par défaut est 512. ```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}} FROM llama3 PARAMETER num_batch 1024 ``` | Setting | Effect | | - | - | | `num_batch 512` (default) | Balanced for interactive chat with short prompts | | `num_batch 1024` | Faster prefill for long prompts — roughly 50-100% faster time-to-first-token | | `num_batch 2048` | Maximum throughput for document ingestion — up to 150% faster prefill | | `num_batch 2048+` | Diminishing returns; higher memory usage without proportional speed gains | > [!TIP] > > Pour le chat interactif avec des invites courtes (moins de 1K tokens), la valeur par défaut `num_batch 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. > [!WARNING] > > Des tailles de lot plus grandes consomment plus de VRAM pendant l'ingestion des invites. Si vous augmentez `num_batch` et rencontrez des erreurs de mémoire, réduisez-la ou baissez `num_ctx`. ## Requêtes parallèles `OLLAMA_NUM_PARALLEL` contrôle le nombre de requêtes qu'un seul modèle traite simultanément. La valeur par défaut est 1 — Ollama gère une requête à la fois par modèle chargé. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Allow 4 parallel requests per model OLLAMA_NUM_PARALLEL=4 ``` | Value | Behavior | | - | - | | `1` (default) | One request at a time — lowest latency per request | | `2` to `4` | Multiple requests share the GPU — higher throughput, slightly higher per-request latency | | `8+` | Maximum throughput for batch workloads — requires significant VRAM for KV cache | > [!NOTE] > > La RAM et la VRAM évoluent avec `OLLAMA_NUM_PARALLEL`. Chaque requête parallèle a besoin de son propre cache KV. Si vous servez 4 requêtes parallèles avec `num_ctx 8192`, vous avez besoin de 4× la mémoire de cache KV par rapport à une seule requête. ### Quand augmenter les requêtes parallèles Augmentez `OLLAMA_NUM_PARALLEL` quand : * Vous servez plusieurs utilisateurs ou agents depuis le même modèle. * Vous exécutez des charges de travail par lots où le débit total compte plus que la latence de chaque requête. * Vous avez de la marge de VRAM et le GPU est sous-utilisé avec des requêtes simples. Gardez-la à 1 quand : * Vous servez un seul utilisateur ou agent. * Vous privilégiez une faible latence au débit. * La VRAM est limitée. ## Gestion de la mémoire des modèles ### Garder les modèles chargés avec `OLLAMA_KEEP_ALIVE` Par défaut, Ollama décharge un modèle de la mémoire après 5 minutes d'inactivité. La requête suivante doit recharger le modèle depuis le disque, ce qui prend de quelques secondes à quelques minutes selon la taille du modèle et la vitesse du disque. Définissez `OLLAMA_KEEP_ALIVE` pour contrôler la durée de chargement des modèles : ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Keep models loaded indefinitely OLLAMA_KEEP_ALIVE=-1 # Keep models loaded for 1 hour OLLAMA_KEEP_ALIVE=1h # Unload models immediately after each request OLLAMA_KEEP_ALIVE=0 ``` | Value | Behavior | | - | - | | `5m` (default) | Unload after 5 minutes of inactivity | | `-1` | Keep loaded indefinitely — no reload penalty | | `0` | Unload immediately after each request | | Duration (`1h`, `30m`, `24h`) | Keep loaded for that duration after the last request | > [!TIP] > > Pour un serveur d'inférence dédié qui exécute le même modèle toute la journée, définissez `OLLAMA_KEEP_ALIVE=-1`. Le modèle reste en mémoire et chaque requête obtient une réponse instantanée sans pénalité de démarrage à froid. ### Limiter les modèles chargés avec `OLLAMA_MAX_LOADED_MODELS` Ollama peut garder plusieurs modèles chargés simultanément. La valeur par défaut est 3 × (nombre de GPUs) ou 3 pour CPU uniquement. Si vous servez de nombreux modèles et voulez limiter l'utilisation de la mémoire, réduisez cette valeur : ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Only keep 1 model loaded at a time OLLAMA_MAX_LOADED_MODELS=1 ``` Quand la limite est atteinte et qu'un nouveau modèle est demandé, Ollama décharge le modèle le moins récemment utilisé pour faire de la place. ## Optimisation Apple Silicon et MLX À partir d'Ollama 0.19, le backend par défaut sur Apple Silicon est le framework MLX d'Apple. MLX est optimisé pour l'architecture de mémoire unifiée d'Apple et offre une inférence sensiblement plus rapide que llama.cpp sur les puces M-série. ### Gains de performance Benchmarks de la mise à jour d'optimisation MLX de juin 2026 d'Ollama : | Model | Quantization | Tokens/sec (MLX) | | - | - | - | | Gemma 4 12B | NVFP4 | \~55 tok/s | | Gemma 4 12B | Q4\_K\_M | \~46 tok/s | | Llama 3.1 8B | Q4\_K\_M | \~70-80 tok/s | MLX prend également en charge la quantification NVFP4 sur Apple Silicon, qui offre une qualité proche de BF16 avec une empreinte mémoire de 4 bits — la moitié de la perte de qualité de la quantification Q4. ### Conseils d'optimisation Apple Silicon 1. **Utilisez des modèles optimisés MLX.** Quand vous téléchargez un modèle sur Apple Silicon, Ollama utilise automatiquement le backend MLX. Aucune configuration nécessaire. 2. **La flash attention est toujours active.** MLX utilise des noyaux d'attention optimisés par défaut. La variable `OLLAMA_FLASH_ATTENTION` n'a aucun effet. 3. **La mémoire unifiée signifie un délestage GPU complet.** Le GPU d'Apple Silicon peut accéder à l'ensemble du pool de RAM, donc `-ngl 999` (toutes les couches sur GPU) fonctionne tant que le modèle et le cache KV tiennent dans la mémoire unifiée. 4. **Utilisez `OLLAMA_KV_CACHE_TYPE=q8_0`** pour étendre votre budget mémoire. Réduire de moitié le cache KV vous permet d'exécuter des modèles plus grands ou des contextes plus longs. 5. **Définissez `OLLAMA_KEEP_ALIVE=-1`** pour une inférence toujours active. Les modèles restent en mémoire unifiée sans pénalité de rechargement. > [!NOTE] > > Si vous avez besoin de portabilité multi-plateforme ou voulez exécuter la même configuration sur GPU NVIDIA et Mac, vous pouvez forcer Ollama à utiliser le backend llama.cpp sur Apple Silicon. Contactez le support Ollama ou consultez leur documentation pour la variable d'environnement permettant de remplacer la sélection du backend. ## Configurations exemples ### Mac Studio M2 Ultra — 128 GB unified memory ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Environment variables OLLAMA_FLASH_ATTENTION=1 OLLAMA_KV_CACHE_TYPE=q8_0 OLLAMA_KEEP_ALIVE=-1 OLLAMA_NUM_PARALLEL=4 ``` ```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}} FROM llama3.1:70b-q4_K_M PARAMETER num_ctx 32768 PARAMETER num_batch 1024 ``` Cette configuration exécute un modèle 70B Q4 avec une fenêtre de contexte de 32K. Le pool de mémoire unifiée de 128 Go gère les \~40 Go de poids du modèle, \~16 Go de cache KV en q8\_0, et laisse de la marge pour 4 requêtes parallèles. MLX offre un débit maximal sur Apple Silicon. ### NVIDIA RTX 4090 — 24 GB VRAM ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Environment variables OLLAMA_FLASH_ATTENTION=1 OLLAMA_KV_CACHE_TYPE=q8_0 OLLAMA_KEEP_ALIVE=-1 OLLAMA_NUM_PARALLEL=2 OLLAMA_NUM_THREADS=4 ``` ```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}} FROM llama3.1:8b-q4_K_M PARAMETER num_ctx 16384 PARAMETER num_batch 1024 ``` Cette configuration exécute un modèle 8B Q4 avec une fenêtre de contexte de 16K. Les 24 Go de VRAM gèrent les \~5 Go de poids du modèle, \~4 Go de cache KV en q8\_0 avec flash attention, et laissent de la marge pour 2 requêtes parallèles. Les 4 threads CPU gèrent l'orchestration et la tokenisation. ### Serveur multi-GPU — 4× RTX 4090 (96 GB total VRAM) ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Environment variables OLLAMA_FLASH_ATTENTION=1 OLLAMA_KV_CACHE_TYPE=q8_0 OLLAMA_KEEP_ALIVE=-1 OLLAMA_NUM_PARALLEL=8 OLLAMA_NUM_THREADS=8 ``` ```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}} FROM llama3.1:70b-q4_K_M PARAMETER num_ctx 8192 PARAMETER num_batch 2048 ``` Cette configuration exécute un modèle 70B Q4 sur 4 GPUs. Ollama distribue automatiquement les couches sur tous les GPUs disponibles. Les 96 Go de VRAM totale gèrent les \~40 Go de poids du modèle, \~16 Go de cache KV, et laissent de la marge pour 8 requêtes parallèles. La grande taille de lot maximise le débit pour les charges de travail par lots. ### Serveur CPU uniquement — 64 GB RAM, pas de GPU ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Environment variables OLLAMA_KEEP_ALIVE=-1 OLLAMA_NUM_PARALLEL=1 OLLAMA_NUM_THREADS=16 ``` ```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}} FROM llama3.1:8b-q4_K_M PARAMETER num_ctx 8192 PARAMETER num_batch 512 PARAMETER num_gpu 0 ``` Cette configuration exécute un modèle 8B Q4 entièrement sur CPU. Les 16 threads correspondent au nombre de cœurs physiques. La petite taille de lot et la requête parallèle unique gardent l'utilisation de la mémoire gérable. Attendez-vous à 5-10 tok/s — utilisable pour le chat interactif mais pas pour les charges de travail par lots. ### Traitement par lots à haut débit — RTX 4090 ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Environment variables OLLAMA_FLASH_ATTENTION=1 OLLAMA_KV_CACHE_TYPE=q4_0 OLLAMA_KEEP_ALIVE=-1 OLLAMA_NUM_PARALLEL=8 OLLAMA_NUM_THREADS=4 ``` ```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}} FROM llama3.1:8b-q4_K_M PARAMETER num_ctx 4096 PARAMETER num_batch 2048 ``` Cette configuration maximise le débit pour les charges de travail par lots hors ligne. Le cache KV q4\_0 réduit la mémoire au quart, permettant 8 requêtes parallèles dans 24 Go de VRAM. La grande taille de lot accélère l'ingestion des invites. Le contexte court de 4K garde le cache KV petit. Attendez-vous à 200-300 tokens totaux par seconde pour toutes les requêtes parallèles. ### Service interactif à faible latence — RTX 4090 ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Environment variables OLLAMA_FLASH_ATTENTION=1 OLLAMA_KV_CACHE_TYPE=q8_0 OLLAMA_KEEP_ALIVE=-1 OLLAMA_NUM_PARALLEL=1 OLLAMA_NUM_THREADS=4 ``` ```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}} FROM llama3.1:8b-q4_K_M PARAMETER num_ctx 8192 PARAMETER num_batch 512 ``` Cette configuration minimise la latence pour le chat interactif. Requête parallèle unique, cache KV q8\_0 pour la qualité, et taille de lot modérée. Attendez-vous à un temps jusqu'au premier token inférieur à 500ms et une vitesse de décodage de 50-70 tok/s. ## Erreurs courantes et comment les éviter ### Erreur 1 : Définir num\_ctx trop haut **Problème :** Vous avez défini `num_ctx 128000` « au cas où », mais vos invites font moins de 2K tokens. Vous venez de gaspiller 64 Go de mémoire de cache KV. **Solution :** Définissez `num_ctx` pour correspondre à votre charge de travail réelle. Si vos invites font moins de 4K tokens, utilisez `num_ctx 4096` ou `num_ctx 8192`. Vous pouvez toujours l'augmenter plus tard pour des requêtes spécifiques via l'API. ### Erreur 2 : Oublier la flash attention **Problème :** Vous utilisez 30-50% de VRAM en plus par rapport au nécessaire car la flash attention n'est pas activée. **Solution :** Définissez toujours `OLLAMA_FLASH_ATTENTION=1`. Il n'y a aucun inconvénient sur le matériel pris en charge. ### Erreur 3 : Ne pas contrôler le déchargement du modèle **Problème :** Vous relancez votre requête après une pause de 10 minutes, et la première requête prend 30 secondes car Ollama a rechargé le modèle depuis le disque. **Solution :** Définissez `OLLAMA_KEEP_ALIVE=-1` pour une inférence toujours active. Le modèle reste en mémoire et chaque requête obtient une réponse instantanée. ### Erreur 4 : Utiliser trop de threads sur GPU **Problème :** Vous avez défini `num_thread 32` sur un CPU à 32 threads, mais toutes les couches sont sur le GPU. Les threads supplémentaires se font concurrence pour le cache et ralentissent l'orchestration. **Solution :** Quand toutes les couches sont sur le GPU, utilisez `num_thread 2` à `num_thread 4`. Le CPU gère uniquement l'orchestration et la tokenisation, pas le calcul d'inférence. ### Erreur 5 : Ignorer la précision du cache KV **Problème :** Vous manquez de VRAM et Ollama délègue des couches au CPU, mais vous n'avez pas considéré que le cache KV utilise 2× plus de mémoire que nécessaire. **Solution :** Définissez `OLLAMA_KV_CACHE_TYPE=q8_0` pour réduire de moitié la mémoire du cache KV. C'est le meilleur équilibre entre qualité et économies de mémoire. ### Erreur 6 : Définir OLLAMA\_NUM\_PARALLEL trop haut **Problème :** Vous avez défini `OLLAMA_NUM_PARALLEL=16` sur un GPU de 24 Go, et maintenant chaque requête n'a que 1.5 Go de cache KV. Les requêtes échouent ou la qualité se dégrade. **Solution :** Calculez votre budget de cache KV : `(VRAM - model_weights) / num_parallel`. S'il reste moins de 1 Go par requête, réduisez `num_parallel` ou baissez `num_ctx`. ## Dépannage ### Ollama est lent après le démarrage **Cause :** Le modèle a été déchargé et a dû être rechargé depuis le disque. **Solution :** Définissez `OLLAMA_KEEP_ALIVE=-1` pour garder le modèle chargé indéfiniment. ### Erreurs de mémoire insuffisante **Cause :** Le modèle + le cache KV dépasse la VRAM ou la RAM disponible. **Solution :** Réduisez `num_ctx`, activez `OLLAMA_FLASH_ATTENTION=1`, définissez `OLLAMA_KV_CACHE_TYPE=q8_0`, ou utilisez une quantification plus petite. ### Le GPU n'est pas utilisé **Cause :** Ollama n'a pas détecté le GPU, ou la VRAM est trop petite même pour quelques couches. **Solution :** Vérifiez `ollama ps` pour voir si les couches sont sur le GPU. Pour les GPUs NVIDIA, assurez-vous que les pilotes NVIDIA et le toolkit CUDA sont installés. Pour les GPUs AMD, assurez-vous que ROCm est installé. ### Inférence CPU lente **Cause :** Trop de threads, ou des couches réparties entre GPU et CPU. **Solution :** Définissez `num_thread` au nombre de cœurs physiques. Si possible, délestez plus de couches sur le GPU avec `num_gpu`. Utilisez une quantification plus petite (Q4\_K\_M ou Q5\_K\_M) pour faire tenir plus de couches sur le GPU. ## Prochaines étapes > **[Ollama remote access](/fr/guides/ollama-remote-access.md)** > > Exposez votre modèle Ollama à vos coéquipiers et agents via Tokios — sans ouvrir de ports ni définir OLLAMA\_HOST=0.0.0.0. > **[Hardware reference](/fr/guides/hardware-reference.md)** > > Comparez les plateformes matérielles pour l'inférence LLM locale — spécifications, capacité de modèles et recommandations. > **[Model fit finder](/fr/guides/model-fit.md)** > > Trouvez quels modèles fonctionnent sur votre matériel, ou quel matériel peut exécuter votre modèle cible. > **[Test your deployment](/fr/guides/benchmark-your-deployment.md)** > > Mesurez la latence et le débit après réglage pour confirmer l'amélioration. ## Foire aux questions > **What is the best Ollama configuration for fast inference?** > > Activez la flash attention (`OLLAMA_FLASH_ATTENTION=1`), définissez la fenêtre de contexte selon les besoins réels de votre tâche (pas le maximum du modèle), utilisez un cache KV quantifié (`OLLAMA_KV_CACHE_TYPE=q8_0` ou `q4_0`) pour les contextes longs, et assurez-vous que votre modèle est entièrement délesté sur GPU. Voir les sections ci-dessus pour les commandes exactes. > **How do I reduce Ollama memory usage?** > > Les 3 plus gros leviers : (1) baissez `num_ctx` — la mémoire évolue linéairement avec la longueur du contexte, (2) quantifiez le cache KV avec `OLLAMA_KV_CACHE_TYPE=q4_0` pour jusqu'à 75% d'économie de cache KV, (3) utilisez une quantification plus petite des poids du modèle (par exemple, Q4\_0 au lieu de Q8\_0). La flash attention économise aussi 30-50% sur la mémoire d'attention. > **Does Ollama use MLX on Mac?** > > Oui — à partir d'Ollama 0.19, le backend par défaut sur Apple Silicon est le framework MLX d'Apple, pas llama.cpp. MLX offre une inférence sensiblement plus rapide sur les puces M-série (55-80 tok/s sur M2 Ultra vs 25-40 tok/s avec llama.cpp). La variable `OLLAMA_FLASH_ATTENTION` n'a aucun effet sur MLX car MLX utilise toujours des noyaux d'attention optimisés. > **How many parallel requests can Ollama handle?** > > Définissez `OLLAMA_NUM_PARALLEL` (par défaut 1). Chaque emplacement parallèle ajoute environ 20-30% de surcharge mémoire pour le cache KV. Pour un modèle 7B en Q4 avec un contexte de 8K, 4 emplacements parallèles tiennent confortablement dans 8 Go de VRAM. Pour des modèles plus grands ou des contextes plus longs, commencez avec 2 et mesurez. > **Why is Ollama slow to load my model?** > > Le temps de chargement du modèle est dominé par la lecture des poids depuis le disque et leur transfert vers le GPU. Utilisez un SSD NVMe (pas un HDD), définissez `OLLAMA_KEEP_ALIVE` pour garder le modèle chaud entre les requêtes, et définissez `OLLAMA_MAX_LOADED_MODELS` pour éviter l'éviction et le rechargement. Sur Apple Silicon, les modèles NVFP4 se chargent plus vite car les poids sont plus petits. > **What GPU offload settings should I use?** > > Par défaut, Ollama sélectionne automatiquement le nombre de couches à délester sur le GPU. Pour une vitesse maximale, définissez `num_gpu` au nombre total de couches du modèle (délestage complet). Si vous manquez de VRAM, réduisez `num_ctx` avant de réduire `num_gpu` — garder le modèle entièrement sur GPU est presque toujours plus rapide qu'un délestage partiel. ## Sources * [Ollama FAQ](https://docs.ollama.com/faq) — documentation officielle sur les variables d'environnement et la configuration * [Ollama Modelfile reference](https://docs.ollama.com/modelfile) — syntaxe des paramètres et valeurs valides * [Ollama MLX performance update](https://ollama.com/blog/mlx-performance) — benchmarks et optimisations de juin 2026 pour Apple Silicon * [Ollama GPU scheduling deep dive](https://eastondev.com/blog/en/posts/ai/ollama-gpu-scheduling/) — gestion de la VRAM et comportement multi-GPU * [Ollama performance tuning: batching, KV cache, and OOM](https://eastondev.com/blog/en/posts/ai/20260410-ollama-performance-optimization/) — benchmarks num\_batch et calculs de mémoire * [Ollama environment variables: complete reference](https://modelpiper.com/blog/ollama-environment-variables) — vérifié par rapport à la source v0.32.5 > [!NOTE] > > Après avoir modifié la configuration d'Ollama, ré-enregistrez votre déploiement Tokios pour que le connecteur récupère le nouveau point de terminaison upstream. Voir [Register Model](/fr/setup/register-model.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.