Ollama API: Erster Chat, Streaming und klare Fehlerbehandlung

Den richtigen Ollama-Endpunkt wählen

Die native lokale API ist standardmäßig unter http://localhost:11434/api erreichbar. Für einen direkten Ollama-Cloudzugriff nennt die Dokumentation https://ollama.com/api und eine passende Authentisierung. Das sind unterschiedliche Zugänge.

Auch eine lokale Ollama-Instanz kann mit ausgewähltem Cloudmodell einen anderen Datenweg haben. „Die URL beginnt mit localhost“ beweist deshalb nicht, dass die gesamte Inferenz auf deinem Rechner bleibt. Prüfe den tatsächlich gewählten Modellnamen und den Betriebsmodus.

Der folgende Einstieg setzt voraus, dass Ollama auf dem angesprochenen Rechner läuft und ein geeignetes lokales Modell dort bereits verfügbar ist. Wenn diese Begriffe neu sind, kannst du zuerst Ollama und lokale Modellnutzung kennenlernen.

Die native Route /api/chat ist von Kompatibilitätsschnittstellen unter anderen Pfaden zu unterscheiden. Verwende Request und Antwortformat immer zusammen mit dem passenden Endpunkt. Für Text-zu-Sprache gibt es den eigenen Endpunkt /v1/audio/speech. Unter Ollama Phonon einrichten findest du Sprachwahl, Plattformvoraussetzungen und WAV-Ausgabe.

Der erste Chat-Request ohne Streaming

Trage im Beispiel den exakten Namen eines tatsächlich vorhandenen lokalen Modells ein. DEIN_LOKALES_MODELL ist ein Platzhalter und wird nicht automatisch ersetzt. Speichere den Inhalt als ollama-chat-request.json.

{
  "model": "DEIN_LOKALES_MODELL",
  "messages": [
    {
      "role": "user",
      "content": "Nenne einen Vorteil und eine Grenze lokaler KI. Antworte in zwei kurzen Sätzen."
    }
  ],
  "stream": false
}

Die JSON-Vorlage herunterladen, den Modellnamen ändern und erst danach senden. Im Verzeichnis der Datei lautet der Aufruf:

curl --fail-with-body --show-error http://localhost:11434/api/chat -H "Content-Type: application/json" --data-binary @ollama-chat-request.json

In Windows PowerShell kannst du ausdrücklich curl.exe verwenden. --fail-with-body setzt eine hinreichend aktuelle curl-Version voraus. Die Datei vermeidet kompliziert verschachtelte Anführungszeichen bei JSON im Terminal.

messages enthält die Gesprächsnachrichten; hier gibt es eine Nachricht mit Rolle user. stream:false schaltet das standardmäßig aktive Streaming für diese Anfrage aus. Dieser Aufruf erzeugt eine Modellantwort, er ist kein reiner Verbindungstest. Wenn ein Workflow diese Modellanfrage übernehmen soll, kannst du n8n mit Ollama verbinden und zuerst einen kleinen Ablauf ohne Werkzeugagenten prüfen.

Die Chat-Antwort gezielt auslesen

Beim nativen Chat steht der Antworttext in message.content. Verwechsle das nicht mit dem Feld response des Generate-Endpunkts. Ein Beispiel aus einer anderen Route kann deshalb trotz gültigem JSON zum falschen Feldzugriff führen.

Behandle die Antwort als Datenobjekt und prüfe die erwarteten Typen. Nicht jedes erfolgreiche HTTP-Ergebnis enthält den fachlich gewünschten Inhalt. Ein leerer Text, eine verweigerte Antwort und eine passende Antwort sind unterschiedliche Fälle.

Wenn dein Programm feste Datenfelder benötigt, kannst du anschließend strukturierte Ollama-Antworten mit einem JSON-Schema prüfen. Formal gültige Daten ersetzen dabei keine Prüfung ihrer inhaltlichen Richtigkeit.

Streaming als Folge einzelner JSON-Zeilen lesen

Bei aktivem Streaming liefert Ollama application/x-ndjson: mehrere JSON-Objekte, zeilenweise übertragen. Der ganze Antwortbody ist deshalb nicht einfach ein einzelnes JSON-Dokument. Ein Netzwerkpaket muss außerdem nicht genau einer vollständigen Zeile entsprechen; nutze den Zeilenleser deiner HTTP-Bibliothek.

