Blog
Point de vue

Comment utiliser LiteLLM avec Ollama

Les LLMs transforment les apps. Ollama facilite l'exécution locale de modèles open-source (Llama 3, Mistral, Phi-3) sur macOS, Linux, Windows.

Louis Dupont

Louis Dupont

5 June 2025

Comment utiliser LiteLLM avec Ollama

Les modèles linguistiques volumineux (LLM) transforment la façon dont nous construisons des applications, mais s'appuyer uniquement sur des API basées sur le cloud n'est pas toujours idéal. La latence, le coût, la confidentialité des données et la nécessité de capacités hors ligne poussent souvent les développeurs à exécuter des modèles localement. Ollama est apparu comme un outil fantastique pour exécuter facilement des LLM open-source puissants comme Llama 3, Mistral et Phi-3 directement sur votre machine (macOS, Linux, Windows).

Cependant, l'interaction avec différents LLM, qu'ils soient locaux ou distants, nécessite souvent d'écrire du code spécifique au modèle. C'est là que LiteLLM entre en jeu. LiteLLM fournit une interface standardisée et légère pour interagir avec plus de 100 API de LLM différentes, dont Ollama, OpenAI, Anthropic, Cohere et bien d'autres. En utilisant LiteLLM, vous pouvez écrire du code une fois et basculer de manière transparente entre différents modèles et fournisseurs, y compris vos modèles Ollama en cours d'exécution localement, avec des modifications minimales.

Ce tutoriel fournit un guide détaillé, étape par étape, sur la façon de configurer et d'utiliser LiteLLM pour interagir avec les modèles Ollama exécutés sur votre machine locale. Nous couvrirons tout, de l'installation et de la configuration de base à la réalisation d'appels d'API, au streaming des réponses et à l'exploitation des fonctionnalités plus avancées de LiteLLM.

💡
Vous voulez un excellent outil de test d'API qui génère une belle documentation API ?

Vous voulez une plateforme intégrée, tout-en-un, pour que votre équipe de développeurs travaille ensemble avec une productivité maximale ?

Apidog répond à toutes vos demandes et remplace Postman à un prix beaucoup plus abordable !
button

Introduction : Pourquoi LiteLLM et Ollama ?

Avant de plonger dans les étapes techniques, comprenons les outils avec lesquels nous travaillons et pourquoi leur combinaison est puissante.

Qu'est-ce que LiteLLM ?

LiteLLM est une bibliothèque Python légère qui agit comme une interface unifiée pour interagir avec un vaste éventail d'API de LLM. Au lieu d'apprendre et de mettre en œuvre différents SDK ou formats de requêtes API pour OpenAI, Anthropic, Cohere, Google Gemini, Azure OpenAI, Replicate, Hugging Face, et les modèles locaux comme Ollama, vous utilisez un seul appel de fonction cohérent : litellm.completion(). LiteLLM gère la complexité sous-jacente de la traduction de votre requête dans le format spécifique requis par le fournisseur de modèles cible.

Principales fonctionnalités de LiteLLM :

Pourquoi utiliser LiteLLM avec Ollama ?

La combinaison d'Ollama et de LiteLLM offre plusieurs avantages :

  1. Normalisation : écrivez une logique d'application à l'aide de l'interface standard de LiteLLM, ce qui vous permet de basculer de manière transparente entre un modèle Ollama local (pour le développement, la confidentialité, l'utilisation hors ligne) et un modèle cloud puissant (pour la production, des capacités spécifiques) sans réécrire le code de base.
  2. Intégration locale simplifiée : LiteLLM facilite l'interaction avec l'API d'Ollama dans vos applications Python, en gérant la mise en forme des requêtes et l'analyse des réponses.
  3. Flexibilité : expérimentez facilement avec différents modèles locaux disponibles via Ollama simplement en modifiant le nom du modèle dans votre appel LiteLLM (par exemple, ollama/llama3 vs. ollama/mistral).
  4. Tirer parti des fonctionnalités de LiteLLM : bénéficiez des fonctionnalités de LiteLLM telles que les nouvelles tentatives, les solutions de repli, la journalisation et le suivi des coûts, même lorsque vous utilisez des modèles Ollama locaux.
  5. Approches hybrides : créez des applications capables d'acheminer intelligemment les requêtes vers des modèles Ollama locaux ou des API distantes en fonction de facteurs tels que le coût, la latence ou les exigences de la tâche, le tout géré via LiteLLM (en particulier via son proxy).

