API compatible OpenAI d’Ollama : accès, tarifs, intégration et guide de production

API compatible OpenAI d’Ollama : accès, tarifs, intégration et guide de production

L’API compatible OpenAI d’Ollama permet à une application de conserver la structure familière du SDK OpenAI tout en envoyant des requêtes soit vers un serveur Ollama local, soit directement vers Ollama Cloud. C’est utile, mais cela ne garantit pas une parité fonctionnelle complète : Ollama documente la prise en charge d’un sous-ensemble de l’API OpenAI, et certaines capacités dépendent de l’endpoint et du modèle que vous choisissez.

Ce guide explique comment accéder à cette interface, la configurer dans une application Python ou JavaScript existante, comprendre les coûts du cloud par rapport au local et lui imposer de véritables limites de production.

Réponse rapide : utilisez http://localhost:11434/v1/ pour un serveur Ollama local et une clé API fictive requise par le SDK mais ignorée par Ollama. Utilisez https://ollama.com/v1 avec OLLAMA_API_KEY pour un accès direct au cloud. Validez l’endpoint et le modèle exacts avant de vous appuyer sur le streaming, la vision, les outils, la sortie structurée ou le comportement de l’API Responses.

Que signifie « compatible OpenAI » pour Ollama ?

Il s’agit d’une surface d’intégration pour les clients OpenAI, et non d’une API hébergée par OpenAI. Elle vous permet de diriger des clients compatibles vers les URL de base d’Ollama et d’utiliser des routes prises en charge, telles que les complétions de chat, les embeddings, la découverte de modèles et les requêtes Responses sans état.

La référence de compatibilité d’Ollama est la source de vérité concernant le sous-ensemble pris en charge. En particulier :

• /v1/chat/completions prend en charge des fonctionnalités telles que le streaming, le mode JSON, la vision, les outils, les sorties reproductibles, les logprobs et des contrôles qui ne s’appliquent qu’aux modèles compatibles.
• /v1/embeddings prend en charge les entrées sous forme de chaînes et de tableaux.
• /v1/models et /v1/models/{model} prennent en charge la découverte de modèles, mais certains champs renvoyés ont une signification propre à Ollama.
• POST /v1/responses est disponible, mais il est sans état : ne vous appuyez pas sur previous_response_id ni sur conversation.

Consultez la référence de compatibilité OpenAI d’Ollama à jour avant d’activer une capacité en production. Le terme « compatible » doit être considéré comme une raison de réutiliser votre client et la forme de vos requêtes, et non comme une raison d’ignorer les tests de fonctionnalités.

Accéder à l’API compatible OpenAI d’Ollama : local ou cloud

Le choix d’implémentation le plus simple consiste à déterminer si l’inférence s’exécute sur votre propre machine ou atteint l’endpoint cloud d’Ollama.

Cette distinction est documentée dans l’introduction à l’API et le guide d’authentification d’Ollama. Les appels directs au cloud nécessitent une clé API. Les appels locaux n’en nécessitent pas.

Configuration locale

Installez Ollama, puis téléchargez le modèle que vous prévoyez d’utiliser. La documentation d’Ollama présente le schéma général :

ollama pull gpt-oss:20b
ollama serve

Vérifiez maintenant que l’endpoint local peut lister les modèles :

curl http://localhost:11434/v1/models

Si cette connexion échoue, résolvez le problème du serveur local avant de modifier le code de l’application. Une migration de client est beaucoup plus facile à déboguer lorsque l’URL de base de l’API et l’inventaire des modèles fonctionnent déjà indépendamment.

Configuration directe du cloud

Pour une utilisation directe du cloud, créez une clé API dans votre compte Ollama et placez-la dans une variable d’environnement :

export OLLAMA_API_KEY="replace-with-your-key"

