Ollama peut être appelé depuis un script, une application interne ou n8n via une API HTTP. La confusion fréquente consiste à traiter le serveur local comme une API cloud avec compte, historique et sécurité gérée. En local, vous appelez généralement http://localhost:11434/api. Une API cloud Ollama existe aussi dans la documentation, mais ses URLs, son authentification et ses modèles ne se confondent pas avec le service installé sur votre machine.
Repère documentaire : documentation officielle du fonctionnement présenté.
Ce guide documentaire décrit une procédure à vérifier sur votre installation ; nous ne présentons pas ces manipulations comme un test exécuté.
Préparer le modèle : pull et list
Avant de déboguer un prompt, vérifiez que le modèle est présent. Côté CLI, ollama pull llama3.2 télécharge un modèle et ollama list liste les modèles locaux. Côté HTTP, la documentation expose aussi des endpoints pour gérer les modèles. Si une requête generate échoue avec “model not found”, le problème n’est pas le JSON : il faut d’abord récupérer ou corriger le nom du modèle.
ollama pull llama3.2
ollama list
curl --max-time 120 http://localhost:11434/api/generate -H 'Content-Type: application/json' -d '{"model":"llama3.2","prompt":"Résume ce texte en 3 puces","stream":false}'Lire la réponse generate
/api/generate renvoie un champ response quand vous demandez une réponse complète avec stream:false. Ne cherchez pas message.content sur cet endpoint : ce champ appartient au format chat. Les métadonnées comme total_duration ou eval_count peuvent aider à diagnostiquer, mais la sortie texte principale est response.
Lire la réponse chat
/api/chat attend un tableau messages, chaque entrée ayant un rôle et un contenu. Avec stream:false, la réponse utile se trouve dans message.content. Ollama ne sauvegarde pas automatiquement votre conversation applicative : si vous voulez que le modèle tienne compte du tour précédent, vous devez renvoyer l’historique utile dans messages. L’historique complet n’est pas toujours souhaitable : tronquez ou résumez les anciens tours si le contexte devient trop long.
curl --max-time 120 http://localhost:11434/api/chat -H 'Content-Type: application/json' -d '{
"model":"llama3.2",
"stream":false,
"messages":[
{"role":"system","content":"Réponds en français, court."},
{"role":"user","content":"Explique le RAG en une phrase."}
]
}'Streaming : NDJSON, pas un unique JSON
Par défaut, plusieurs endpoints peuvent streamer. Le flux arrive alors sous forme de lignes JSON successives, souvent appelé NDJSON : une ligne partielle, puis une autre, jusqu’à done:true. Un parseur qui attend un seul objet JSON final va casser. Pour une intégration simple, mettez stream:false. Pour une UI temps réel, lisez ligne par ligne, concaténez response ou les fragments message.content, puis traitez le dernier objet comme signal de fin.
Timeouts et sécurité
Ajoutez --max-time à curl et des timeouts côté client applicatif. Une génération locale peut bloquer longtemps si le modèle est lourd, si le CPU prend le relais ou si la mémoire sature. Ne publiez pas le port sur Internet sans proxy, authentification, filtrage d’IP et logs maîtrisés. Modifier OLLAMA_HOST peut changer l’interface écoutée : utile en réseau interne, dangereux si fait sans pare-feu.
Débogage rapide
- Connexion refusée : service Ollama non démarré ou mauvais host.
- Modèle absent : lancer pull ou corriger le nom.
- JSON invalide : vérifier les guillemets et la syntaxe JSON ; le bon Content-Type ne répare pas un document mal formé.
- Réponse vide : distinguer
responsepour generate etmessage.contentpour chat. - Flux illisible : désactiver le streaming ou parser le NDJSON.
La règle de production est simple : un prototype local peut appeler Ollama directement ; une application exposée doit ajouter une couche de contrôle, limiter les prompts, journaliser sobrement et protéger le port.
Exemple de parse côté script
Pour /api/generate, votre code doit lire data["response"]. Pour /api/chat, il doit lire data["message"]["content"]. Cette différence évite beaucoup de bugs n8n ou Python où l’on croit recevoir une réponse vide. En streaming, lisez chaque ligne non vide, parsez le JSON de cette ligne, concaténez le fragment, puis arrêtez quand done vaut vrai.
Cloud ou local : contrat différent
Si vous passez à une API cloud, ne recyclez pas aveuglément la configuration locale. Il peut y avoir une clé API, des modèles nommés différemment, une facturation, des limites de débit, une politique de conservation et des URLs différentes. Gardez deux profils de configuration : OLLAMA_LOCAL_BASE_URL et OLLAMA_CLOUD_BASE_URL, plus les timeouts et modèles associés.
Erreur à éviter en agent
Un agent qui discute avec Ollama doit renvoyer les messages utiles à chaque tour. Ne supposez pas qu’Ollama garde l’état de conversation côté serveur. Stockez l’historique dans votre application, résumez-le quand il grossit et n’envoyez pas de secrets inutiles dans le prompt.
Test d’intégration minimal
Avant de brancher un agent ou un workflow, faites deux appels séparés : un generate sans streaming et un chat sans streaming. Vérifiez explicitement le champ lu dans chaque cas, puis activez seulement ensuite le streaming si l’interface en a besoin. Cette séquence isole les erreurs de modèle, de réseau et de parsing.
Champ de sortie attendu
Dans la fiche technique du workflow, écrivez noir sur blanc le champ consommé : response pour generate, message.content pour chat. Ce détail évite les intégrations qui affichent un objet complet ou une réponse vide.
Pour les bases : définition d’un modèle de langage.