Der folgende eigene Parser verarbeitet bereits vollständig zusammengesetzte und als Text dekodierte Zeilen. Er ist auf einfachen Chattext begrenzt; Toolaufrufe, Reasoningfelder und multimodale Inhalte wären gesondert zu behandeln. Netzwerkverbindung, Timeout und Abbruchkontrolle gehören in die umgebende Anwendung.

import json

def read_chat_lines(lines):
    parts = []
    done = False
    for line in lines:
        if not line.strip():
            continue
        if done:
            raise ValueError("Daten nach dem Abschluss")
        item = json.loads(line)
        if not isinstance(item, dict):
            raise ValueError("JSON-Objekt erwartet")
        if "error" in item:
            raise RuntimeError(str(item["error"]))
        message = item.get("message", {})
        if not isinstance(message, dict):
            raise ValueError("Ungültiges message-Feld")
        content = message.get("content", "")
        if not isinstance(content, str):
            raise ValueError("Text in message.content erwartet")
        parts.append(content)
        done = item.get("done") is True
    if not done:
        raise ValueError("Stream ohne done=true abgebrochen")
    return "".join(parts)

# Eigene künstliche Daten, kein API-Aufruf:
sample = [
    '{"message":{"content":"Hallo "},"done":false}',
    '{"message":{"content":"Welt"},"done":true}',
]
print(read_chat_lines(sample))

Die Beispielausgabe lautet rechnerisch Hallo Welt. Sie stammt nur aus den beiden künstlichen Zeilen im Code. Es wurde kein Modell angesprochen und kein tatsächlicher Stream mitgeschnitten.

HTTP-Fehler und Streamfehler getrennt behandeln

Die Ollama-Hilfe unterscheidet etwa ungültige Eingaben, fehlende Modelle und weitere Fehlerzustände. Prüfe zuerst den HTTP-Status und den erhaltenen Fehlerbody. Wenn der Stream bereits begonnen hat, kann ein späteres error-Objekt auftreten, ohne dass aus dem ursprünglichen HTTP 200 nachträglich ein anderer Status wird.

Bei Verbindungsfehlern solltest du den Ollama-Port und die Verbindung prüfen. Das ist etwas anderes als ein fehlender Modellname oder ein Fehler nach bereits begonnenem Streaming.

Wiederhole Anfragen nicht blind. Bei einem Abbruch können bereits Text oder Werkzeugaktionen entstanden sein. Lege fest, was deine Anwendung bei Fehlern zeigt, welche Daten sie protokolliert und ob eine Wiederholung überhaupt passend ist.

Ein kurzer Prüfplan für die eigene Anwendung

Baue den ersten Ablauf klein: eine freigegebene Eingabe, ein vorhandenes lokales Modell, eine einzelne Antwort und eine sichtbare Fehleranzeige. Halte die Version und das tatsächliche Ziel fest. Die native Ollama-API wird laut Einführung nicht streng versioniert; prüfe Beispiele deshalb gegen deinen eingesetzten Stand.

Ziel: lokale native /api/chat-Route.
Modell: exakter vorhandener Name und Betriebsmodus geprüft.
Erster Lauf: stream:false und message.content kontrollieren.
Negativfall: ungültige Eingabe oder fehlendes Modell sichtbar erkennen.
Streaming: einzelne JSON-Zeilen plus error und done prüfen.
Abbruch: Timeout, Teilantwort und Wiederholung unterscheiden.
Datenschutz: nur nötige Eingaben und begrenzte Protokolle.
Netzwerk: API nicht ohne passenden Schutz öffentlich freigeben.

Ein funktionierender Prototyp braucht noch keinen öffentlich erreichbaren Modellserver. Bleibe beim kleinsten passenden Zugang und prüfe eine Freigabe gesondert, wenn andere Rechner zugreifen sollen.

Stand: 20. Oktober 2026. Vier offizielle API-Texte vollständig gelesen. Request und Code wurden statisch geprüft, künstliche Parserfälle unabhängig ausgeführt. Es gab keine tatsächliche Ollama-, Cloud- oder Modellanfrage.