Se préparer à utiliser LiteLLM et Ollama

Avant de commencer, assurez-vous d'avoir les outils nécessaires installés et configurés.

LiteLLM est une bibliothèque Python, vous devez donc avoir Python installé sur votre système. LiteLLM nécessite Python 3.8 ou supérieur.

python --version
# or
python3 --version

Installer et configurer Ollama

Vous devez avoir Ollama installé et en cours d'exécution sur la même machine où vous prévoyez d'exécuter votre code Python LiteLLM (ou accessible via le réseau si vous l'exécutez sur une autre machine).

ollama --version

Cela devrait afficher la version d'Ollama installée.

Extraire un modèle Ollama

Ollama a besoin d'au moins un modèle téléchargé pour pouvoir traiter les requêtes. Extrayons un modèle populaire comme Llama 3 (variante d'instruction 8B).

ollama pull llama3

Cela téléchargera les fichiers du modèle Llama 3. Cela peut prendre un certain temps en fonction de votre connexion Internet et de la taille du modèle. Vous pouvez remplacer llama3 par d'autres modèles disponibles dans la bibliothèque Ollama (par exemple, mistral, phi3, gemma:2b). Consultez le site Web d'Ollama pour obtenir une liste complète.

Installer LiteLLM

Avec Python et Ollama prêts, installez LiteLLM à l'aide de pip.

pip install litellm
# or if you use pip3
# pip3 install litellm

python # or python3
>>> import litellm
>>> litellm.__version__
# This should print the installed version without errors.
>>> exit()

Exécuter Ollama localement

LiteLLM doit se connecter au serveur API d'Ollama. Vous devez vous assurer qu'Ollama est en cours d'exécution.

Vérification de l'exécution d'Ollama

ollama serve

Cette commande démarrera le serveur, et il continuera généralement à s'exécuter dans cette fenêtre de terminal jusqu'à ce que vous l'arrêtiez (Ctrl+C). Vous souhaiterez peut-être l'exécuter en arrière-plan ou en tant que service système pour une utilisation à long terme.

curl http://localhost:11434

Vous devriez obtenir une réponse comme Ollama is running. Si vous obtenez une erreur « connection refused », Ollama n'est probablement pas en cours d'exécution ou est configuré sur un port/une adresse différent(e).

Par défaut, Ollama expose son API à :

LiteLLM est préconfiguré pour connaître cette adresse par défaut. Si votre instance Ollama s'exécute sur un autre hôte ou port (par exemple, à l'intérieur d'un conteneur Docker avec mappage de port, ou sur un serveur distant), vous devrez indiquer à LiteLLM où le trouver (couvert dans la section Configuration). Pour la plupart des configurations locales standard, la valeur par défaut fonctionne immédiatement.

Effectuer votre premier appel LiteLLM à Ollama

Maintenant, écrivons un script Python simple pour envoyer une requête au modèle llama3 en cours d'exécution via Ollama, à l'aide de LiteLLM.

Script Python de base

Créez un nouveau fichier Python (par exemple, ollama_test.py) et ajoutez le code suivant :

import litellm
import os

# Optional: Set verbose logging for LiteLLM to see what's happening
# litellm.set_verbose = True

# Define the model name - important: prefix with "ollama/"
# Ensure 'llama3' is the model you pulled with `ollama pull llama3`
model_name = "ollama/llama3"

# Define the messages for the chat completion
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Why is the sky blue?"}
]