L’URL de base du cloud est https://ollama.com/v1. Ollama indique que son API hébergée utilise Authorization: Bearer ; ne placez pas de clé à longue durée de vie dans du code navigateur, un dépôt ou un fichier de configuration côté client.

Intégrer l’API compatible OpenAI d’Ollama avec le SDK OpenAI

Le point de migration se situe dans la configuration du client. Conservez les messages de l’application et la gestion des erreurs derrière votre propre interface, puis remplacez uniquement l’URL de base, la clé et la configuration du modèle.

Python : serveur local

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama",  # required by the SDK; ignored by the local server
)

response = client.chat.completions.create(
    model="gpt-oss:20b",
    messages=[
        {"role": "user", "content": "Summarize the production risks of exposing a local API."}
    ],
)

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

Le point de terminaison local n’authentifie pas les requêtes. La clé d’espace réservé existe uniquement parce que le client OpenAI attend une valeur ; elle ne protège pas le serveur local.

Python : cloud direct

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://ollama.com/v1",
    api_key=os.environ["OLLAMA_API_KEY"],
)

response = client.chat.completions.create(
    model="gemma4:31b",
    messages=[
        {"role": "user", "content": "Give one sentence on safe API key storage."}
    ],
)

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

La structure du code est délibérément similaire. La différence opérationnelle ne l’est pas : les appels directs au cloud dépendent d’une clé API et du modèle cloud choisi ; les appels locaux dépendent d’un modèle téléchargé et des ressources disponibles sur l’hôte.

JavaScript : gardez le point de terminaison configurable

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.OLLAMA_BASE_URL ?? "http://localhost:11434/v1/",
  apiKey: process.env.OLLAMA_API_KEY ?? "ollama",
});

const completion = await client.chat.completions.create({
  model: process.env.OLLAMA_MODEL ?? "gpt-oss:20b",
  messages: [{ role: "user", content: "Return a concise health-check message." }],
});

console.log(completion.choices[0].message.content);

Définissez les variables d’environnement pour chaque déploiement :

# Local
OLLAMA_BASE_URL=http://localhost:11434/v1/
OLLAMA_API_KEY=ollama
OLLAMA_MODEL=gpt-oss:20b

# Direct cloud
OLLAMA_BASE_URL=https://ollama.com/v1
OLLAMA_API_KEY=replace-with-your-key
OLLAMA_MODEL=gemma4:31b

Cette configuration rend explicite et vérifiable toute modification ultérieure de route ou de modèle. Elle empêche également qu’une URL de base propre à un environnement devienne un comportement caché de l’application.

Matrice de compatibilité : ce qu’il faut tester avant la mise en production

L’API compatible OpenAI d’Ollama est particulièrement utile lorsque vous faites de la compatibilité un plan de test plutôt qu’une hypothèse.

Deux détails surprennent souvent les équipes :

1. L’état appartient à votre application. Votre application doit stocker les messages ou l’état de conversation dont elle a besoin au lieu d’attendre un comportement de Responses avec état de la part d’Ollama.
2. Un nom de modèle ne garantit pas les capacités. Une requête peut utiliser un point de terminaison compatible tout en ne fournissant pas la qualité ou le comportement d’outil dont un flux de travail a besoin. Testez ensemble le modèle, la taille du prompt, les limites de sortie et les outils.

Si une intégration existante code en dur un nom de modèle OpenAI par défaut, Ollama documente ollama cp comme moyen de créer un alias de modèle local temporaire. Utilisez-le uniquement comme couche de compatibilité délibérée, documentez l’alias et supprimez-le une fois votre configuration explicite.

Tarification d’Ollama : coût total de possession local contre tarifs cloud par jeton

La tarification de l’API compatible OpenAI d’Ollama dépend de la route utilisée.

L’inférence locale n’est pas facturée au jeton, mais elle n’est pas gratuite

L’exécution d’un modèle local ne génère pas de facture cloud Ollama par jeton. Elle crée toutefois un profil de coûts d’exploitation :

