Ollama OpenAI-kompatible API: Zugriff, Preise, Integration und Produktionsleitfaden

Ollama OpenAI-kompatible API: Zugriff, Preise, Integration und Produktionsleitfaden

Die Ollama OpenAI-kompatible API ermöglicht es einer Anwendung, die vertraute Struktur des OpenAI SDK beizubehalten und gleichzeitig Anfragen entweder an einen lokalen Ollama-Server oder direkt an Ollama Cloud zu senden. Das ist nützlich, aber keine Zusage vollständiger Funktionsparität: Ollama dokumentiert die Unterstützung für einen Teilbereich der OpenAI API, und einige Funktionen hängen vom gewählten Endpunkt und Modell ab.

Dieser Leitfaden zeigt, wie Sie auf diese Schnittstelle zugreifen, sie in einer bestehenden Python- oder JavaScript-Anwendung konfigurieren, Cloud- und lokale Kosten verstehen und klare Grenzen für den Produktionseinsatz setzen.

Kurzantwort: Verwenden Sie http://localhost:11434/v1/ für einen lokalen Ollama-Server und einen vom SDK benötigten Platzhalter-API-Schlüssel, der von Ollama ignoriert wird. Verwenden Sie https://ollama.com/v1 zusammen mit OLLAMA_API_KEY für den direkten Cloud-Zugriff. Prüfen Sie den genauen Endpunkt und das Modell, bevor Sie sich auf Streaming, Vision, Tools, strukturierte Ausgabe oder das Verhalten der Responses API verlassen.

Was bedeutet „OpenAI-kompatibel“ für Ollama?

Dies ist eine Integrationsoberfläche für OpenAI-Clients, keine von OpenAI gehostete API. Sie ermöglicht es Ihnen, kompatible Clients auf Ollama-Basis-URLs zu verweisen und unterstützte Routen wie Chat Completions, Embeddings, Modellerkennung und zustandslose Responses-Anfragen zu verwenden.

Ollamas Kompatibilitätsreferenz ist die maßgebliche Quelle für den unterstützten Teilbereich. Insbesondere:

• /v1/chat/completions unterstützt Funktionen wie Streaming, JSON-Modus, Vision, Tools, reproduzierbare Ausgaben, Logprobs und Steuerelemente, die nur für kompatible Modelle gelten.
• /v1/embeddings unterstützt Zeichenketten- und Array-Eingaben.
• /v1/models und /v1/models/{model} unterstützen die Modellerkennung, aber einige zurückgegebene Felder haben Ollama-spezifische Bedeutungen.
• POST /v1/responses ist verfügbar, jedoch zustandslos: Verlassen Sie sich nicht auf previous_response_id oder conversation.

Lesen Sie die aktuelle Ollama-OpenAI-Kompatibilitätsreferenz, bevor Sie eine Funktion in der Produktion aktivieren. „Kompatibel“ sollte als Grund dienen, Ihren Client und Ihre Anfrageform wiederzuverwenden – nicht als Grund, Funktionstests zu überspringen.

Zugriff auf die Ollama OpenAI-kompatible API: lokal gegenüber Cloud

Die einfachste Implementierungsentscheidung besteht darin, ob die Inferenz auf Ihrer eigenen Maschine ausgeführt wird oder Ollamas Cloud-Endpunkt erreicht.

Diese Aufteilung wird in Ollamas API-Einführung und Authentifizierungsleitfaden dokumentiert. Direkte Cloud-Aufrufe erfordern einen API-Schlüssel. Lokale Aufrufe nicht.

Lokale Einrichtung

Installieren Sie Ollama und laden Sie dann das Modell herunter, das Sie verwenden möchten. Die Ollama-Dokumentation zeigt das allgemeine Muster:

ollama pull gpt-oss:20b
ollama serve

Prüfen Sie nun, ob der lokale Endpunkt Modelle auflisten kann:

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

Wenn diese Verbindung fehlschlägt, beheben Sie das Problem mit dem lokalen Server, bevor Sie den Anwendungscode ändern. Eine Client-Migration lässt sich wesentlich leichter debuggen, wenn die API-Basis-URL und das Modellinventar bereits unabhängig funktionieren.

Direkte Cloud-Einrichtung

Erstellen Sie für die direkte Cloud-Nutzung einen API-Schlüssel in Ihrem Ollama-Konto und legen Sie ihn in einer Umgebungsvariable ab:

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

