Ollama-API-Aufrufe: Von curl bis zur OpenAI-SDK-kompatiblen Schnittstelle

Der curl-Befehl im Terminal – und im JSON steckt nur ein halbes Wort. Zwei Stunden später war klar: Streaming-Antwort. Ollama liefert standardmäßig Inhalt stückweise aus, jedes JSON-Objekt enthält nur wenige Zeichen.

Beim lokalen LLM-Deployment senkt Ollama die Hürde: Herunterladen, installieren, starten – drei Schritte. Bei der API wird es unübersichtlich: Was unterscheidet native REST-API und OpenAI-SDK-Kompatibilität? Wie verarbeitet man Streaming?

Dieser Artikel fasst die Stolpersteine zusammen – von curl bis zur OpenAI-SDK-Migration ohne Codeänderung, plus Details, die in der Doku leicht übersehen werden.

Zwei Ollama-API-Schnittstellen

Das hat mich eine Weile verwirrt: Ollama bietet zwei grundverschiedene API-Varianten:

Native REST-API: http://localhost:11434/api/*

• Endpunkte: /api/generate (Textgenerierung), /api/chat (Dialog), /api/tags (Modellliste)
• Standardmäßig Streaming (genau das Problem um drei Uhr nachts)
• Direkter HTTP-Aufruf, kein SDK nötig

OpenAI-kompatible Schnittstelle: http://localhost:11434/v1/*

• Endpunkte: /v1/chat/completions, /v1/completions, /v1/models
• Voll kompatibel mit OpenAI SDK (Python, JavaScript)
• Bestehendes OpenAI-Tool-Ökosystem nutzbar

Warum zwei Varianten? Beide haben ihren Platz. Die native API ist leichter und direkter – ideal für eigene HTTP-Clients. Die OpenAI-Kompatibilität lässt bestehenden OpenAI-SDK-Code unverändert laufen – nur base_url anpassen.

Dieses Design ist durchdacht: einfache Aufrufe für Einsteiger, nahtlose Integration für Teams mit OpenAI-Codebasis.

Native REST-API: Mit curl starten

Die native API ist schlicht: ein standardmäßiger REST-Endpunkt.

Alibaba Cloud - Top-Wahl für Entwickler, exklusiv 15 % Rabatt auf Lighthouse-Server

15 % Rabatt sichern →Anzeige

Einfacher curl-Aufruf

Minimalbeispiel – Textgenerierung:

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "Why is the sky blue?",
  "stream": false
}'

Achten Sie auf stream: false. Standardmäßig streamt Ollama – für eine vollständige JSON-Antwort Streaming explizit deaktivieren. Sonst erscheint eine Ausgabe wie:

{"model":"llama3.2","response":"That","done":false}
{"model":"llama3.2","response":"'","done":false}
{"model":"llama3.2","response":"s","done":false}
{"model":"llama3.2","response":" a","done":false}
...
{"model":"llama3.2","response":"!","done":true}

Jedes JSON-Objekt enthält nur wenige Zeichen – tokenweise Ausgabe. Das ist NDJSON (Newline-Delimited JSON): eine Zeile pro JSON-Objekt. Beim ersten Versuch wurde nur das erste Objekt mit „That“ geparst – weil es wie normales JSON behandelt wurde.

Dialogmodus ist praxisnäher

Einmalige Generierung für einfache Aufgaben; im Alltag zählt der Dialogmodus:

curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2",
  "messages": [
    { "role": "user", "content": "Hello!" }
  ],
  "stream": false
}'

Ein messages-Array hält den Verlauf – so behält das Modell Kontext. Entscheidend für Chat-Anwendungen.

Installierte Modelle anzeigen

Welche Modelle lokal verfügbar sind:

curl http://localhost:11434/api/tags

Die JSON-Antwort listet alle heruntergeladenen Modelle inklusive Größe, Änderungszeit und Quantisierungsstufe.

Streaming-Antworten verarbeiten

Ollama streamt nicht in einem Stück, sondern tokenweise.

Streaming in Python

Mit der requests-Bibliothek:

import requests
import json

url = "http://localhost:11434/api/chat"
payload = {
    "model": "llama3.2",
    "messages": [{"role": "user", "content": "Write a short poem"}],
    "stream": True
}

response = requests.post(url, json=payload, stream=True)
for line in response.iter_lines():
    if line:
        chunk = json.loads(line)
        print(chunk.get("message", {}).get("content", ""), end="", flush=True)

Der Schlüssel ist response.iter_lines() – zeilenweises Lesen des NDJSON-Streams. Jeder Chunk kann nur wenige Zeichen enthalten; erst die Akkumulation ergibt die vollständige Antwort.

Streaming in JavaScript

Mit der fetch-API ähnlich:

const response = await fetch('http://localhost:11434/api/chat', {
  method: 'POST',
  body: JSON.stringify({
    model: 'llama3.2',
    messages: [{ role: 'user', content: 'Hello!' }],
    stream: true
  })
});

const reader = response.body.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const chunk = new TextDecoder().decode(value);
  // Jeden Chunk verarbeiten...
}

Streaming ist aufwändiger als Nicht-Streaming – die UX ist besser: Ausgabe in Echtzeit statt langer Wartezeit und plötzlichem Textblock.