• Capacité GPU ou CPU, RAM/VRAM, stockage et amortissement des machines
• Électricité et refroidissement
• Temps de téléchargement des modèles et stockage des images
• Planification de capacité, surveillance, correctifs et réponse aux incidents
• Le coût d’opportunité de maintenir un modèle prêt pour les requêtes à faible latence

Pour un développeur seul, cela peut être un excellent compromis. Pour un produit avec un trafic irrégulier ou plusieurs modèles, calculez l’utilisation du matériel et le travail de fiabilité en plus du coût brut d’inférence.

La tarification directe du cloud est publiée par million de tokens

La page de tarification en direct d’Ollama répertorie les tarifs cloud par million de tokens, avec des prix distincts pour les entrées, les entrées mises en cache et les sorties. Les exemples ci-dessous ont été vérifiés le 22 octobre 2026 ; utilisez la liste de prix en direct pour vos décisions d’approvisionnement et de déploiement.

La page de tarification d’Ollama décrit également une tarification en heures creuses pour les entrées éligibles. N’établissez pas un budget à partir du seul libellé d’un modèle : utilisez la ligne tarifaire applicable à l’itinéraire, au modèle et au moment réels.

Une estimation mensuelle pratique est la suivante :

monthly_cloud_cost =
  (input_tokens / 1,000,000 × input_rate)
+ (cached_input_tokens / 1,000,000 × cached_input_rate)
+ (output_tokens / 1,000,000 × output_rate)

Par exemple, aux tarifs publiés ci-dessus pour gpt-oss:20b, 1 million de tokens d’entrée non mis en cache, plus 250 000 tokens de sortie, donnent une estimation de $0.145 avant toute modification tarifaire ou tout crédit spécifique au compte. Pour les prévisions de production, utilisez la télémétrie de tokens observée, et non une longueur de conversation estimée.

Guide de production : sécurisez le serveur local avant de l’exposer

La règle de production la plus importante pour l’API compatible OpenAI d’Ollama est simple : un serveur Ollama local n’est pas authentifié par défaut.

Ollama se lie par défaut à 127.0.0.1:11434. Sa documentation indique que OLLAMA_HOST peut modifier l’adresse de liaison et qu’un proxy tel que Nginx peut transmettre le trafic au serveur. Ce sont des options d’implémentation, et non de l’authentification. Si vous étendez le service au-delà de localhost, mettez en place des contrôles délibérés autour de celui-ci.

Liste de contrôle pour la production

1. Conservez la liaison de bouclage par défaut, sauf si vous disposez d’un chemin d’accès défini. N’exposez pas directement le port 11434 à Internet.
2. Placez TLS et l’authentification à la périphérie. Utilisez un proxy inverse, un réseau privé, une identité de service et une autorisation par client adaptés à votre environnement. Une clé factice du SDK OpenAI n’est pas un contrôle d’accès.
3. Autorisez les origines de navigateur de façon restrictive. Ollama documente OLLAMA_ORIGINS pour les origines supplémentaires autorisées. Ajoutez uniquement les origines exactes des applications web ou extensions nécessitant l’accès ; n’en faites pas un contournement global des règles cross-origin.
4. Utilisez une liste d’autorisation de modèles. Traitez le model demandé comme une entrée à valider. Les appelants en production ne doivent pas pouvoir récupérer des modèles arbitraires ou sélectionner des modèles non examinés.
5. Définissez une politique de file d’attente et gérez les surcharges. Ollama indique qu’un serveur surchargé peut renvoyer HTTP 503 et expose OLLAMA_MAX_QUEUE. Utilisez des nouvelles tentatives limitées avec un backoff exponentiel et du jitter, puis renvoyez un échec contrôlé à l’appelant.
6. Planifiez conjointement la capacité VRAM et la concurrence. OLLAMA_NUM_PARALLEL augmente le parallélisme par modèle, mais les besoins en mémoire augmentent avec lui. OLLAMA_MAX_LOADED_MODELS et OLLAMA_KEEP_ALIVE déterminent avec quelle agressivité les modèles occupent la mémoire.
7. Instrumentez les chemins qui comptent. Suivez la latence, le temps d’attente en file, les HTTP 503, l’inventaire des modèles actifs, la taille des requêtes, les déconnexions de flux, les erreurs d’appel d’outils et la pression sur la mémoire GPU/CPU. ollama ps aide à vérifier où s’exécutent les modèles chargés.
8. Testez les redémarrages et les démarrages à froid. Un modèle local peut nécessiter un temps de chargement après un déploiement ou une éviction. Effectuez des exercices de charge, de retour arrière et de délai d’expiration avant que l’API ne prenne en charge un flux de travail destiné aux clients.
9. Ne laissez pas les secrets dans les clients. En mode cloud, stockez OLLAMA_API_KEY dans un gestionnaire de secrets côté serveur ou dans un environnement d’exécution protégé, et non dans un bundle frontend.
10. Épinglez la suite d’acceptation, pas seulement la version de la dépendance. Réexécutez les tests de chat, de streaming, d’outils, de JSON, de vision et d’état de réponse chaque fois que vous mettez à niveau Ollama, changez de modèle ou modifiez la couche de routage.

