Vous avez déjà un script Python et Ollama fonctionne sur votre machine, mais vous cherchez comment envoyer un message, afficher la réponse au fil de sa génération et éviter qu’une panne arrête tout le programme. La bibliothèque officielle ollama fournit ces briques directement, avec une interface synchrone et une variante asynchrone.
Quelle bibliothèque Python choisir pour appeler Ollama ?
Pour relier votre programme à l’intelligence artificielle, partez du paquet officiel ollama plutôt que de fabriquer une requête HTTP à la main. La bibliothèque cible les projets Python 3.8 ou plus récent. Elle suppose qu’Ollama est installé et lancé, et qu’un modèle utilisable est disponible. Son dépôt officiel documente l’installation avec pip install ollama ainsi que les appels de chat. (github.com)
Cette bibliothèque est le bon choix si vous voulez manipuler des messages et récupérer une réponse sous forme d’objet Python. Le client HTTP direct reste une autre option, plus bas niveau, qui vous oblige à gérer vous-même le format des échanges. Le SDK conserve une interface proche de l’API Ollama, mais vous n’avez pas à coder le décodage de chaque réponse. Pour les détails de l’interface HTTP, consultez les appels à l’API Ollama dans la partie qui lui est consacrée.
Comment envoyer un premier message avec chat ?
Installez le paquet dans le même environnement Python que celui qui exécutera votre script. Si vous utilisez un environnement virtuel, activez-le avant l’installation : cela évite d’installer ollama dans un autre interpréteur que celui du projet.
python -m pip install ollama
La fonction chat reçoit un nom de modèle et une liste messages. Chaque message associe un rôle, par exemple user pour la demande, à un contenu textuel. Ce format permet de transmettre plusieurs tours de conversation ; il ne faut donc pas envoyer seulement une chaîne quand l’interface attend une liste de messages.
from ollama import chat
response = chat(
model="gemma4",
messages=[
{"role": "user", "content": "Propose un nom pour un serveur Minecraft."}
],
)
print(response.message.content)
L’exemple utilise gemma4, comme l’exemple de la documentation de la bibliothèque ; remplacez ce nom par celui du modèle effectivement disponible chez vous. Sans stream=True, l’appel attend la réponse complète et renvoie un objet de réponse. Le texte généré se trouve dans response.message.content. Le SDK autorise aussi l’accès de type dictionnaire, mais garder l’accès par attribut rend le code lisible et cohérent avec ses types de réponse.
Faut-il utiliser le client, le mode asynchrone ou le cloud ?
Pour un petit script lancé de manière séquentielle, chat(...) suffit. Si vous devez configurer explicitement l’hôte ou réutiliser un client dans plusieurs fonctions, créez un Client : il accepte un hôte, et les options supplémentaires sont transmises au client HTTP sous-jacent. Pour une application qui doit attendre plusieurs opérations réseau sans bloquer sa boucle d’événements, Ollama propose aussi AsyncClient avec await.
Le critère principal n’est donc pas une différence de syntaxe pour obtenir le texte, mais le modèle d’exécution de votre application. Un script de console peut rester synchrone ; une application asynchrone devrait éviter de bloquer sa boucle avec un appel synchrone. Enfin, le SDK peut aussi pointer vers Ollama Cloud : cette option déplace l’exécution du modèle vers le service distant, au lieu de la faire tourner sur votre ordinateur. Les conditions de connexion et d’authentification diffèrent alors du mode local ; Ollama Cloud est une piste si la puissance de votre machine est le facteur limitant.
Comment afficher la réponse au fil de sa génération ?
Le streaming affiche des fragments dès qu’ils sont produits, ce qui donne un retour visuel plus rapide qu’une attente jusqu’à la fin. Il est désactivé par défaut dans les SDK : passez explicitement stream=True, puis parcourez le résultat. La documentation officielle décrit ces fragments comme des parties du message de l’assistant à afficher ou à accumuler. (github.com)
from ollama import chat
stream = chat(
model="gemma4",
messages=[{"role": "user", "content": "Explique le ray tracing en deux phrases."}],
stream=True,
)
texte_complet = []
for fragment in stream:
morceau = fragment.message.content or ""
print(morceau, end="", flush=True)
texte_complet.append(morceau)
print()
reponse_complete = "".join(texte_complet)
flush=True demande à Python d’écrire aussitôt le fragment dans la sortie, au lieu d’attendre que le tampon soit rempli. L’accumulation dans une liste permet de reconstituer ensuite la réponse complète sans multiplier les concaténations de chaînes dans la boucle.
Le contenu d’un fragment peut être vide : le flux peut aussi transporter des informations qui ne sont pas du texte à afficher. Si vous activez des fonctions ou des outils, ne supposez pas que chaque fragment est un morceau visible de la réponse. Pour poursuivre une conversation, conservez les messages nécessaires et ajoutez les sorties d’outils au bon rôle ; le flux est une suite d’éléments, pas une simple chaîne.
Comment traiter les erreurs sans masquer leur cause ?
Interceptez ollama.ResponseError autour de l’appel, y compris autour de la boucle de streaming. La bibliothèque indique que les erreurs de statut et celles détectées pendant le flux sont levées sous forme d’exception. Vous pouvez examiner error pour le texte explicatif et status_code quand un code de statut est disponible.
import ollama
try:
response = ollama.chat(
model="gemma4",
messages=[{"role": "user", "content": "Donne une idée de construction Minecraft."}],
)
except ollama.ResponseError as exc:
print(f"Erreur Ollama ({exc.status_code}) : {exc.error}")
Ne traitez pas toutes les erreurs comme si elles indiquaient la même panne. La documentation de l’API donne les statuts courants : 200 signifie une réussite, 400 signale notamment une requête invalide, 404 une ressource ou un modèle introuvable, 429 une limite de requêtes, 500 une erreur interne et 502 un problème de passerelle, par exemple lorsqu’un modèle cloud n’est pas joignable. Ce sont des indications de diagnostic, pas une garantie que chaque appel renverra l’un de ces codes. (github.com)
Pour une erreur 404, vérifiez d’abord le nom du modèle et sa disponibilité. Pour un 400, inspectez les champs envoyés et le contenu des messages. Pour une erreur de connexion, vérifiez que le service Ollama est lancé et accessible depuis le processus Python. Évitez de relancer indéfiniment une requête invalide ; une nouvelle tentative est surtout pertinente pour une panne temporaire, avec une limite et un délai d’attente adaptés à votre application.
En streaming, une erreur peut arriver après l’envoi de premiers fragments. Votre terminal peut donc afficher un début de réponse sans que la génération soit complète. La documentation des erreurs précise qu’une erreur en cours de flux apparaît dans le flux lui-même et ne modifie pas le statut HTTP déjà envoyé. En pratique, traitez l’exception, signalez que la sortie est incomplète et ne sauvegardez pas silencieusement le texte partiel comme résultat final.
Comment vérifier que l’appel Python fonctionne ?
Faites un test minimal avant d’intégrer l’appel dans une interface ou un bot. Vérifiez d’abord que l’import réussit dans l’environnement actif, puis que le nom passé à model correspond bien au modèle présent. Lancez une requête courte en mode non-streaming : vous isolez ainsi les problèmes d’installation, de connexion et de disponibilité du modèle avant d’ajouter la gestion des fragments.
Pour tester ensuite le streaming, reprenez la même demande avec stream=True. Le texte doit apparaître par morceaux et la boucle doit se terminer normalement. Comparez reponse_complete au texte affiché, et prévoyez un traitement d’exception autour de l’itération. Si le programme se bloque, examinez si le service est joignable ; si l’exception indique un modèle absent, corrigez son identifiant plutôt que de modifier le prompt. Ce découpage transforme un diagnostic vague en vérifications reproductibles.
Questions fréquentes
Faut-il appeler l’API HTTP directement pour utiliser Ollama avec Python ?
Non. La bibliothèque officielle ollama enveloppe les appels et renvoie des objets Python, ce qui évite de construire manuellement la requête HTTP et de décoder chaque réponse. Un appel HTTP direct peut rester utile si votre application a des besoins particuliers ou si vous utilisez un autre langage. Pour un script Python classique, commencez par la bibliothèque officielle.
Pourquoi mon script reçoit-il une erreur 404 ?
Une erreur 404 indique notamment que le modèle demandé est introuvable. Vérifiez que le nom passé à model correspond exactement à un modèle disponible dans votre installation et que le modèle a été récupéré. L’exception ResponseError expose son code dans status_code et son message dans error : affichez-les pour distinguer ce cas d’une erreur de connexion.
Le streaming est-il activé automatiquement avec la bibliothèque Python ?
Non. Dans les SDK Ollama, le streaming est désactivé par défaut ; vous devez passer stream=True à chat. La fonction renvoie alors un itérateur de fragments et non une réponse complète immédiate. Parcourez cet itérateur pour afficher le texte progressivement, puis conservez les fragments utiles si vous devez enregistrer la réponse entière.
