FAQ Ollama
Ce chapitre condense les connaissances de dépannage dans un manuel de référence pratique : commencez par l'analyse des logs, effectuez un triage par symptôme, et couvre six grandes catégories de problèmes - VRAM insuffisante, échecs de téléchargement, conflits de ports, anomalies GPU, surcharge et compatibilité lors des mises à niveau.
La première étape universelle : vérifier d'abord les logs
Les messages d'erreur d'Ollama sont souvent très brefs ; la véritable cause racine est presque toujours écrite dans les logs.
| Environnement | Afficher la commande / l'emplacement |
|---|---|
| macOS | cat ~/.ollama/logs/server.log |
| Linux(systemd) | journalctl -u ollama --no-pager --follow --pager-end |
| Windows | %LOCALAPPDATA%\Ollama\server.log |
| Docker | docker logs <container_name> |
| Exécution manuelle du serveur | Les journaux sont affichés directement dans le terminal courant |
Lorsque les journaux par défaut manquent de détails, activez le mode débogage et redémarrez le service pour voir les processus clés tels que la découverte du GPU et l'estimation de la VRAM :
# 调试模式启动 OLLAMA_DEBUG=1 ollama serve
Lorsque vous rencontrez une anomalie, effectuez d'abord un diagnostic à l'aide du diagramme de navigation ci-dessous, puis passez à la section correspondante :
VRAM / Mémoire insuffisante (OOM)
Il s'agit du problème d'exécution le plus courant, se manifestant généralement par la disparition du processus en pleine génération, le blocage du système ou des échecs d'allocation mémoire dans les journaux.
| Symptôme | Cause | Contre-mesure |
|---|---|---|
| Processus tué lors du chargement d'un grand modèle | Mémoire physique insuffisante | Passez à un tag plus petit ; ou utilisez create pour quantifier et réduire la taille |
| Plantage pendant la génération | L'accumulation du contexte entraîne l'expansion du cache KV | Réduisez num_ctx ; activez Flash Attention et la quantification du cache KV |
| Défaillance collective lors de requêtes multiples | NUM_PARALLEL est trop grand, l'utilisation de la VRAM se multiplie | Remettez-le à 1, puis augmentez-le progressivement en observant ollama ps |
| Le modèle s'exécute mais est déchargé sur le CPU | La VRAM est légèrement inférieure à la quantité requise | Libérez la VRAM utilisée en arrière-plan ; descendez d'un niveau de taille de paramètres |
Le trio de commandes de diagnostic : ollama ps pour vérifier l'occupation du modèle et le ratio de répartition, nvidia-smi (ou rocm-smi) pour vérifier la VRAM en temps réel, et free -h pour vérifier la mémoire système.
Échecs de téléchargement de modèle et interruptions avec reprise
Les problèmes de téléchargement se situent presque toujours dans le chemin réseau ; la bonne nouvelle est qu'Ollama prend en charge les téléchargements reprenables couche par couche, ce qui rend les nouvelles tentatives très peu coûteuses.
| Symptôme | Cause | Contre-mesure |
|---|---|---|
| Téléchargements interrompus à plusieurs reprises | Réseau instable vers le serveur source | Réexécutez la même commande pour reprendre ; configurez HTTPS_PROXY si nécessaire |
| Échec persistant après la configuration du proxy | HTTP_PROXY a été défini par erreur | Conservez uniquement HTTPS_PROXY, supprimez HTTP_PROXY |
| Erreur de certificat du proxy | Le certificat auto-signé n'est pas approuvé | Installez le certificat CA comme certificat système |
| Avertissement d'espace disque insuffisant | La capacité de la partition cible est insuffisante | Libérez de l'espace, ou utilisez OLLAMA_MODELS pour migrer le chemin de stockage |
Conflits de ports et connexion refusée
Lorsque le client signale "connection refused", l'essentiel est qu'aucun service ne répond sur le port 11434.
| Symptôme | Cause | Contre-mesure |
|---|---|---|
| Connexion curl locale refusée | Le service Ollama n'est pas démarré | Ouvrez l'application sur macOS / Windows ; exécutez sudo systemctl start ollama sur Linux |
| Les journaux signalent que le port est déjà utilisé | 11434 est occupé par un autre programme | Arrêtez le processus qui l'occupe, ou démarrez sur un autre port : OLLAMA_HOST=127.0.0.1:11435 |
| Les machines distantes ne peuvent pas se connecter | Le service n'écoute que sur l'adresse de bouclage | Définissez OLLAMA_HOST=0.0.0.0 côté serveur et autorisez-le à travers le pare-feu |
| L'installation manuelle sous Linux s'arrête immédiatement après le démarrage | /tmp est monté avec noexec, la bibliothèque d'inférence ne peut pas être chargée | Définir OLLAMA_TMPDIR pour pointer vers un répertoire exécutable |
GPU non utilisé / Échec de découverte
Le symptôme est ollama ps affichant 100% CPU, ou des journaux montrant un échec de découverte du GPU. NVIDIA et AMD ont des chemins de dépannage différents.
Spécificités NVIDIA
Vérifiez d'abord le pilote et l'environnement de passthrough, puis traitez selon les codes d'erreur des journaux :
| Élément à vérifier | Méthode |
|---|---|
| Version du pilote | nvidia-smi s'exécute normalement ; mettez à niveau vers le dernier pilote |
| Passthrough de conteneur | Si docker run --gpus all ubuntu nvidia-smi échoue, il s'agit d'un problème de Container Toolkit |
| Anomalie du module de pilote | Rechargez avec sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm et réessayez |
| Échoue après une reprise depuis la suspension | Après la veille/réveil sous Linux, rechargez le module nvidia_uvm |
| Docker perd le GPU après une longue période d'exécution | Ajoutez native.cgroupdriver=cgroupfs à /etc/docker/daemon.json et redémarrez Docker |
Les codes d'erreur CUDA dans les journaux valent la peine d'être mémorisés : 3 signifie non initialisé, 46 signifie périphérique indisponible, 100 signifie aucun périphérique, 999 signifie erreur inconnue - la plupart pointent vers le pilote ou la configuration de passthrough.
Spécificités AMD
| Symptôme | Cause | Contre-mesure |
|---|---|---|
| Complètement non détecté sous Linux | L'utilisateur n'est pas dans le groupe video / render | Ajoutez l'utilisateur en cours d'exécution au groupe correspondant et redémarrez le service |
| Les journaux affichent un délai d'attente de découverte | Le pilote ROCm est trop ancien (inférieur à v7) | Mettez à niveau ROCm v7 avec amdgpu-install et redémarrez |
| Les anciennes cartes ne sont pas prises en charge | L'architecture ne figure pas dans la liste officielle des architectures prises en charge | Essayez HSA_OVERRIDE_GFX_VERSION pour spécifier une architecture similaire |
| Certaines cartes anciennes ne disposent pas de ROCm sous Windows | Limitation de la pile de pilotes | Utilisez le chemin Vulkan par défaut ; vérifiez GGML_VK_VISIBLE_DEVICES en cas d'anomalie |
Dépannage systématique des erreurs 503 de surcharge et des réponses lentes
Enchaînez les méthodes des chapitres précédents en une procédure fixe ; en six étapes, vous pouvez localiser la grande majorité des problèmes de performance :
Première étape, utilisez ollama ps pour confirmer si PROCESSOR est à 100 % GPU ; si un fractionnement apparaît, revenez d'abord à l'optimisation de la VRAM.
Deuxième étape, examinez les journaux à la recherche de traces de mise en file d'attente, de déchargement ou d'échecs de découverte.
Troisième étape, recevoir une erreur 503 signifie que la file d'attente est pleine ; vérifiez le volume de requêtes simultanées et OLLAMA_MAX_QUEUE, puis évaluez s'il faut monter en charge.
Quatrième étape, dans les scénarios partagés multi-utilisateurs, vérifiez la relation multiplicative entre OLLAMA_NUM_PARALLEL et la VRAM.
Cinquième étape, vérifiez la stratégie keep_alive : des déchargements et rechargements fréquents feront grimper en flèche la latence du premier token.
Étape six, utilisez le champ usage de l'API pour calculer les tokens/s, et comparez avec la référence historique afin de quantifier l'effet de chaque ajustement.
Problèmes de compatibilité après mise à niveau et retour arrière
Lorsque le comportement est anormal après une mise à niveau, trois actions résolvent la plupart des cas :
# 1. Linux 手动升级前先清理旧库,避免新旧混用 sudo rm -rf /usr/lib/ollama # 2. 回退到指定版本 curl -fsSL https://ollama.com/install.sh | OLLAMA_VERSION=0.5.7 sh # 3. AMD 显卡同步升级 ROCm v7 驱动后重启
Les blocs illisibles qui apparaissent dans le terminal Windows sont un ancien problème de police de terminal, sans rapport avec le modèle ; il suffit de passer à Windows Terminal.
Autres extensions