KiloClaw - Managed OpenClaw für Unternehmen: AI-Agent-Orchestrierung und smartes Modell-Routing

Jetzt starten →Anzeige

OpenAI-SDK-Kompatibilität: Migration ohne Codeänderung

Ollama bietet eine vollständige OpenAI-API-kompatible Schnittstelle – bestehender Code lässt sich nahezu nahtlos übernehmen.

Beispiel mit Python OpenAI SDK

Offizielles OpenAI SDK direkt nutzen:

from openai import OpenAI

client = OpenAI(
    base_url='http://localhost:11434/v1/',
    api_key='ollama'  # lokal keine Validierung, beliebiger Wert
)

response = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "Hello!"}]
)

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

Die einzige Anpassung: base_url setzen und beliebigen api_key übergeben. Restlicher Code bleibt gleich.

Wechsel zwischen Entwicklung und Produktion

Praktisch: lokal Ollama, in Produktion OpenAI:

# Entwicklung .env
OPENAI_API_KEY=anyrandomtext
LLM_ENDPOINT="http://localhost:11434/v1"
MODEL=llama3.2

# Produktion .env
OPENAI_API_KEY=sk-XXXXXXXXXXXXXXXXXXXXXXXX
LLM_ENDPOINT="https://api.openai.com/v1"
MODEL=gpt-3.5-turbo

Im Code aus Umgebungsvariablen lesen:

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.getenv('LLM_ENDPOINT'),
    api_key=os.getenv('OPENAI_API_KEY')
)

In der Entwicklung entfallen OpenAI-Kosten – lokale Tests reichen. Beim Go-Live reicht ein Wechsel der Umgebungsvariablen.

Unterstützte Endpunkte

Die OpenAI-kompatible Ollama-Schnittstelle unterstützt:

Experimentell gibt es /v1/images/generations – Stabilität noch eingeschränkt.

Modell-Aliase

Kleiner Trick: Modellen Aliase geben. Code soll wie GPT-3.5 aussehen:

ollama cp llama3.2 gpt-3.5-turbo

Dann verwendet model="gpt-3.5-turbo" im Code lokal llama3.2 – hilfreich bei der Migration.

Welche Variante wählen?

Native REST-API

Passend wenn:

🔥 Verschwende keine Monate für ungenutzte Produkte! Teste deine SaaS-Nutzenversprechen mit Adsterra bei kleinem Budget →

Jetzt testen →Anzeige

• Sie den leichtesten Aufruf wollen
• Sie kein OpenAI-SDK-Ökosystem brauchen
• Sie einen eigenen HTTP-Client schreiben (Embedded, Spezialumgebung)
• Sie Streaming-Details präzise steuern müssen

Die native API ist direkter und näher am Protokoll – wer HTTP kennt, kommt schnell zurecht.

OpenAI-SDK-kompatible Schnittstelle

Passend wenn:

• Sie bereits OpenAI-SDK-Code haben
• Sie schnell auf lokales Deployment wechseln wollen
• Sie OpenAI-Toolchains nutzen (LangChain, LlamaIndex)
• Sie zwischen Entwicklung und Produktion wechseln müssen

Wer wenig am Code ändern will, greift zur OpenAI-Kompatibilität.

Empfehlung

In der Entwicklung meist OpenAI-SDK-Kompatibilität – wenig Codeänderung, Toolchains funktionieren, Debugging einfacher. Die native API passt für minimale CLI-Tools oder Umgebungen ohne OpenAI SDK.

Praxis-Code-Snippets

Python-Streaming-Chat (OpenAI SDK)

from openai import OpenAI

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

stream = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "Write a poem"}],
    stream=True
)

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

JavaScript-Vollständiger Dialog (native API)

async function chat(messages) {
  const response = await fetch('http://localhost:11434/api/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      model: 'llama3.2',
      messages: messages,
      stream: false
    })
  });
  return await response.json();
}

// Dialogverlauf pflegen
let conversation = [
  { role: 'user', content: 'Hello!' }
];

const result = await chat(conversation);
conversation.push({
  role: 'assistant',
  content: result.message.content
});

console.log(result.message.content);

Beispiel mit Tool Calling

Ollama unterstützt Function Calling:

from openai import OpenAI

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

tools = [
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get current weather",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {"type": "string"}
        },
        "required": ["location"]
      }
    }
  }
]

response = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    tools=tools
)

if response.choices[0].message.tool_calls:
  print("Model wants to call:", response.choices[0].message.tool_calls[0].function.name)

Kurz zusammengefasst

Ollamas API-Design ist ausgewogen: native REST-API für Direktheit und Leichtgewicht, OpenAI-SDK für Bequemlichkeit und Ökosystem-Kompatibilität. Beide Varianten haben klare Einsatzgebiete – die Wahl hängt vom Bedarf ab.

Beim Einstieg empfiehlt sich die OpenAI-SDK-Kompatibilität – schneller Start, wenig Anpassung. Später können Sie bei Bedarf zur nativen API wechseln.

Wichtig beim Streaming: Standard ist Streaming aktiv. Bei Bedarf an vollständigem JSON stream: false setzen – sonst droht das Erlebnis mit einem halben Wort um drei Uhr nachts.

Referenzen

• Ollama API Introduction
• Ollama OpenAI Compatibility
• Ollama Streaming Guide
• KodeKloud OpenAI Compatibility Guide