API Ollama en Python, puis un endpoint hébergé

Configurez le client Python

Installez d'abord Ollama lui-même, lancez-le, et pull un modèle depuis un terminal : ollama pull llama3. Le serveur écoute sur http://localhost:11434. Ensuite, installez le package Python dans un environnement virtuel :

Copypython -m venv .venv
source .venv/bin/activate
pip install ollama openai

Le package ollama communique avec les routes natives d'Ollama sous /api. Le package openai est destiné à la deuxième partie de ce tutoriel, où la cible est un endpoint hébergé. Si vous préférez un outil visuel avant de coder, consultez les notes sur l'utilisation d'Ollama avec une interface graphique.

Vérifiez l'installation en exécutant ollama list dans le terminal. Si votre modèle apparaît là, Python le trouvera. Si vous obtenez une erreur de connexion plus tard, le serveur n'est probablement pas en cours d'exécution.

Votre premier appel de chat

Voici les bases de l'API python ollama en un seul extrait : un message système, un message utilisateur et deux options.

Copyimport ollama

resp = ollama.chat(
    model="llama3",
    messages=[
        {"role": "system", "content": "Answer in one short paragraph."},
        {"role": "user", "content": "What is a context window?"},
    ],
    options={"temperature": 0.4, "num_ctx": 8192},
)
print(resp["message"]["content"])

La réponse est un objet de type dictionnaire ; le texte se trouve dans message.content. Dans options vous pouvez définir des paramètres de génération. temperature contrôle l'aléatoire et num_ctx définit la longueur de contexte pour cet appel. Ollama utilise par défaut un contexte assez petit à moins que vous ne l'augmentiez, ce qui surprend les gens qui collent de longs documents et obtiennent des réponses qui ignorent le début.

Pour le chat multi-tours, gardez une liste de messages et ajoutez chaque réponse vous-même. Ollama, comme la plupart des APIs de chat, est sans état entre les appels.

Réponses en streaming

Sans streaming, vous attendez la réponse complète. Avec stream=True, la fonction retourne un générateur et vous imprimez les morceaux à mesure qu'ils arrivent :

Copyimport ollama

for part in ollama.chat(
    model="llama3",
    messages=[{"role": "user", "content": "Explain recursion with a cooking analogy."}],
    stream=True,
):
    print(part["message"]["content"], end="", flush=True)

Chaque partie contient un petit message.content. La dernière partie a done défini à true et inclut les délais et le nombre de tokens. Pour les applications web, transmettez ces éléments au navigateur via des événements envoyés par le serveur ou des WebSockets.

Les erreurs que vous verrez réellement

Deux échecs couvrent la plupart des problèmes des débutants.

Copyimport ollama

try:
    ollama.chat(model="llama3", messages=[{"role": "user", "content": "hi"}])
except ollama.ResponseError as exc:
    if exc.status_code == 404:
        print("Model missing. Run: ollama pull llama3")
    else:
        raise
except ConnectionError:
    print("Cannot reach Ollama. Is the server running on port 11434?")

Une erreur 404 de ResponseError signifie que le nom du modèle ne correspond à rien que vous ayez récupéré. Les noms incluent des tags, donc llama3 et llama3:70b sont des modèles différents. Une erreur de connexion signifie que le serveur n'est pas en marche, ou que vous êtes dans un conteneur où localhost pointe vers le conteneur, et non l'hôte. Dans ce cas, passez un client avec l'hôte correct : ollama.Client(host="http://host.docker.internal:11434").

D'autres schémas sont répertoriés dans les erreurs courantes de l'API Ollama.

Même programme, endpoint hébergé

Les modèles locaux sont limités par votre mémoire et votre vitesse. Lorsqu'un script doit s'exécuter sur un serveur, gérer de nombreuses tâches en parallèle, ou utiliser une fenêtre plus grande, un endpoint hébergé est plus simple. L'astuce est d'écrire le programme contre le SDK OpenAI et de traiter l'URL de base, la clé et le modèle comme une configuration :

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("LLM_BASE_URL", "https://api.ollamansfw.com/v1"),
    api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

