Bibliothèque Python Ollama : bien démarrer avec les LLM en local

Les API LLM dans le cloud sont puissantes, mais présentent des contreparties : facturation à l’usage, limites de taux, et incertitudes sur le lieu de traitement de vos données. Pour des développeurs qui manipulent des données sensibles ou qui expérimentent beaucoup, ces contraintes deviennent vite un frein.

C’est là que les approches "local‑first" se distinguent. La bibliothèque Python Ollama lève ces frictions en vous permettant d’exécuter des grands modèles de langage en local, tout en interagissant avec eux via un code Python clair et natif. Vous gardez ainsi la main sur les performances, les coûts et la confidentialité.

Dans cet article, je vous guide à travers l’API complète de la bibliothèque Python Ollama, de la génération de texte simple avec generate() jusqu’à l’appel d’outils et aux modèles de vision.

Je vous recommande également de consulter nos derniers tutoriels Ollama :

• Tutoriel Gemma 4 : créer un agent de code IA local avec Gradio et Ollama
• Tutoriel Qwen 3.5 Small Models : créez un générateur Vidéo‑vers‑Jeu avec Ollama
• Utiliser OpenClaw avec Ollama : créer un data analyst local
• Utiliser Claude Code avec les modèles locaux Ollama

Prérequis pour exécuter Ollama avec Python

Avant de commencer, assurez‑vous d’avoir la configuration suivante :

• Python 3.8 ou supérieur

• Ollama téléchargé depuis son site, installé et en cours d’exécution (ollama serve)

• Au moins un modèle récupéré (par ex. ollama pull llama3.2)

Ces prérequis sont essentiels, car le SDK Python n’est qu’un client ; l’inférence se fait dans le runtime Ollama. Si le runtime est indisponible ou si aucun modèle adapté n’est présent, les appels échoueront.

Vous pouvez aussi envisager d’utiliser Docker avec Ollama pour garantir la cohérence des versions.

Qu’est‑ce que la bibliothèque Python Ollama ?

La bibliothèque Python Ollama est le SDK officiel qui encapsule l’API REST d’Ollama dans une interface Pythonique et simple. Autrement dit, elle transforme des requêtes HTTP bas niveau et des charges utiles JSON en fonctions Python de haut niveau pour vous permettre de vous concentrer sur l’intention plutôt que sur le transport.

À mesure que votre application grandit, cette abstraction supprime la répétition dans la construction des requêtes, standardise le traitement des réponses et centralise la gestion des erreurs.

À titre de comparaison, une requête brute pourrait ressembler à ceci :

import requests

response = requests.post(
    "http://localhost:11434/api/generate",
    json={
        "model": "llama3.2",
        "prompt": "Explain recursion"
    }
)

Cela fonctionne, mais devient vite verbeux et source d’erreurs. Avec le SDK, la même tâche devient :

import ollama

response = ollama.generate(
    model='llama3.2',
    prompt='Explain recursion'
)

Comment la bibliothèque communique avec le serveur Ollama

Sous le capot, chaque appel du SDK devient une requête HTTP vers le serveur Ollama à l’adresse http://localhost:11434. Votre script Python agit comme un client, tandis que le runtime Ollama agit comme un serveur qui héberge et exécute les modèles.

Cette séparation est importante car elle permet d’exécuter le modèle comme un service dédié, d’optimiser la gestion des ressources (CPU/GPU) et d’autoriser plusieurs applications à partager la même instance de modèle.

Si vous devez vous connecter à une autre machine, vous pouvez configurer un client personnalisé :

from ollama import Client

client = Client(host='http://remote-server:11434')
response = client.generate(model='llama3.2', prompt='Hello')

Installer et configurer la bibliothèque

L’installation est simple et nécessite peu de dépendances :

pip install ollama

Après l’installation, il est recommandé de vérifier la connectivité en listant les modèles disponibles. 

Cela vous permet de confirmer que votre environnement Python, le SDK et le runtime Ollama sont bien connectés.

Pour cela, exécutez :

import ollama

print(ollama.list())

Générer du texte avec generate()

La fonction generate() est conçue pour des tâches sans état : chaque requête est traitée de manière indépendante, sans mémoire des interactions précédentes. C’est idéal pour des tâches comme la synthèse, la réécriture ou la génération de code.

En l’absence de contexte conservé, la qualité de la sortie dépend entièrement de la clarté du prompt.

Génération de texte basique

L’exemple suivant illustre le flux le plus simple : envoyer un prompt, recevoir une réponse et extraire le texte généré.

