API Ollama en Python et une alternative hébergée

Le résumé

Si vous recherchez ollama api python, vous voulez généralement l’une des trois choses suivantes : appeler un modèle s’exécutant sur votre propre machine, diffuser des tokens à partir de celui-ci, ou faire fonctionner le même script ailleurs. Ollama vous offre ces trois possibilités. Il exécute un serveur local, par défaut à l’adresse http://localhost:11434, et vous pouvez lui parler via le package Python ollama, avec du HTTP brut, ou avec n’importe quel client OpenAI pointant vers son chemin /v1.

Le hic est que le modèle doit s’exécuter sur votre matériel. Un ordinateur portable sans GPU décent sera lent avec des modèles plus grands, et un serveur sans GPU est mal adapté. Dans ce cas, une API compatible OpenAI hébergée est la solution plus simple, et comme le format de requête est identique, le changement ne vous coûte que trois lignes de configuration. Les deux méthodes sont couvertes ci-dessous, avec du code que vous pouvez coller.

Appeler un modèle local avec le package ollama

Installez Ollama, récupérez un modèle et assurez-vous que le serveur est en cours d’exécution. Puis installez le client Python :

Copypip install ollama
ollama pull llama3.2

Un appel de conversation basique ressemble à ceci. Le nom du modèle est celui que vous avez récupéré ; llama3.2 n’est qu’un exemple.

Copyimport ollama

response = ollama.chat(
    model="llama3.2",
    messages=[{"role": "user", "content": "Explain DNS in two sentences."}],
)
print(response["message"]["content"])

Diffusion en continu

Passez stream=True et vous obtenez un itérateur de fragments au lieu d’une seule réponse. Chaque fragment contient une partie de la réponse dans message.content.

Copyimport ollama

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

Pointer le client vers une autre machine

Si Ollama s'exécute sur un hôte différent, créez un client avec une adresse explicite, par exemple ollama.Client(host="http://192.168.1.20:11434"). Par défaut, le serveur n'écoute que sur la machine locale, donc l'accès distant nécessite un paramètre délibéré du côté du serveur. Ne l'exposez pas à Internet sans un proxy et une authentification devant, car l'API native n'a pas sa propre vérification de clé.

HTTP brut avec requests

Vous n’avez pas besoin du package du tout. L’endpoint de chat natif est POST /api/chat. Le streaming y est activé par défaut, et le flux est du JSON par ligne, et non du SSE. Définissez "stream": false si vous souhaitez recevoir un objet unique.

Copyimport requests

r = requests.post(
    "http://localhost:11434/api/chat",
    json={
        "model": "llama3.2",
        "messages": [{"role": "user", "content": "Name three HTTP status codes."}],
        "stream": False,
    },
    timeout=120,
)
r.raise_for_status()
print(r.json()["message"]["content"])

Définissez un délai d’attente élevé. La première requête après un pull doit charger le modèle en mémoire, ce qui peut prendre beaucoup plus de temps que les requêtes suivantes.

Lire le flux manuellement ne prend que quelques lignes de plus. Appelez requests.post(..., stream=True), parcourez r.iter_lines(), sautez les lignes vides et exécutez json.loads sur chacune. Chaque objet contient une petite partie de la réponse, et le dernier contient "done": true. C’est pratique dans un conteneur minimal où vous préférez ne pas installer un autre package, et cela montre clairement ce que la bibliothèque fait pour vous. L’API hébergée utilise un format de streaming différent, sous forme de lignes SSE commençant par data:, ce qui est une bonne raison de laisser le SDK OpenAI analyser le streaming pour vous dans du code portable.

Utilisation du SDK OpenAI avec Ollama

Ollama expose également un endpoint de style OpenAI sous /v1. Cela signifie que le package officiel openai fonctionne, tout comme la plupart des logiciels qui vous permettent de définir une URL de base personnalisée. La clé est requise par le SDK mais ignorée par un Ollama local, donc n’importe quelle chaîne conviendra.

Copyfrom openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
resp = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "Give me a one-line summary of TCP."}],
)
print(resp.choices[0].message.content)

C'est la forme la plus utile, car elle découple votre code du serveur. La même fonction peut parler à un modèle local aujourd'hui et à autre chose demain, ce qui est la section suivante.

Le même code contre une API hébergée

L’option hébergée ici est une API compatible OpenAI avec un seul modèle, uncensored, gérée par un fournisseur indépendant et optimisée pour répondre sans refus de contenu pour une utilisation légale par les adultes. Elle est uniquement textuelle. L’URL de base est https://api.ollamaapi.cc/v1, et vous vous authentifiez avec une clé Bearer depuis la page Clé API.

Voici une version qui lit sa cible à partir de variables d'environnement, avec les valeurs hébergées par défaut. Pour revenir à votre serveur local, exportez deux variables et ne changez rien d'autre.

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.getenv("LLM_BASE_URL", "https://api.ollamaapi.cc/v1"),
    api_key=os.getenv("LLM_API_KEY", "YOUR_API_KEY"),
)
MODEL = os.getenv("LLM_MODEL", "uncensored")

resp = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "List four uses of a message queue."},
    ],
    temperature=0.7,
)
print(resp.choices[0].message.content)

Pour les exécutions locales, définissez LLM_BASE_URL=http://localhost:11434/v1, LLM_API_KEY=ollama et LLM_MODEL=llama3.2. Le guide de démarrage rapide a la même configuration en curl et Node.

Streaming, mode JSON et outils côté hébergé

