Manuel complet des commandes Ollama
Ce chapitre présente les commandes d'utilisation d'Ollama, couvrant l'installation, la gestion des modèles, les paramètres d'exécution, le Modelfile, l'API REST, les variables d'environnement et le dépannage courant. Tout le contenu est basé sur Ollama 0.17.x.
Installation et démarrage
Les trois plateformes disposent de méthodes d'installation standard. Après l'installation, Ollama s'exécute automatiquement en tant que service en arrière-plan, à l'écoute sur127.0.0.1:11434。
| Plateforme | Méthode d'installation | Description |
|---|---|---|
| macOS | brew install ollama | Vous pouvez également télécharger l'installateur DMG depuis le site officiel. |
| Linux | curl -fsSL https://ollama.com/install.sh | sh | Script officiel en un clic qui configure automatiquement le service systemd. |
| Windows | Télécharger l'installateur depuis le site officiel. | Installer via l'assistant ; s'enregistre automatiquement en tant que service système. |
| Docker | docker run -d -v ollama:/root/.ollama -p 11434:11434 ollama/ollama | Le volume de données ollama conserve les modèles. |
Dans la plupart des cas, vous n'avez pas besoin de démarrer le service manuellement, mais cela est utile pour le dépannage ou la modification temporaire de la configuration.ollama serve。
Exemple
ollama serve
# Vérifier que le service est prêt : il est normal qu'il retourne "Ollama is running"
curl http://localhost:11434
Si un message d'occupation de port apparaît, le service en arrière-plan est déjà en cours d'exécution. L'exécution de `ollama serve` dans un autre terminal signalera alors une erreur, ce qui est normal. Utilisez simplement la ligne de commande ou l'API directement.
Tableau complet des commandes de gestion des modèles
La gestion des modèles est la partie principale de la ligne de commande Ollama, avec environ dix commandes, toutes répertoriées dans le tableau ci-dessous.
| Commande | Fonction | Exemple |
|---|---|---|
| ollama pull <model> | Télécharger un modèle depuis la bibliothèque de modèles ; si aucun tag n'est donné, la valeur par défaut est `latest`. | ollama pull qwen3.5:4b |
| ollama run <model> | Exécuter un modèle de manière interactive ; s'il n'est pas disponible localement, il sera automatiquement récupéré. | ollama run qwen3.5 |
| ollama list / ollama ls | Lister les modèles locaux, leurs tailles et leurs dates de modification. | ollama list |
| ollama show <model> | Afficher les détails du modèle : paramètres, gabarit, prompt système, etc. | ollama show qwen3.5 |
| ollama ps | Afficher les modèles chargés en mémoire et leur durée de vie restante. | ollama ps |
| ollama stop <model> | Arrêter et décharger immédiatement un modèle en cours d'exécution. | ollama stop qwen3.5 |
| ollama cp <src> <dst> | Copier ou renommer un modèle. | ollama cp qwen3.5 example-clone |
| ollama rm <model> | Supprimer un modèle local pour libérer de l'espace disque. | ollama rm qwen3.5:0.8b |
| ollama create <name> -f <file> | Créer un modèle personnalisé à partir d'un Modelfile. | ollama create example-coder -f Modelfile |
| ollama push <model> | Pousser un modèle vers une bibliothèque de modèles distante ; une connexion est requise au préalable. | ollama push myteam/example-coder |
| ollama serve | Démarrer le service en arrière-plan ; il s'exécute généralement automatiquement avec le système. | ollama serve |
La combinaison la plus fréquemment utilisée dans le travail quotidien est `run`, `list`, `ps` et `rm` : exécuter des modèles, vérifier l'inventaire, inspecter la mémoire et libérer de l'espace.
Exemple
ollama pull qwen3.5:0.8b
# Faire une copie et lui donner votre propre nom
ollama cp qwen3.5 example-clone
# Après avoir confirmé que la copie a réussi, supprimez la taille qui n'est plus nécessaire
ollama rm qwen3.5:0.8b
`rm` supprime les fichiers de modèle correspondant à ce tag. Si d'autres tags partagent les mêmes poids sous-jacents (blobs), l'espace disque n'est entièrement libéré qu'après la suppression du dernier tag qui les référence.
Commande run et mode interactif
`run` peut être utilisé comme un outil de questions-réponses ponctuel, peut entrer en mode interactif pour des conversations à plusieurs tours, et prend également en charge la modification des paramètres à l'exécution.
Arguments de ligne de commande
Les arguments sont écrits après le nom du modèle ; ils ne prennent effet que pour l'exécution en cours et ne sont pas écrits dans la configuration du modèle.
Exemple
ollama run qwen3.5
# Questions-réponses en une seule fois : le prompt suit le nom du modèle ; quitte automatiquement après avoir répondu
ollama run qwen3.5 "Présentez Python en une phrase."
# Afficher les statistiques de tokens : temps total, tokens par seconde et autres indicateurs de performance
ollama run qwen3.5 --verbose
# Forcer le modèle à générer une sortie au format JSON
ollama run qwen3.5 --format json
# Augmenter la fenêtre de contexte (unité : tokens)
ollama run qwen3.5 --num-ctx 8192
# Placer autant de couches du modèle que possible sur le GPU (999 signifie aucune limite)
ollama run qwen3.5 --num-gpu 999
Commandes slash en mode interactif
Après être entré en mode interactif, les commandes commençant par une barre oblique ajustent l'état de la session ; ces ajustements ne prennent effet que pour la session en cours.
| Commande | Fonction |
|---|---|
| /set parameter <name> <value> | Ajuster temporairement les paramètres d'inférence, tels que `temperature`. |
| /set system <prompt> | Définir temporairement le prompt système. |
| /show info | Afficher des informations sur le modèle actuel. |
| /show modelfile | Afficher le Modelfile correspondant au modèle actuel. |
| /save <name> | Enregistrer les paramètres de la session actuelle en tant que nouveau modèle. |
| /load <name> | Charger un modèle ou une session enregistrés. |
| /clear | Effacer le contexte de conversation actuel et recommencer. |
| /bye | Quitter le mode interactif. |
Si vous souhaitez conserver à long terme les paramètres définis via des commandes slash, utilisez `/save` pour les enregistrer en tant que nouveau modèle ; en arrière-plan, cela génère un Modelfile pour vous.
Un autre raccourci pour quitter le mode interactif consiste à appuyer sur Ctrl+D, ce qui a le même effet que `/bye`.
Modèles personnalisés avec Modelfile
Modelfile utilise une syntaxe de type Dockerfile pour empaqueter un « modèle de base + paramètres + prompt système » en un nouveau modèle.
Exemple
# FROM spécifie le modèle de base (obligatoire) ; il peut aussi s'agir d'un chemin de fichier GGUF local
FROM qwen3.5
# Paramètres d’inférence courants (facultatifs)
PARAMETER temperature 0.2
PARAMETER num_ctx 8192
# Prompt système ; détermine le rôle et le comportement du modèle (facultatif)
SYSTEM Vous êtes un ingénieur Python senior. Produisez du code concis, testable et annoté avec des types.
Exemple
ollama create example-coder -f Modelfile
# L'exécuter comme un modèle classique
ollama run example-coder "Écrivez un tri rapide, y compris les tests."
Pour importer des poids GGUF locaux, pointez simplement FROM vers le chemin du fichier ; c'est couramment utilisé pour exécuter des fichiers de modèle téléchargés depuis la communauté open source.
Exemple
# FROM pointe vers un fichier de poids GGUF local
FROM ./model-file.gguf
Toutes les directives Modelfile sont répertoriées dans le tableau ci-dessous ; les trois premières lignes constituent la combinaison la plus couramment utilisée.
| Directive | Objectif | Requis |
|---|---|---|
| FROM | Spécifiez le modèle de base ou le chemin du fichier GGUF. | Requis |
| PARAMETER | Définir les paramètres d'inférence : temperature, num_ctx, top_p, stop, etc. | Optional |
| SYSTÈME | Définir le prompt système. | Optional |
| TEMPLATE | Personnaliser le modèle de prompt de conversation. | Optional |
| ADAPTER | Charger un adaptateur LoRA. | Optional |
| MESSAGE | Exemples de conversation prédéfinis pour mettre en œuvre un guidage few-shot. | Optional |
| LICENSE | Déclarer la licence du modèle. | Optional |
Si vous souhaitez modifier un modèle existant et que vous ne voulez pas partir de zéro, exécutez d'abordollama show --modelfile 模型名pour exporter la recette complète ; après modification, exécutez `create` à nouveau.
Référence rapide de l'API REST
Après le démarrage du service Ollama, il écoute par défaut surhttp://localhost:11434, et tout ce que la CLI peut faire, l'API peut aussi le faire.
| Point de terminaison | Méthode | Fonction |
|---|---|---|
| /api/generate | POST | Génération de texte à tour unique ; renvoie sous forme de flux par défaut. |
| /api/chat | POST | Conversation multi-tours ; transmettez l'historique via le tableau `messages`. |
| /api/embed | POST | Générer des embeddings vectoriels de texte pour la récupération RAG. |
| /api/tags | GET | Lister les modèles locaux ; correspond à `ollama list`. |
| /api/show | POST | Afficher les détails du modèle ; correspond à `ollama show`. |
| /api/pull | POST | Récupérer un modèle ; correspond à `ollama pull`. |
| /api/delete | DELETE | Supprimer un modèle ; correspond à `ollama rm`. |
Exemple
curl http://localhost:11434/api/generate -d '{
"model": "qwen3.5",
"prompt": "Écrire un Hello World en Python"
}'
# Conversation multi-tours
curl http://localhost:11434/api/chat -d '{
"model": "qwen3.5",
"messages": [{"role": "user", "content": "Expliquez ce qu'est une API REST."}]
}'
# Générer des embeddings vectoriels
curl http://localhost:11434/api/embed -d '{
"model": "nomic-embed-text",
"input": "Votre contenu texte"
}'
# Lister les modèles locaux
curl http://localhost:11434/api/tags
# Afficher les détails du modèle
curl http://localhost:11434/api/show -d '{"model": "qwen3.5"}'
# Supprimer le modèle
curl -X DELETE http://localhost:11434/api/delete -d '{"model": "qwen3.5"}'
Interface compatible OpenAI
Ollama fournit un point de terminaison compatible OpenAI./v1/chat/completions, le code existant de l'écosystème OpenAI peut être utilisé directement en pointant base_url vers une instance locale.
Exemple
from openai import OpenAI
# base_url pointe vers Ollama local ; api_key peut être n'importe quelle chaîne non vide
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
resp = client.chat.completions.create(
model="qwen3.5", # Nom du modèle téléchargé localement
messages=[{"role": "user", "content": "Bonjour, veuillez présenter un exemple"}],
)
print(resp.choices[0].message.content)
$ python3 openai_compat.py 你好!example(Example)是一个面向初学者的编程学习网站,提供大量免费的基础技术教程。
Référence rapide des variables d'environnement
Les variables d'environnement sont le principal moyen de configurer le comportement du service Ollama. Les modifications ne prennent effet qu'après le redémarrage du service.
| Variable | Description | Valeur par défaut |
|---|---|---|
| OLLAMA_HOST | Adresse d'écoute du service ; 0.0.0.0 permet l'accès au réseau local | 127.0.0.1:11434 |
| OLLAMA_MODELS | Chemin de stockage des modèles ; couramment utilisé lors du passage à un disque plus grand | ~/.ollama/models |
| OLLAMA_NUM_GPU | Nombre de couches de modèle placées dans le GPU ; 999 signifie toutes | Auto |
| OLLAMA_NUM_PARALLEL | Nombre de requêtes simultanées pour le même modèle | Auto |
| OLLAMA_MAX_LOADED_MODELS | Nombre maximal de modèles résidents en mémoire en même temps | Auto |
| OLLAMA_FLASH_ATTENTION | Activer Flash Attention ; recommandé pour les contextes longs | Désactivé |
| OLLAMA_KEEP_ALIVE | Durée pendant laquelle un modèle reste inactif avant d'être déchargé de la mémoire | 5m |
| OLLAMA_DEBUG | Activer les journaux de débogage pour produire des informations d'exécution plus détaillées | Désactivé |
Exemple
export OLLAMA_HOST=0.0.0.0:11434
export OLLAMA_MODELS=/data/ollama-models
ollama serve
Définir OLLAMA_KEEP_ALIVE sur 0 décharge le modèle immédiatement après chaque requête, ce qui économise de la mémoire mais le recharge à chaque requête ; définissez-le sur -1 pour le garder résident. La syntaxe de cette valeur varie selon la version ; reportez-vous à `ollama serve --help` et à la documentation officielle.
Dépannage courant
Lorsque vous rencontrez des erreurs, utilisez d'abord le tableau ci-dessous pour localiser le problème. La plupart des problèmes relèvent de trois catégories : nom de modèle incorrect, service non démarré ou ressources insuffisantes.
| Problème | Démarche de dépannage |
|---|---|
| VRAM / mémoire insuffisantes (OOM) | Passez à une taille de modèle plus petite ou à une précision de quantification inférieure, par ex. utilisez 4b au lieu de 9b |
| L'erreur indique que le modèle est introuvable | Vérifiez si le nom du modèle et le tag sont corrects. Les tags sont séparés par un deux-points, par ex. qwen3.5:4b, et non qwen3.5-4b. |
| connexion refusée | Vérifiez si le service est en cours d'exécution et si le port 11434 est occupé. |
| Réponse lente | Utilisez `ollama ps` pour vérifier la colonne PROCESSOR et confirmer si le modèle s'exécute réellement sur le GPU ; réduisez de manière appropriée num_ctx. |
| Confusion entre plusieurs versions de modèle | Lorsqu'aucun tag n'est spécifié, la version "latest" est sélectionnée selon des règles internes ; il est recommandé de toujours spécifier explicitement le tag complet. |
Aide-mémoire de référence rapide
Enfin, les commandes les plus fréquemment utilisées sont condensées dans un tableau, prêt à être copié et utilisé.
| Commande | Fonction |
|---|---|
| ollama pull <model> | Télécharger le modèle |
| ollama run <model> | Exécuter le modèle / entrer en conversation interactive |
| ollama list | Afficher les modèles téléchargés |
| ollama show <model> | Afficher les détails du modèle |
| ollama ps | Afficher les modèles en cours d'exécution |
| ollama stop <model> | Arrêter et décharger le modèle |
| ollama rm <model> | Supprimer le modèle |
| ollama cp <old> <new> | Copier / renommer le modèle |
| ollama create <name> -f Modelfile | Créer un modèle personnalisé à l'aide d'un Modelfile |
| ollama serve | Démarrer le service |
Autres extensionsOllama évolue rapidement, et certains paramètres et comportements de commandes peuvent changer selon les versions. Avant d'agir, consultez `ollama --help` et la documentation officielle.