import ollama

response = ollama.generate(
    model='llama3.2',
    prompt='Write a Python docstring for a function that calculates factorial'
)

print(response['response'])

La réponse inclut également des métadonnées comme le temps d’exécution et les comptes de tokens, utiles pour optimiser les performances.

Personnaliser la sortie avec des paramètres

Le comportement de génération peut être ajusté via des paramètres d’échantillonnage, qui contrôlent la sélection des tokens par le modèle.

Des valeurs de température plus faibles produisent des sorties plus déterministes, tandis que des valeurs élevées introduisent davantage de variété. Vous pouvez utiliser des paramètres comme top_p et num_predict pour affiner la diversité et la longueur des sorties.

Voici quelques paramètres importants :

Voici un exemple utilisant les paramètres top_p, temperature et num_predict :

response = ollama.generate(
    model='llama3.2',
    prompt='Explain machine learning in one paragraph',
    options={
        'temperature': 0.2,
        'top_p': 0.9,
        'num_predict': 100
    }
)

Construire des conversations avec chat()

Contrairement à generate(), l’API chat() prend en charge des interactions avec état en travaillant sur une séquence de messages. Le modèle peut ainsi conserver le contexte sur plusieurs tours.

Chaque message inclut un rôle, tel que user, assistant ou system, qui structure la conversation.

Requêtes de chat à un seul tour

Même une interaction à un seul tour utilise le format message, ce qui prépare le terrain pour des conversations plus complexes.

response = ollama.chat(
    model='llama3.2',
    messages=[
        {'role': 'user', 'content': 'Explain Python decorators'}
    ]
)

print(response['message']['content'])

Conserver le contexte multi‑tours

Pour conserver le contexte, vous stockez et renvoyez explicitement l’historique complet de la conversation à chaque requête. Vous contrôlez ainsi précisément ce que le modèle "se souvient".

messages = [
    {'role': 'user', 'content': 'What is recursion?'}
]

response = ollama.chat(model='llama3.2', messages=messages)
messages.append(response['message'])

messages.append({'role': 'user', 'content': 'Give an example in Python'})
response = ollama.chat(model='llama3.2', messages=messages)

Façonner le comportement avec des prompts système

Un prompt système définit en amont le comportement du modèle : ton, contraintes, rôle, etc.

messages = [
    {'role': 'system', 'content': 'You are a strict Python code reviewer.'},
    {'role': 'user', 'content': 'Review this code: def add(a,b): return a+b'}
]

Streaming et prise en charge d’Async dans la bibliothèque Python Ollama

Pour les applications interactives, la réactivité compte autant que la justesse. Ollama prend en charge le streaming et l’exécution asynchrone pour améliorer les performances et l’expérience utilisateur.

Streaming de réponses en temps réel

Le streaming permet de traiter la sortie au fil de l’eau, sans attendre la réponse complète.

for chunk in ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'Write a story'}],
    stream=True
):
    print(chunk['message']['content'], end='', flush=True)

Utiliser AsyncClient pour les applications asynchrones

L’exécution asynchrone permet à votre application de traiter plusieurs requêtes en parallèle sans blocage. Vous devrez utiliser la bibliothèque asyncio de Python pour l’implémenter.

Voici un exemple :

import asyncio
from ollama import AsyncClient

async def main():
    client = AsyncClient()
    async for chunk in await client.chat(
        model='llama3.2',
        messages=[{'role': 'user', 'content': 'Explain async programming'}],
        stream=True
    ):
        print(chunk['message']['content'], end='')

asyncio.run(main())

Gérer les modèles Ollama depuis Python

Le SDK Ollama propose aussi des outils pour gérer les modèles par programme, très utiles dans des environnements automatisés.

Lister et inspecter les modèles locaux

Vous pouvez récupérer la liste des modèles disponibles et inspecter leurs propriétés, comme la taille et la configuration.

models = ollama.list()
print(models)

info = ollama.show('llama3.2')
print(info)

Télécharger et supprimer des modèles par programme

Les modèles peuvent être téléchargés ou supprimés directement depuis Python, ce qui facilite la gestion dynamique des dépendances.

ollama.pull('llama3.2')
ollama.delete('llama3.2')

Générer et utiliser des embeddings avec la bibliothèque Python Ollama

Les embeddings représentent le texte sous forme de vecteurs numériques capturant la sémantique. Ils permettent de comparer des textes selon leur similarité plutôt que leur formulation exacte.