Die Cloud-Basis-URL lautet https://ollama.com/v1. Ollama dokumentiert, dass seine gehostete API Authorization: Bearer verwendet; legen Sie keinen langlebigen Schlüssel in Browser-Code, ein Repository oder eine clientseitige Konfigurationsdatei.

Integrieren Sie die Ollama OpenAI-kompatible API mit dem OpenAI SDK

Der Migrationspunkt ist die Client-Konfiguration. Halten Sie Anwendungsmeldungen und Fehlerbehandlung hinter Ihrer eigenen Schnittstelle, und tauschen Sie dann nur die Konfiguration für Basis-URL, Schlüssel und Modell aus.

Python: lokaler Server

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)

Der lokale Endpunkt authentifiziert Anfragen nicht. Der Platzhalterschlüssel existiert nur, weil der OpenAI-Client einen Wert erwartet; er schützt den lokalen Server nicht.

Python: direkte Cloud

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)

Die Code-Struktur ist bewusst ähnlich. Der operative Unterschied ist jedoch erheblich: Direkte Cloud-Aufrufe hängen von einem API-Schlüssel und dem gewählten Cloud-Modell ab; lokale Aufrufe hängen von einem heruntergeladenen Modell und den auf dem Host verfügbaren Ressourcen ab.

JavaScript: Endpunkt konfigurierbar halten

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);

Legen Sie Umgebungsvariablen pro Bereitstellung fest:

# 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

Diese Konfiguration macht eine spätere Änderung von Route oder Modell explizit und überprüfbar. Sie verhindert außerdem, dass eine umgebungsspezifische Basis-URL zu verborgenem Anwendungsverhalten wird.

Kompatibilitätsmatrix: Was Sie vor der Auslieferung testen sollten

Die Ollama OpenAI-kompatible API ist besonders nützlich, wenn Sie Kompatibilität als Testplan und nicht als Annahme behandeln.

Zwei Details überraschen Teams häufig:

1. Der Zustand gehört in Ihre Anwendung. Ihre App sollte die benötigten Nachrichten oder den Gesprächszustand speichern, statt zustandsbehaftetes Responses-Verhalten von Ollama zu erwarten.
2. Ein Modellname ist keine Fähigkeitsgarantie. Eine Anfrage kann einen kompatiblen Endpunkt verwenden und dennoch nicht die Qualität oder das Tool-Verhalten liefern, das ein Workflow benötigt. Testen Sie Modell, Prompt-Größe, Ausgabelimits und Tools gemeinsam.

Wenn eine bestehende Integration einen standardmäßigen OpenAI-Modellnamen fest einprogrammiert, dokumentiert Ollama ollama cp als Möglichkeit, einen temporären lokalen Modellalias zu erstellen. Verwenden Sie dies nur als bewusst gewählten Kompatibilitäts-Shim, dokumentieren Sie den Alias und entfernen Sie ihn, sobald Ihre Konfiguration explizit ist.

Ollama-Preise: lokale Gesamtbetriebskosten im Vergleich zu Cloud-Tokenraten

Die Preisgestaltung für die Ollama OpenAI-kompatible API hängt von der Route ab.

Lokale Inferenz ist keine Tokenabrechnung – aber nicht kostenlos

Der Betrieb eines lokalen Modells erzeugt keine Ollama-Cloud-Rechnung pro Token. Er führt jedoch zu einem Betriebs-Kostenprofil:

• GPU- oder CPU-Kapazität, RAM/VRAM, Speicher und Abschreibung der Hardware
• Strom und Kühlung
• Zeit zum Herunterladen des Modells und Speicher für Images
• Kapazitätsplanung, Monitoring, Patching und Incident Response
• Die Opportunitätskosten, ein Modell für Anfragen mit niedriger Latenz im Speicher warmzuhalten

Für einen einzelnen Entwickler kann dies ein ausgezeichneter Kompromiss sein. Für ein Produkt mit schwankendem Datenverkehr oder mehreren Modellen sollten Sie neben den reinen Inferenzkosten auch die Hardwareauslastung und den Aufwand für die Zuverlässigkeit berechnen.

Direkte Cloud-Preise werden pro Million Tokens veröffentlicht

