OpenAI-kompatible API mit Ollama

Was dieser Artikel über die OpenAI-kompatible API von Ollama behandelt

• Welche Endpunkte Ollama im OpenAI-Format anbietet.
• Wie man bestehenden OpenAI-Code auf Ollama umstellt.
• Unterschiede und Einschränkungen.
• Beispiele in Python und curl.
• Tipps für den produktiven Einsatz.

Einleitung: OpenAI-kompatible API mit Ollama

Ollama bietet nicht nur eine eigene API, sondern auch Endpunkte, die dem OpenAI-Format entsprechen. Das ist besonders praktisch, wenn man bereits Anwendungen mit der OpenAI-Client-Bibliothek gebaut hat und diese auf eine lokale Ollama-Instanz umstellen möchte. Statt api.openai.com wird einfach die lokale Ollama-Adresse mit dem Pfad /v1 verwendet.

Dieser Artikel zeigt, welche Endpunkte verfügbar sind, wie die Migration funktioniert und worauf man achten muss.

Wichtige Begriffe

• OpenAI API: Schnittstelle von OpenAI für Chat, Completions und Embeddings.
• OpenAI-kompatibler Endpunkt: API, die das OpenAI-Schema nachbildet.
• /v1: Pfad bei Ollama für OpenAI-kompatible Anfragen.
• Chat Completions: Mehrturnige Konversationen.
• Embeddings: Vektor-Darstellungen von Text.
• API-Key: Authentifizierungsschlüssel, bei Ollama oft ein Platzhalter.
• Base URL: Adresse der API, zum Beispiel http://localhost:11434/v1.

Verfügbare Endpunkte

Ollama implementet viele OpenAI-Endpunkte:

• POST /v1/chat/completions für Chat.
• POST /v1/completions für Textvervollständigung.
• POST /v1/embeddings für Embeddings.
• GET /v1/models zum Auflisten von Modellen.

Nicht alle OpenAI-Features wie functions, tools oder vision sind in jedem Modell verfügbar. Das hängt vom Modell und der Ollama-Version ab.

Endpunkt-Adresse

http://localhost:11434/v1

Für ein Ollama auf einem anderen Rechner:

http://ollama-server.local:11434/v1

Python-Beispiel mit OpenAI-Client

pip install openai

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"
)

response = client.chat.completions.create(
    model="llama3.1",
    messages=[
        {"role": "user", "content": "Erkläre Ollama in drei Sätzen."}
    ]
)

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

Streaming

stream = client.chat.completions.create(
    model="llama3.1",
    messages=[{"role": "user", "content": "Erzähle mir einen Witz."}],
    stream=True
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Embeddings

response = client.embeddings.create(
    model="nomic-embed-text",
    input="Ollama ist eine lokale KI-Plattform."
)

print(response.data[0].embedding[:5])

curl-Beispiel

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.1",
    "messages": [
      {"role": "user", "content": "Hallo Ollama"}
    ]
  }'

Modelle auflisten

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

Unterschiede zur echten OpenAI API

• Authentifizierung: Ollama braucht keinen echten API-Key, erwartet aber einen beliebigen Wert.
• Rate-Limiting: Lokal meist nicht vorhanden.
• Modellnamen: OpenAI-Modellnamen müssen durch Ollama-Modelle ersetzt werden.
• Tools / Functions: Nicht jedes Modell unterstützt Function Calling.
• Vision: Nur bestimmte multimodale Modelle wie llava unterstützen Bilder.
• Streaming: Wird in der Regel unterstützt.
• RAG: Muss in der Anwendung selbst implementiert werden.

Bestehende Anwendung migrieren

Schritte:

1. base_url auf http://localhost:11434/v1 setzen.
2. api_key auf einen beliebigen Wert wie "ollama" setzen.
3. OpenAI-Modellnamen durch Ollama-Namen ersetzen.
4. Features prüfen, die Ollama noch nicht unterstützt.
5. Fehlerbehandlung anpassen, da Fehlermeldungen anders aussehen können.

Wann ist die OpenAI-API nützlich?

• Bestehender Code soll schnell lokal laufen.
• Anwendungen sollen ohne grossen Umbau datenschutzfreundlich werden.
• Vergleich zwischen OpenAI und lokalen Modellen.
• Prototypen, die später auf Ollama produktiv gehen.

Wann lieber die native Ollama API?

• Wenn alle Ollama-Features wie Modelfiles, Pull, Delete und Generate genutzt werden.
• Wenn spezifische Ollama-Erweiterungen gebraucht werden.
• Wenn die Anwendung ursprünglich für Ollama entwickelt wird.

Sicherheit

• Ollama standardmässig ohne Authentifizierung.
• Nicht öffentlich ins Internet stellen.
• Bei Bedarf Reverse Proxy mit Authentifizierung davor schalten.
• API-Key im Client kein echtes Secret, sondern Platzhalter.
• Kommunikation im lokalen Netzwerk oder über VPN/Tailscale abwickeln.

Typische Stolpersteine

• Falscher Port: Standard ist 11434.
• Modell nicht heruntergeladen: ollama pull llama3.1 vorher ausführen.
• api_key fehlt: OpenAI-Client braucht einen Wert, auch wenn Ollama ihn ignoriert.
• Falsche Endpunkte: /v1/chat/completions, nicht /api/chat.
• Vision-Modelle: Nicht jedes Modell verarbeitet Bilder.
• Tools nicht unterstützt: Modell muss Function Calling können.
• CORS-Probleme: Browser-Anfragen an localhost können blockiert werden.

Weiterführende Links und Infos

• BotServ.de Ollama REST API
• BotServ.de Ollama API-Bibliotheken
• BotServ.de Ollama Sicherheit
• BotServ.de Docker Reverse Proxy

FAQ: OpenAI-kompatible API mit Ollama

Brauche ich einen echten OpenAI API-Key? Nein, ein beliebiger Wert wie ollama reicht.

Sind alle OpenAI-Features verfügbar? Nein, Tools, Vision und bestimmte Parameter hängen vom Modell ab.

Kann ich Streaming nutzen? Ja, in der Regel wird Streaming über SSE unterstützt.

Welche Modelle funktionieren? Alle lokalen Ollama-Modelle, die über den Namen angesprochen werden.

Ist die API identisch mit OpenAI? Fast, aber es gibt Einschränkungen und abweichende Fehlermeldungen.

Quellen und weiterführende Literatur

• Ollama OpenAI Compatibility: https://ollama.com/blog/openai-compatibility
• OpenAI API Reference: https://platform.openai.com/docs/api-reference
• Ollama API Docs: https://github.com/ollama/ollama/blob/main/docs/api.md

Zusammenfassung: OpenAI-kompatible API mit Ollama

Ollamas /v1 Endpunkte ermöglichen es, bestehenden OpenAI-Code fast unverändert lokal laufen zu lassen. Wer die base_url auf http://localhost:11434/v1 und den API-Key auf einen Platzhalter setzt, kann Modelle wie llama3.1 oder qwen2.5 statt OpenAI-Modellen verwenden. Wichtig sind Modellverfügbarkeit, fehlende Features wie Tools oder Vision und die Absicherung der lokalen Ollama-Instanz. Für reine Ollama-Features ist die native API weiterhin die bessere Wahl, aber für Migrationen und Prototypen ist die OpenAI-Kompatibilität sehr praktisch.