La FAQ d’Ollama documente l’adresse de liaison, la configuration CORS, le comportement de la file d’attente, les paramètres de concurrence et les contrôles local/cloud qui sous-tendent ces recommandations.

Un chemin de déploiement plus sûr

Utilisez cette séquence pour une application qui démarre localement et peut ensuite utiliser des modèles hébergés :

1. Validez le point de terminaison local. Téléchargez un modèle, listez les modèles et envoyez une complétion de chat sans streaming.
2. Stabilisez la configuration du client OpenAI. Faites de l’URL de base, de la clé API et du modèle des variables d’environnement, et non des littéraux dispersés dans le codebase.
3. Créez une suite de compatibilité. Incluez la sortie JSON, le streaming, chaque schéma d’outil, les entrées de vision lorsqu’elles sont pertinentes, le comportement en cas de délai d’expiration et les requêtes malformées.
4. Testez la charge de l’hôte. Enregistrez la latence, la profondeur de file d’attente, la VRAM/RAM et le point à partir duquel les 503 commencent.
5. Ajoutez une périphérie authentifiée avant tout accès distant. Gardez Ollama privé derrière le service applicatif ou un proxy de confiance.
6. Évaluez le mode cloud séparément. Utilisez une clé cloud dédiée, des modèles autorisés par liste blanche, des alertes budgétaires et des cas de test couvrant les limitations propres aux Responses dans le cloud.
7. Découplez le choix du fournisseur de la logique métier. Si un produit doit comparer des modèles hébergés ou ajouter une route de secours, conservez le contrat du client OpenAI derrière un petit adaptateur.

Pour la dernière étape, une checklist de migration de passerelle API compatible OpenAI peut vous aider à séparer l’intégration client de la sélection du fournisseur de modèles. Si vous souhaitez évaluer plusieurs fournisseurs hébergés sans ajouter un nouveau modèle de client pour chacun, consultez le guide de démarrage rapide de l’API Flatkey et le guide pour déterminer quand une passerelle API d’IA est utile.

Erreurs fréquentes avec l’API compatible OpenAI d’Ollama

Traiter un serveur localhost comme un service sécurisé

Une requête locale peut fonctionner parce que le processus se trouve sur la même machine, et non parce que l’accès est authentifié. Dès qu’une adresse de liaison, un tunnel, un proxy ou un port de conteneur change, réévaluez l’identité, la politique réseau, TLS et la journalisation d’audit.

Supposer une parité fonctionnelle avec OpenAI