Ollamas aktuelle Preisseite führt Cloud-Tarife pro einer Million Tokens auf, einschließlich separater Preise für Eingabe, zwischengespeicherte Eingabe und Ausgabe. Die folgenden Beispiele wurden am 22. Oktober 2026 geprüft; verwenden Sie für Beschaffungs- und Bereitstellungsentscheidungen die aktuelle Preisliste.

Ollamas Preisseite beschreibt auch Preise außerhalb der Spitzenzeiten für berechtigte Einträge. Erstellen Sie kein Budget allein anhand einer Modellbezeichnung: Verwenden Sie die Preiszeile, die für die tatsächliche Route, das Modell und den Zeitpunkt gilt.

Eine praktische monatliche Schätzung lautet:

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)

Bei den oben veröffentlichten Tarifen für gpt-oss:20b ergeben beispielsweise 1 Million nicht zwischengespeicherte Eingabe-Tokens plus 250.000 Ausgabe-Tokens geschätzte $0.145, bevor Preisänderungen oder kontospezifische Gutschriften berücksichtigt werden. Verwenden Sie für eine Produktionsprognose beobachtete Token-Telemetrie statt geschätzter Chat-Länge.

Produktionsleitfaden: Sichern Sie den lokalen Server, bevor Sie ihn verfügbar machen

Die wichtigste Produktionsregel für die Ollama OpenAI-kompatible API ist einfach: Ein lokaler Ollama-Server ist standardmäßig nicht authentifiziert.

Ollama bindet standardmäßig an 127.0.0.1:11434. Die Dokumentation zeigt, dass OLLAMA_HOST die Bindungsadresse ändern kann und dass ein Proxy wie Nginx Datenverkehr an den Server weiterleiten kann. Dies sind Implementierungsoptionen – keine Authentifizierung. Wenn Sie den Dienst über localhost hinaus verfügbar machen, richten Sie bewusst entsprechende Kontrollen ein.

Checkliste für die Produktion

1. Behalten Sie die standardmäßige Loopback-Bindung bei, sofern Sie keinen definierten Zugriffspfad haben. Stellen Sie Port 11434 nicht direkt im Internet bereit.
2. Setzen Sie TLS und Authentifizierung am Edge um. Verwenden Sie einen Reverse Proxy, ein privates Netzwerk, Dienstidentitäten und eine pro Client geeignete Autorisierung für Ihre Umgebung. Ein Platzhalter-Schlüssel des OpenAI SDK ist keine Zugriffskontrolle.
3. Beschränken Sie Browser-Ursprünge eng. Ollama dokumentiert OLLAMA_ORIGINS für zusätzliche erlaubte Ursprünge. Fügen Sie nur die exakten Ursprünge der Web-App oder Erweiterung hinzu, die Zugriff benötigen; machen Sie daraus keine pauschale Umgehung von Cross-Origin-Beschränkungen.
4. Verwenden Sie eine Modell-Allowlist. Behandeln Sie das angeforderte model als Eingabe, die Sie validieren. Produktionsaufrufer sollten weder beliebige Modelle abrufen noch ungeprüfte Modelle auswählen können.
5. Legen Sie eine Warteschlangenrichtlinie fest und behandeln Sie Überlastungen. Ollama dokumentiert, dass ein überlasteter Server HTTP 503 zurückgeben kann, und stellt OLLAMA_MAX_QUEUE bereit. Verwenden Sie begrenzte Wiederholungsversuche mit exponentiellem Backoff und Jitter und geben Sie dem Aufrufer anschließend einen kontrollierten Fehler zurück.
6. Planen Sie VRAM-Kapazität und Parallelität gemeinsam. OLLAMA_NUM_PARALLEL erhöht die Parallelität pro Modell, doch der Speicherbedarf wächst damit. OLLAMA_MAX_LOADED_MODELS und OLLAMA_KEEP_ALIVE bestimmen, wie aggressiv Modelle Speicher belegen.
7. Instrumentieren Sie die relevanten Pfade. Verfolgen Sie Latenz, Warteschlangenzeit, HTTP-503-Antworten, Inventar aktiver Modelle, Anfragegröße, Stream-Trennungen, Tool-Call-Fehler sowie GPU-/CPU-Speicherdruck. ollama ps hilft zu prüfen, wo geladene Modelle ausgeführt werden.
8. Testen Sie Neustarts und Kaltstarts. Ein lokales Modell kann nach einer Bereitstellung oder Auslagerung Ladezeit benötigen. Führen Sie Last-, Rollback- und Timeout-Übungen durch, bevor die API einen kundenorientierten Workflow unterstützt.
9. Halten Sie Geheimnisse aus Clients heraus. Speichern Sie für den Cloud-Modus OLLAMA_API_KEY in einem serverseitigen Secret Manager oder einer geschützten Laufzeitumgebung – nicht in einem Frontend-Bundle.
10. Pinnen Sie die Abnahmetests, nicht nur die Abhängigkeitsversion. Führen Sie Chat-, Streaming-, Tool-, JSON-, Vision- und Response-State-Tests erneut aus, wenn Sie Ollama aktualisieren, ein Modell ändern oder die Routing-Schicht anpassen.