Créer des embeddings de texte

L’exemple suivant convertit un texte en représentation vectorielle, exploitable pour la recherche ou le clustering.

response = ollama.embed(
    model='nomic-embed-text',
    input='Ollama is a local LLM runtime'
)

embedding = response['embeddings'][0]

Construire une recherche par similarité basique

Une fois les embeddings générés, la similarité peut être mesurée via la similarité cosinus, qui compare l’angle entre les vecteurs.

Voici un simple exemple de fonction de recherche :

import numpy as np

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

Appel d’outils et sorties structurées avec la bibliothèque Python Ollama

Pour des applications avancées, les modèles doivent souvent interagir avec des fonctions externes ou renvoyer des données structurées.

Mettre en œuvre l’appel d’outils avec des fonctions Python

L’appel d’outils permet au modèle d’invoquer des fonctions Python prédéfinies selon l’intention de l’utilisateur.

Créons une fonction qui utilise ces outils :

def get_weather(city: str) -> str:
    """Get current weather for a city"""
    return f"Weather in {city} is sunny"
response = ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'What is the weather in Paris?'}],
    tools=[get_weather]
)

Obtenir des réponses JSON structurées

Les sorties structurées garantissent des réponses cohérentes et lisibles par machine, comme du JSON.

response = ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'Review: Great product, 5 stars!'}],
    format='json'
)

Avancé : modèles de vision et Ollama Cloud en Python

Ollama prend en charge des modèles multimodaux et l’inférence dans le cloud pour des cas d’usage plus avancés.

Envoyer des images à des modèles de vision

Les modèles de vision traitent à la fois du texte et des images, pour des tâches comme la description d’image et l’analyse visuelle.

response = ollama.chat(
    model='llama3.2-vision',
    messages=[{
        'role': 'user',
        'content': 'Describe this image',
        'images': ['image.jpg']
    }]
)

Exécuter des modèles cloud depuis Python

Pour des modèles trop volumineux pour tourner en local, Ollama Cloud propose une inférence hébergée. Il vous faut vous connecter à Ollama Cloud.

ollama signin

Après connexion, vous pouvez dialoguer avec des modèles hébergés dans le cloud ainsi :

from ollama import Client
import os

ollama.chat(model='deepseek-v3.1:671b-cloud', messages=[...])

client = Client(
    host='https://ollama.com',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

Gestion des erreurs : les écueils les plus fréquents avec Ollama Python

Dans des applications réelles, gérer explicitement les erreurs évite les défaillances silencieuses et améliore la fiabilité.

Gérer les exceptions ResponseError

Le SDK Ollama lève des exceptions structurées pour les erreurs côté serveur, vous permettant d’inspecter la cause.

import ollama

try:
    ollama.generate(model='unknown', prompt='test')
except ollama.ResponseError as e:
    print(e.status_code, e.error)

Déboguer les problèmes de connexion et de modèles

Les problèmes courants incluent un serveur à l’arrêt, des modèles manquants, une mémoire insuffisante ou un dépassement de la limite de contexte.

• Serveur non lancé : démarrez avec ollama serve

• Modèle introuvable : exécutez ollama pull

• Mémoire insuffisante : utilisez des modèles plus petits ou la quantification

• Problèmes de contexte : ajustez num_ctx

num_ctx contrôle le nombre maximal de tokens que le modèle peut « voir » en une fois, y compris :

• votre prompt
• les instructions système
• l’historique de conversation
• les documents récupérés (RAG)
• et les tokens générés par le modèle

Bien gérer ce paramètre évite que le LLM tronque du contenu antérieur (souvent au début) ou perde silencieusement des consignes ou données importantes.

Conclusion

La bibliothèque Python Ollama offre une interface complète pour travailler avec des LLM locaux et cloud, de la génération de texte aux fonctionnalités avancées comme les embeddings, l’appel d’outils et les entrées multimodales. Les LLM deviennent un service local contre lequel vous pouvez écrire des scripts, tester et mettre à l’échelle comme n’importe quel autre composant de votre stack.

D’après mon expérience avec Ollama, c’est une bonne option quand on veut éviter les LLM cloud. Par exemple, je peux utiliser plus librement des modèles open source. Si vous cherchez aussi plus d’options pour passer d’un modèle à l’autre, Ollama est une excellente porte d’entrée.

Pour aller plus loin, je vous recommande notre cours Developing LLM Applications with LangChain ou la certification Associate AI Engineer for Developers.