def ask(prompt, history=None):
    messages = (history or []) + [{"role": "user", "content": prompt}]
    out = ""
    for chunk in client.chat.completions.create(model=MODEL, messages=messages, stream=True):
        if chunk.choices and chunk.choices[0].delta.content:
            piece = chunk.choices[0].delta.content
            out += piece
            print(piece, end="", flush=True)
    return out

ask("Explain recursion with a cooking analogy.")

Pour Ollama local, définissez LLM_BASE_URL=http://localhost:11434/v1, LLM_API_KEY=ollama (n'importe quelle chaîne non vide est acceptée là) et LLM_MODEL=llama3. Pour l'API hébergée, utilisez les valeurs par défaut ci-dessus, votre vraie clé et le modèle uncensored. Rien d'autre dans le code ne change.

Obtenez une clé sur la page clé API. Les nouveaux comptes peuvent réclamer un crédit d'essai gratuit de 0,50 $ en un clic, sans paiement, valable 7 jours. Le modèle est un modèle à poids ouverts d'un fournisseur indépendant, ajusté pour répondre sans refus de contenu pour une utilisation adulte légale. Il est uniquement textuel et n'est pas l'API officielle d'un grand laboratoire.

Exécution de nombreux prompts en parallèle

Un modèle local sur une machine gère généralement une requête à la fois, donc les boucles sont séquentielles. Un endpoint hébergé permet la concurrence, ce qui rend le travail par lots beaucoup plus rapide. Maintenez le nombre de workers sous la limite de votre clé : 8 requêtes simultanées pour une clé complète, 2 pour une clé d'essai.

Copyfrom concurrent.futures import ThreadPoolExecutor
from openai import OpenAI

client = OpenAI(base_url="https://api.ollamansfw.com/v1", api_key="YOUR_KEY")

def summarize(text):
    r = client.chat.completions.create(
        model="uncensored",
        messages=[{"role": "user", "content": "Summarize in one line: " + text}],
        max_tokens=60,
    )
    return r.choices[0].message.content

docs = ["first text", "second text", "third text"]
with ThreadPoolExecutor(max_workers=6) as pool:
    results = list(pool.map(summarize, docs))
print(results)

Six workers laissent une marge sous la limite de 8. Si un worker reçoit un 429, le SDK OpenAI réessaie quelques fois par défaut, mais ajoutez votre propre logique de réessai pour les exécutions longues. N'oubliez pas aussi que chaque requête en streaming occupe son slot jusqu'à la fin du flux, donc ne mélangez pas une longue conversation en streaming et un gros lot sur la même clé d'essai.

Différences à anticiper

• Aucune option locale uniquement. num_ctx et keep_alive n'ont pas de sens côté hébergé. La fenêtre de contexte est de 100 000 tokens, prompts et complétions confondus.
• Limites de débit. Une clé complète permet 8 requêtes simultanées et 300 requêtes par minute ; une clé d'essai en permet 2 et 60. Au-delà, vous obtenez un code d'erreur 429 avec rate_limited ou concurrency. Réessayez après une pause ; en cas de surcharge temporaire, la réponse contient Retry-After: 5.
• Coût. L'entrée est de 0,15 $ par 1M de tokens et la sortie est de 0,50 $ par 1M. Un script qui envoie 2 000 prompts de 600 tokens d'entrée et 400 tokens de sortie dépense 2 000 x (600 x 0,15 $ + 400 x 0,50 $) / 1M = 2 000 x 0,00029 $ = 0,58 $.
• Facturation. Crédit prépayé, de $20 à $500, payé avec de la crypto (USDT sur TRC20 ou USDC sur Base). Les requêtes échouées ou refusées ne sont pas facturées.

Pour une comparaison côte à côte des endpoints, lisez notre note sur la tarification de l'API ou la documentation.

Plus de guides

• API Ollama vs API OpenAI : endpoints et code
• Comment utiliser Ollama avec une interface graphique (et une solution de secours hébergée)