Ollamas FAQ dokumentiert die Bindungsadresse, die CORS-Konfiguration, das Warteschlangenverhalten, Parallelitätseinstellungen und die lokalen/Cloud-Steuerungen hinter diesen Empfehlungen.

Ein sichererer Einführungsweg

Verwenden Sie diese Reihenfolge für eine Anwendung, die lokal beginnt und später möglicherweise gehostete Modelle verwendet:

1. Prüfen Sie den lokalen Endpunkt. Laden Sie ein Modell herunter, listen Sie Modelle auf und senden Sie eine nicht streamende Chat-Abschlussanfrage.
2. Stabilisieren Sie die OpenAI-Client-Konfiguration. Verwenden Sie Umgebungsvariablen für Basis-URL, API-Schlüssel und Modell – keine Literale, die über die gesamte Codebasis verteilt sind.
3. Erstellen Sie eine Kompatibilitätssuite. Beziehen Sie JSON-Ausgabe, Streaming, jedes Tool-Schema, gegebenenfalls Vision-Eingaben, Timeout-Verhalten und fehlerhafte Anfragen ein.
4. Führen Sie Lasttests auf dem Host durch. Erfassen Sie Latenz, Warteschlangentiefe, VRAM/RAM und den Punkt, ab dem 503-Fehler auftreten.
5. Fügen Sie vor dem Remotezugriff eine authentifizierte Edge-Schicht hinzu. Halten Sie Ollama hinter dem Anwendungsdienst oder einem vertrauenswürdigen Proxy privat.
6. Bewerten Sie den Cloud-Modus separat. Verwenden Sie einen dedizierten Cloud-Schlüssel, zugelassene Modelle, Budgetwarnungen und Testfälle, die die cloud-spezifischen Responses-Einschränkungen abdecken.
7. Entkoppeln Sie die Anbieterauswahl von der Geschäftslogik. Wenn ein Produkt gehostete Modelle vergleichen oder eine Fallback-Route hinzufügen muss, halten Sie den OpenAI-Client-Vertrag hinter einem kleinen Adapter.

Für den letzten Schritt kann eine Checkliste für die Migration zu einem OpenAI-kompatiblen API-Gateway Ihnen helfen, die Client-Integration von der Auswahl des Modellanbieters zu trennen. Wenn Sie mehrere gehostete Anbieter bewerten möchten, ohne für jeden ein neues Client-Muster hinzuzufügen, lesen Sie den Flatkey API-Schnellstart und den Leitfaden dazu, wann ein KI-API-Gateway sinnvoll ist.

Häufige Fehler bei der Ollama OpenAI-kompatiblen API

Einen localhost-Server wie einen abgesicherten Dienst behandeln

Eine lokale Anfrage kann funktionieren, weil der Prozess auf demselben Rechner läuft, nicht weil der Zugriff authentifiziert ist. Sobald sich eine Bind-Adresse, ein Tunnel, ein Proxy oder ein Container-Port ändert, sollten Sie Identität, Netzwerkrichtlinie, TLS und Audit-Protokollierung erneut prüfen.

Von vollständiger OpenAI-Funktionsparität ausgehen

Ollama unterstützt ausdrücklich eine Teilmenge der OpenAI API. Integrieren Sie eine Funktionsprüfung in die CI und testen Sie die Semantik – nicht nur eine 200-Antwort. Eine Tool-Definition, die lokal geparst wird, kann sich nach einem Modellwechsel anders verhalten.

Cloud-Preisangaben als Budget verwenden