L'endpoint hébergé prend en charge le streaming via SSE, le mode JSON, l'appel de fonctions, et les paramètres d'échantillonnage habituels (temperature, top_p, stop, seed et les pénalités). Le streaming avec le SDK est la même boucle que vous écririez pour n'importe quel serveur de style OpenAI :

Copystream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Tell a two-paragraph story about a lighthouse."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Pour une sortie structurée, définissez response_format={"type": "json_object"} et indiquez dans le prompt que vous voulez du JSON. Analysez toujours à l'intérieur d'un bloc try ; un modèle peut toujours retourner quelque chose que vous n'avez pas prévu.

Une différence par rapport à l'utilisation locale est importante dans le code : les limites. Une clé complète permet 8 requêtes simultanées et 300 requêtes par minute, et une requête diffusée garde sa place jusqu'à la fin du flux. Si vous parallélisez avec des threads, limitez le pool à 8 et réessayez sur HTTP 429 en utilisant l'en-tête Retry-After lorsqu'il est présent.

Maintenir une conversation

Ni l'endpoint de chat local ni l'endpoint hébergé ne se souviennent de quoi que ce soit entre les appels. Le serveur ne voit que les messages que vous envoyez, donc un chatbot est une liste à laquelle vous ajoutez et que vous renvoyez. Le motif est identique pour les deux cibles, ce qui est une bonne raison de garder le client de style OpenAI comme votre valeur par défaut.

Copyhistory = [{"role": "system", "content": "You are a helpful assistant."}]

def ask(text):
    history.append({"role": "user", "content": text})
    resp = client.chat.completions.create(model=MODEL, messages=history)
    answer = resp.choices[0].message.content
    history.append({"role": "assistant", "content": answer})
    return answer

print(ask("Pick a name for a hiking app."))
print(ask("Give me a tagline for it."))

Deux notes pratiques. Premièrement, les modèles locaux ont une longueur de fenêtre de contexte que vous définissez et que la mémoire doit contenir ; si l'historique dépasse cette limite, les tours plus anciens sont coupés ou l'appel échoue, selon les paramètres. Le modèle hébergé accepte une fenêtre de 100 000 tokens incluant la complétion, ce qui est bien plus que la plupart des chats n'ont besoin, mais les longs historiques coûtent toujours des tokens d'entrée à chaque tour. Deuxièmement, une fois qu'un historique devient long, résumez les tours les plus anciens en un court message au lieu de tous les renvoyer. Cela maintient la latence et le coût stables sur les deux backends.

Nouvelle tentative polie

Sur l'API hébergée, une surcharge temporaire renvoie HTTP 429 avec un en-tête Retry-After: 5. Un petit adaptateur le gère :

Copyimport time
from openai import RateLimitError

def chat_with_retry(messages, tries=4):
    for attempt in range(tries):
        try:
            return client.chat.completions.create(model=MODEL, messages=messages)
        except RateLimitError:
            time.sleep(5 * (attempt + 1))
    raise RuntimeError("still rate limited")

Ollama local ne vous limite pas en débit, mais il met en file d'attente les requêtes lorsque le modèle est occupé, donc le même adaptateur ne pose pas de problème là-bas.

Local ou hébergé : comment décider

Aucun des deux choix n'est meilleur en général. Utilisez les points ci-dessous comme liste de contrôle.

• Choisissez Ollama en local si vous devez travailler hors ligne, si les données ne doivent jamais quitter la machine, si vous possédez déjà un GPU capable, ou si vous voulez essayer rapidement plusieurs modèles ouverts différents.
• Choisissez une API hébergée si vous n’avez pas de GPU, si vous utilisez un petit VPS ou dans un environnement CI, si plusieurs personnes ou services partagent un seul backend, ou si vous souhaitez une longue fenêtre de contexte sans avoir à dimensionner la mémoire vous-même. Le modèle hébergé accepte jusqu’à 100 000 tokens au total pour le prompt et la complétion.
• Mélangez les deux pendant le développement : itérez localement, puis pointez la production vers l'URL hébergée via des variables d'environnement.

L'utilisation hébergée est facturée par token, à $0,15 par 1M de tokens d'entrée et $0,50 par 1M de tokens de sortie, à partir de crédit prépayé. La page de tarification liste les montants de rechargement, et les nouveaux comptes peuvent obtenir un crédit d'essai de $0,50 en un clic, sans carte nécessaire. Les prompts ne sont pas utilisés pour l'entraînement.

Erreurs que vous rencontrerez

Symptôme	Cause probable	Correction
Connexion refusée sur le port 11434	Le serveur Ollama n'est pas en cours d'exécution	Démarrez l'application ou exécutez ollama serve
Modèle non trouvé	Le modèle n'a jamais été tiré, ou le nom contient une faute de frappe	Exécutez ollama list, puis ollama pull le nom que vous utilisez
Le premier appel expire (timeout)	Le modèle est encore en cours de chargement	Augmentez le délai d'expiration ou envoyez une requête de pré-chauffage
Erreur d'authentification sur l'API hébergée	Clé Bearer manquante ou incorrecte	Vérifiez LLM_API_KEY et l'URL de base
HTTP 429 avec le code concurrency	Plus de 8 requêtes en cours (2 sur une clé d'essai)	Réduisez le nombre de workers
HTTP 429 avec le code rate_limited	Limite de requêtes par minute dépassée	Reculez et réessayez

Les requêtes échouées ou refusées côté hébergement ne sont pas facturées, donc la logique de nouvelle tentative n'entraîne pas de facturation pour les tentatives échouées.

Plus de guides

• Tarification de l'API Ollama : coût local vs paiement par token
• API Ollama vs OpenRouter : lequel vous convient ?
• Guide de la clé API Mistral