Ollama prend explicitement en charge un sous-ensemble de l’API OpenAI. Intégrez une vérification des capacités dans la CI et testez la sémantique, pas seulement une réponse 200. Une définition d’outil qui est analysée localement peut se comporter différemment après un changement de modèle.

Utiliser les libellés de prix cloud comme budget

Les tarifs des entrées, des entrées mises en cache et des sorties peuvent différer considérablement. Journalisez les champs de jetons, calculez le coût effectif par tâche réussie et vérifiez à nouveau la page tarifaire avant de vous engager sur un budget fixe.

Augmenter le parallélisme sans modèle de mémoire

Davantage de requêtes parallèles peuvent accroître les besoins en contexte et en mémoire. Surveillez la pression réelle sur l’hôte avec des prompts représentatifs avant de modifier les paramètres de concurrence.

Donner une clé cloud au navigateur

Un appel direct du navigateur vers le cloud rend la rotation des clés, le contrôle du budget et la prévention des abus beaucoup plus difficiles. Conservez la clé cloud dans un backend de confiance et n’exposez que l’opération nécessaire à votre application.

FAQ

L’API compatible OpenAI d’Ollama est-elle identique à l’API OpenAI ?

Non. La couche de compatibilité d’Ollama prend en charge un sous-ensemble documenté de l’API OpenAI afin que les clients compatibles puissent se connecter à Ollama. Confirmez les points de terminaison et champs individuels dans la référence de compatibilité d’Ollama avant de considérer une fonctionnalité comme portable.

L’API Ollama locale nécessite-t-elle une clé API ?

Non. Ollama indique que l’API locale ne requiert pas d’authentification. La valeur api_key="ollama" dans les exemples de SDK est une exigence de client non vide, et non un identifiant. Gardez le serveur local sur localhost ou ajoutez de véritables contrôles avant une exposition distante.

Ollama Cloud nécessite-t-il une clé API ?

Oui. L’accès direct au cloud à https://ollama.com/v1 requiert une clé API transmise sous forme de jeton Bearer. Stockez-la côté serveur.

Puis-je utiliser /v1/responses ?

Oui, pour les requêtes Responses sans état. Ne vous appuyez pas sur previous_response_id ni sur conversation. La documentation cloud souligne également des limitations concernant la recherche web intégrée et la relecture des appels d’outils personnalisés/libres.

L’API compatible OpenAI d’Ollama est-elle gratuite ?

L’inférence locale n’entraîne pas de frais cloud Ollama par jeton, mais vous payez toujours le matériel et les opérations que vous exécutez. L’inférence cloud directe utilise une tarification publiée par jeton et des crédits de compte.

Quand devrais-je utiliser une passerelle à la place ?

Utilisez Ollama directement lorsque la route locale/cloud répond aux besoins du workload en matière de modèles, de confidentialité et d’exploitation. Envisagez une passerelle lorsque votre produit nécessite une intégration cohérente entre plusieurs fournisseurs hébergés, un workflow d’évaluation de modèles ou un chemin de secours distinct. Commencez par une décision claire concernant une API d’IA unifiée, puis conservez le même adaptateur client au niveau de l’application.

Conclusion

L’API compatible OpenAI d’Ollama offre aux développeurs un moyen pratique de réutiliser un SDK OpenAI avec des modèles servis localement ou dans le cloud. Une implémentation sûre ne se limite pas à modifier l’URL de base : elle repose sur une matrice de capacités testée, un modèle de coûts local versus cloud clair, une limite de déploiement local privée et un plan testé en charge pour les files d’attente et la mémoire des modèles.

Commencez en local si vous avez besoin de contrôle et pouvez exploiter le matériel. Utilisez le cloud direct lorsque vous souhaitez une inférence hébergée via la même interface client. Dans les deux cas, gardez le choix du point de terminaison configurable et veillez à ce que chaque fonctionnalité prise en charge justifie sa place dans votre suite de tests de production.