Tarife für Eingaben, zwischengespeicherte Eingaben und Ausgaben können erheblich voneinander abweichen. Protokollieren Sie Token-Felder, berechnen Sie die effektiven Kosten pro erfolgreich abgeschlossener Aufgabe und prüfen Sie die Preisseite erneut, bevor Sie sich auf ein festes Budget festlegen.

Parallelität ohne Speichermodell erhöhen

Mehr parallele Anfragen können die Kontext- und Speicheranforderungen erhöhen. Beobachten Sie die tatsächliche Auslastung des Hosts bei repräsentativen Prompts, bevor Sie die Parallelitätseinstellungen ändern.

Dem Browser einen Cloud-Schlüssel geben

Ein direkter Aufruf vom Browser zur Cloud erschwert Schlüsselrotation, Budgetkontrolle und Missbrauchsprävention erheblich. Bewahren Sie den Cloud-Schlüssel in einem vertrauenswürdigen Backend auf und stellen Sie nur die Operation bereit, die Ihre Anwendung benötigt.

FAQ

Ist Ollamas OpenAI-kompatible API dieselbe wie die OpenAI API?

Nein. Ollamas Kompatibilitätsschicht unterstützt eine dokumentierte Teilmenge der OpenAI API, damit kompatible Clients eine Verbindung zu Ollama herstellen können. Prüfen Sie einzelne Endpunkte und Felder in Ollamas Kompatibilitätsreferenz, bevor Sie eine Funktion als portabel behandeln.

Benötigt die lokale Ollama API einen API-Schlüssel?

Nein. Laut Ollama erfordert die lokale API keine Authentifizierung. Der Wert api_key="ollama" in SDK-Beispielen ist eine Anforderung des Clients an einen nicht leeren Wert, keine Zugangsdaten. Behalten Sie den lokalen Server auf localhost oder fügen Sie vor einer Remote-Exposition echte Kontrollen hinzu.

Benötigt Ollama Cloud einen API-Schlüssel?

Ja. Direkter Cloud-Zugriff auf https://ollama.com/v1 erfordert einen API-Schlüssel, der als Bearer-Token übergeben wird. Speichern Sie ihn serverseitig.

Kann ich /v1/responses verwenden?

Ja, für zustandslose Responses-Anfragen. Verlassen Sie sich nicht auf previous_response_id oder conversation. Die Cloud-Dokumentation weist außerdem auf Einschränkungen bei der integrierten Websuche und bei der Wiedergabe benutzerdefinierter/freiformatiger Tool-Aufrufe hin.

Ist die Ollama OpenAI-kompatible API kostenlos?

Für lokale Inferenz fallen keine Ollama-Cloud-Gebühren pro Token an, Sie zahlen jedoch weiterhin für die Hardware und den Betrieb. Direkte Cloud-Inferenz verwendet veröffentlichte Preise pro Token und Kontoguthaben.

Wann sollte ich stattdessen ein Gateway verwenden?

Verwenden Sie Ollama direkt, wenn die lokale/Cloud-Route die Modell-, Datenschutz- und Betriebsanforderungen der Arbeitslast erfüllt. Ziehen Sie ein Gateway in Betracht, wenn Ihr Produkt eine konsistente Integration über mehrere gehostete Anbieter hinweg, einen Modellbewertungs-Workflow oder einen separaten Fallback-Pfad benötigt. Beginnen Sie mit einer klaren Entscheidung für eine vereinheitlichte KI-API und behalten Sie anschließend denselben Client-Adapter auf Anwendungsebene bei.

Fazit

Die Ollama OpenAI-kompatible API bietet Entwicklern eine praktische Möglichkeit, ein OpenAI SDK mit lokalen oder über die Cloud bereitgestellten Modellen wiederzuverwenden. Eine sichere Implementierung ist nicht nur eine Änderung der Basis-URL: Sie umfasst eine getestete Funktionsmatrix, ein klares Kostenmodell für lokal gegenüber Cloud, eine private lokale Bereitstellungsgrenze und einen lastgetesteten Plan für Warteschlangen und Modellspeicher.

Starten Sie lokal, wenn Sie Kontrolle benötigen und die Hardware betreiben können. Nutzen Sie die direkte Cloud, wenn Sie gehostete Inferenz über dieselbe Client-Struktur wünschen. Halten Sie in beiden Fällen die Endpunktwahl konfigurierbar und lassen Sie jede unterstützte Funktion ihren Platz in Ihrer Produktions-Testsuite verdienen.