try:
    print(f"--- Sending request to {model_name} ---")
    # Call the litellm.completion function
    response = litellm.completion(
        model=model_name,
        messages=messages
    )

    # Print the response
    print("--- Response ---")
    # The response object mirrors the OpenAI structure
    # Access the message content like this:
    message_content = response.choices[0].message.content
    print(message_content)

    # You can also print the entire response object for inspection
    # print("\n--- Full Response Object ---")
    # print(response)

except Exception as e:
    print(f"An error occurred: {e}")

Décomposons la fonction :

Avec ces points à l'esprit, exécutons la fonction :

Assurez-vous qu'Ollama est en cours d'exécution (comme vérifié à l'étape 4) et que vous avez extrait le modèle llama3. Ensuite, exécutez le script à partir de votre terminal :

python ollama_test.py

Vous devriez voir une sortie similaire à celle-ci (le texte exact variera en fonction de la réponse du modèle) :

--- Sending request to ollama/llama3 ---
--- Response ---
The sky appears blue because of a phenomenon called Rayleigh scattering. Sunlight reaching Earth's atmosphere is composed of different colors of light, which have different wavelengths. Blue and violet light have shorter wavelengths, while red and orange light have longer wavelengths.

As sunlight travels through the atmosphere, it collides with tiny gas molecules (mostly nitrogen and oxygen). These molecules scatter the sunlight in all directions. Shorter wavelengths (blue and violet) are scattered more effectively than longer wavelengths (red and orange).

Our eyes are more sensitive to blue than violet, and some violet light is absorbed higher in the atmosphere, so we perceive the sky as primarily blue during the daytime when the sun is high.

Near sunrise and sunset, sunlight passes through more of the atmosphere to reach our eyes. Most of the blue light is scattered away, allowing more of the longer wavelength red and orange light to reach us, which is why sunrises and sunsets often appear reddish or orange.

Félicitations ! Vous avez utilisé avec succès LiteLLM pour communiquer avec votre modèle Ollama local.

Effectuer des réponses en streaming

Pour les applications interactives (comme les chatbots) ou lors de la génération de longues réponses, attendre la complétion complète peut entraîner une mauvaise expérience utilisateur. Le streaming vous permet de recevoir la réponse jeton par jeton au fur et à mesure de sa génération. LiteLLM facilite cela.

Pourquoi le streaming ?

Implémentation du streaming avec LiteLLM

Modifiez le script précédent (ollama_test.py) pour activer le streaming :

import litellm
import os

# litellm.set_verbose = True # Optional for debugging

model_name = "ollama/llama3"
messages = [
    {"role": "system", "content": "You are a concise poet."},
    {"role": "user", "content": "Write a short haiku about a cat."}
]

try:
    print(f"--- Sending streaming request to {model_name} ---")
    # Set stream=True
    response_stream = litellm.completion(
        model=model_name,
        messages=messages,
        stream=True  # Enable streaming
    )

    print("--- Streaming Response ---")
    full_response = ""
    # Iterate through the stream chunks
    for chunk in response_stream:
        # Each chunk mimics the OpenAI streaming chunk structure
        # Access the content delta like this:
        content_delta = chunk.choices[0].delta.content

        if content_delta:  # Check if there's new content in this chunk
            print(content_delta, end="", flush=True) # Print immediately without newline
            full_response += content_delta

    print("\n--- End of Stream ---")
    # print(f"\nFull reconstructed response:\n{full_response}") # Optional: show full response at the end

except Exception as e:
    print(f"\nAn error occurred: {e}")

Modifications :

  1. stream=True : a ajouté ce paramètre à l'appel litellm.completion.
  2. Itération : la fonction renvoie désormais un itérateur (response_stream). Nous parcourons cette itération.
  3. Gestion des blocs : chaque chunk dans la boucle représente une petite partie de la réponse. Nous accédons au nouveau fragment de texte à l'aide de chunk.choices[0].delta.content. L'attribut delta contient la différence par rapport au bloc précédent (généralement quelques caractères ou un mot).
  4. print(..., end="", flush=True) : imprime immédiatement le contenu du bloc sans ajouter de nouvelle ligne, en vidant la mémoire tampon de sortie pour s'assurer qu'il apparaît immédiatement dans le terminal.

Exécutez ce script mis à jour :

python ollama_test.py

Vous verrez le haïku apparaître mot par mot ou caractère par caractère dans votre terminal, ce qui démontre le comportement de streaming.

Configuration de la configuration LiteLLM + Ollama

Bien que LiteLLM fonctionne avec les configurations Ollama par défaut, vous devrez peut-être le configurer si votre configuration s'écarte du http://localhost:11434 standard.

Comportement par défaut (Localhost)

Comme mentionné, LiteLLM suppose automatiquement qu'Ollama s'exécute à http://localhost:11434 lorsque vous utilisez le préfixe ollama/. S'il s'agit de votre configuration, aucune configuration supplémentaire n'est nécessaire.

Utilisation de variables d'environnement (facultatif)

Si Ollama s'exécute sur un autre hôte ou port, vous pouvez indiquer à LiteLLM où le trouver à l'aide de variables d'environnement. LiteLLM recherche des variables d'environnement spécifiques pour configurer les points de terminaison de l'API. Pour un modèle Ollama spécifique (ou tous les modèles Ollama si vous souhaitez une substitution générale), vous pouvez définir son URL de base.

Par exemple, si votre instance Ollama s'exécute à http://192.168.1.100:11434, vous pouvez définir une variable d'environnement avant d'exécuter votre script Python :

Linux/macOS :

export OLLAMA_API_BASE="http://192.168.1.100:11434"
python your_script.py

Windows (invite de commande) :

set OLLAMA_API_BASE=http://192.168.1.100:11434
python your_script.py

Windows (PowerShell) :

$env:OLLAMA_API_BASE = "http://192.168.1.100:11434"
python your_script.py

Maintenant, lorsque votre script appelle litellm.completion(model="ollama/llama3", ...), LiteLLM recherchera la variable d'environnement OLLAMA_API_BASE et utilisera cette URL au lieu de la valeur par défaut localhost.

Remarque : la définition de OLLAMA_API_BASE remplace l'URL de base pour tous les modèles commençant par ollama/. Consultez la documentation de LiteLLM pour des contrôles de variables d'environnement plus granulaires si nécessaire (par exemple, définir l'URL de base pour un alias de modèle spécifique).

Utilisation d'un fichier de configuration (facultatif)

Pour des configurations plus complexes impliquant plusieurs modèles, des paramètres personnalisés ou pour éviter les variables d'environnement, LiteLLM prend en charge un fichier de configuration (config.yaml ou chemin spécifié).

Créez un fichier config.yaml dans le même répertoire que votre script (ou ailleurs, et pointez LiteLLM vers celui-ci) :

# config.yaml
model_list:
  - model_name: ollama/llama3 # The name you use in litellm.completion
    litellm_params:
      model: ollama/llama3 # The actual model identifier for the provider
      api_base: "http://localhost:11434" # Default, change if needed

  - model_name: ollama/mistral-remote # Example: Alias for a remote Ollama
    litellm_params:
      model: ollama/mistral # Ollama expects 'mistral'
      api_base: "http://192.168.1.100:11434"

  - model_name: gpt-4o-mini # Example: Including a non-Ollama model
    litellm_params:
      model: gpt-4o-mini
      api_key: "os.environ/OPENAI_API_KEY" # Securely read from env var

general_settings:
  # Optional: Set global settings like timeouts
  # timeout: 300 # 5 minutes

# You can define custom environment variables within the config too
environment_variables:
  OPENAI_API_KEY: "" # Define placeholders or actual keys (less secure)

Pour utiliser ce fichier de configuration, vous devez indiquer à LiteLLM de le charger, généralement au début de votre application :

import litellm
import os

# Load configuration from config.yaml in the current directory
# You can also provide an absolute path: litellm.load_config("path/to/your/config.yaml")
try:
    litellm.load_config()
    print("LiteLLM configuration loaded successfully.")
except Exception as e:
    print(f"Warning: Could not load LiteLLM config. Using defaults. Error: {e}")


# Now you can use the model names defined in the config
try:
    # Using the standard ollama/llama3 which might pick up the api_base from the config
    response_local = litellm.completion(model="ollama/llama3", messages=[{"role": "user", "content": "Test local"}])
    print("Local Llama3 Response:", response_local.choices[0].message.content[:50], "...") # Print snippet

    # Using the alias defined for the remote mistral model
    # response_remote = litellm.completion(model="ollama/mistral-remote", messages=[{"role": "user", "content": "Test remote"}])
    # print("Remote Mistral Response:", response_remote.choices[0].message.content[:50], "...")

except Exception as e:
    print(f"An error occurred during completion: {e}")

Le fichier de configuration offre un moyen structuré de gérer les paramètres de plusieurs modèles, y compris les instances Ollama potentiellement en cours d'exécution sur différentes machines.

Au-delà des appels de base et du streaming, LiteLLM offre des fonctionnalités qui améliorent la robustesse et l'observabilité, qui fonctionnent de manière transparente avec Ollama.

Alias de modèle

Bien que le fichier de configuration permette de définir des alias, vous pouvez également les enregistrer par programme. Ceci est utile pour simplifier les noms de modèles ou mapper des noms génériques vers des modèles Ollama spécifiques.

import litellm

# Define an alias: map "my-local-llm" to "ollama/llama3"
litellm.register_model({
    "my-local-llm": {
        "model": "ollama/llama3",
        # You could also specify api_base here if needed for this alias specifically
        # "api_base": "http://localhost:11434"
    }
})

# Now use the alias in your completion call
messages = [{"role": "user", "content": "Tell me about model aliasing."}]
response = litellm.completion(model="my-local-llm", messages=messages)

print(response.choices[0].message.content)

Gestion des erreurs et nouvelles tentatives

Des problèmes de réseau ou des problèmes Ollama temporaires peuvent survenir. LiteLLM dispose d'une logique de nouvelle tentative intégrée.

import litellm
import time

# Example: Make Ollama temporarily unavailable (e.g., stop `ollama serve`)
print("Stopping Ollama for 10 seconds (if possible)... You might need to do this manually.")
# os.system("ollama stop") # This command might not exist; manual stop is safer
# time.sleep(10)
# print("Restarting Ollama... You might need to do this manually.")
# os.system("ollama serve &") # Start in background
# time.sleep(5) # Give it time to start

messages = [{"role": "user", "content": "Does retry work?"}]

try:
    # LiteLLM will automatically retry on specific connection errors
    # You can configure the number of retries, backoff factor, etc.
    response = litellm.completion(
        model="ollama/llama3",
        messages=messages,
        num_retries=3,       # Attempt up to 3 retries
        timeout=10           # Set a timeout for each request attempt (seconds)
    )
    print("Success after retries (or on first try):")
    print(response.choices[0].message.content)

except Exception as e:
    # This will catch errors that persist after retries (e.g., model not found, config error)
    # Or if all retries fail for connection errors.
    print(f"An error occurred after retries: {e}")

LiteLLM relance intelligemment les erreurs de réseau transitoires courantes. Vous pouvez personnaliser le comportement de nouvelle tentative globalement ou par appel.

Journalisation et rappels

LiteLLM fournit des hooks pour enregistrer les données de requête/réponse ou déclencher des fonctions personnalisées (rappels) lors d'appels réussis ou d'erreurs. Ceci est inestimable pour la surveillance, le débogage et le suivi des coûts (bien que le suivi des coûts soit moins pertinent pour Ollama local, sauf si vous attribuez des coûts virtuels).

import litellm
import logging

# Configure basic logging
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(message)s')
logger = logging.getLogger(__name__)

# Define a simple success callback function
def log_success(kwargs, completion_response, start_time, end_time):
    """Logs details about a successful LLM call."""
    model = kwargs.get("model", "unknown_model")
    input_text = kwargs.get("messages", [])[-1]['content'] if kwargs.get("messages") else "N/A"
    output_text = completion_response.choices[0].message.content[:50] + "..." # Snippet
    duration = (end_time - start_time).total_seconds()
    logger.info(f"Success! Model: {model}, Duration: {duration:.2f}s, Input: '{input_text[:30]}...', Output: '{output_text}'")

# Define a simple failure callback function
def log_failure(kwargs, exception, start_time, end_time):
    """Logs details about a failed LLM call."""
    model = kwargs.get("model", "unknown_model")
    duration = (end_time - start_time).total_seconds()
    logger.error(f"Failure! Model: {model}, Duration: {duration:.2f}s, Error: {exception}")


# Register the callbacks with LiteLLM
litellm.success_callback = [log_success]
litellm.failure_callback = [log_failure]

# Now make a call - callbacks will trigger automatically
messages = [{"role": "user", "content": "How do callbacks work in LiteLLM?"}]
try:
    response = litellm.completion(model="ollama/llama3", messages=messages)
    # print(response.choices[0].message.content) # You can still use the response
except Exception as e:
    pass # Failure callback already handled the logging

# Example of a call that might fail (e.g., model not pulled)
# try:
#     response_fail = litellm.completion(model="ollama/nonexistent-model", messages=messages)
# except Exception as e:
#     pass # Failure callback will log

Exécutez ce script, et vous verrez des messages INFO ou ERROR enregistrés par vos fonctions de rappel, offrant une visibilité sur les interactions LLM. LiteLLM s'intègre également à des plateformes comme Langfuse, Helicone, PromptLayer, etc., pour une observabilité plus avancée.

Gestion des clés API

Bien qu'Ollama lui-même ne nécessite généralement pas de clés API pour l'accès local, si votre application utilise également des fournisseurs cloud (OpenAI, Anthropic, etc.) via LiteLLM, vous devrez gérer ces clés. LiteLLM recherche les clés dans les variables d'environnement standard (par exemple, OPENAI_API_KEY, ANTHROPIC_API_KEY) ou elles peuvent être définies dans le config.yaml ou passées directement à l'appel completion (moins recommandé pour la sécurité). L'utilisation d'un config.yaml ou de variables d'environnement est l'approche préférée.

Comment utiliser le serveur proxy LiteLLM (recommandé pour la robustesse)

Bien que l'utilisation directe de la bibliothèque litellm dans votre code Python soit idéale pour les scripts simples ou les applications uniques, le proxy LiteLLM offre une solution plus robuste et évolutive, en particulier pour les microservices ou lorsque plusieurs applications ont besoin d'accéder aux LLM (y compris Ollama).

Qu'est-ce que le proxy LiteLLM ?

Le proxy LiteLLM est un serveur autonome que vous exécutez séparément. Vos applications effectuent ensuite des requêtes API standard compatibles avec OpenAI vers le point de terminaison du proxy. Le proxy, configuré avec les détails de votre modèle (y compris les instances Ollama, les clés API pour les fournisseurs cloud, etc.), gère l'acheminement

Explore more

Fathom-R1-14B : Modèle de raisonnement IA avancé d'Inde

Fathom-R1-14B : Modèle de raisonnement IA avancé d'Inde

L'IA en expansion rapide. Fathom-R1-14B (14,8 milliards de paramètres) excelle en raisonnement mathématique et général, conçu par Fractal AI Research.

5 June 2025

Mistral Code : L'assistant de codage le plus personnalisable basé sur l'IA pour les entreprises

Mistral Code : L'assistant de codage le plus personnalisable basé sur l'IA pour les entreprises

Découvrez Mistral Code, l'IA d'aide au code la plus personnalisable pour les entreprises.

5 June 2025

Comment Claude Code transforme le codage de l'IA en 2025

Comment Claude Code transforme le codage de l'IA en 2025

Découvrez Claude Code en 2025 : codage IA révolutionné. Fonctionnalités, démo, et pourquoi il gagne du terrain après Windsurf d'Anthropic. Indispensable !

5 June 2025

Pratiquez le Design-first d'API dans Apidog

Découvrez une manière plus simple de créer et utiliser des API

S'inscrire gratuitementTélécharger