KI-API-Streaming: SSE, erste Ausgabe & Timeouts

Zuverlässiges KI-API-Streaming: korrekte Chat- und Responses-Events, SSE-Parsing, Kennzahlen zur ersten effektiven Ausgabe, Timeouts pro Phase und Diagnose von 499.

KI-API-Streaming: SSE, erste Ausgabe & Timeouts

KI-API-Streaming liefert die Ausgabe schrittweise, während ein Modell generiert, statt auf den vollständigen Antwortinhalt zu warten. Das kann die wahrgenommene Reaktionsgeschwindigkeit verbessern, verringert aber nicht automatisch die Modelllatenz und bringt einen Protokollvertrag mit sich, den der Client korrekt parsen muss.

Die erste Regel lautet: Der Parser muss zum Endpunkt passen. Chat Completions verwendet gestreamte Completion-Chunks, Responses dagegen typisierte Response-Events. Ein Client kann HTTP 200 erhalten und trotzdem nichts darstellen, wenn er die falsche Event-Struktur erwartet.

Mit einer ungepufferten Anfrage beginnen

Für ein Chat-Completions-Modell deaktiviert curl -N die Ausgabepufferung von curl:

curl -N -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [{"role": "user", "content": "Explain SSE in three points."}],
    "stream": true
  }'

Für ein Responses-kompatibles Modell:

curl -N -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_RESPONSES_MODEL",
    "input": "Explain SSE in three points.",
    "stream": true
  }'

Verwenden Sie eine exakte Modell-ID aus Modelle & Preise. Testen Sie dieselbe Anfrage zuerst einmal ohne Streaming; so trennen Sie die Validierung der Anfrage vom Parsen des Streams.

Den Event-Stream als Protokoll behandeln

Server-Sent Events sind gerahmte Datensätze, keine beliebigen JSON-Fragmente. Ein Client im Produktivbetrieb muss:

  • den Antwortinhalt in HTTP-Bibliothek, Proxy und UI-Schicht ungepuffert halten;
  • unvollständige Netzwerk-Reads sammeln, bis ein vollständiges Event vorliegt;
  • den Event-Typ des gewählten Endpunkts parsen;
  • Text-Deltas, Reasoning- oder Tool-Events, Abschluss-Events und Fehler-Events verarbeiten;
  • nicht davon ausgehen, dass jede nützliche Antwort sichtbaren Text enthält;
  • Abbruchinformationen und die endgültigen Nutzungsdaten erhalten;
  • den Stream nach einem abschließenden Event schließen, statt endlos zu warten.

Verwenden Sie nach Möglichkeit ein SDK, das das gewählte Protokoll nativ unterstützt. Ein selbst geschriebener Parser sollte mit fragmentierten Frames, mehreren Events in einem Read, reiner Tool-Ausgabe und einem sauberen abschließenden Event getestet werden.

Mehr messen als die Zeit bis zum ersten Token

Die „Zeit bis zum ersten Token“ ist für Agent-Traffic oft zu ungenau. Trennen Sie diese Messungen:

Messung Bedeutung
Verbindung und Authentifizierung Zeit, bis das Gateway erreicht und der Schlüssel geprüft ist
Antwort-Header des Dienstanbieters Zeit, bis die ausgewählte Route mit einer Antwort beginnt
Erste effektive Ausgabe Erster nützlicher Text, erstes Reasoning- oder Tool-Event
Erster sichtbarer Text Erster Text, den Benutzer tatsächlich sehen
Ausgabedurchsatz Sichtbare Generierungsgeschwindigkeit nach Beginn der Ausgabe
Gesamtantwortzeit Zeit bis zum Abschluss, Fehler oder Abbruch

Ein Tool-Aufruf kann eine effektive Ausgabe liefern, bevor sichtbarer Text erscheint. Daher ist die erste effektive Ausgabe die sicherere Betriebskennzahl, während der erste sichtbare Text für die Benutzererfahrung nützlich ist.

Die Nutzungsprotokolle von Modelflare bewahren Zeitnachweise pro Anfrage auf, sodass sich diese Phasen mit Modell, Gruppe, Status, Token und Kosten vergleichen lassen.

Timeouts nach Phasen festlegen

Ein einziges kurzes globales Timeout führt zu mehrdeutigen Fehlern. Ein Streaming-Client sollte mehrere Zeitbudgets berücksichtigen:

  1. Verbindungs-Timeout: Die HTTP-Verbindung kann nicht aufgebaut werden.
  2. Timeout für Header oder erste Ausgabe: Nach Annahme der Anfrage kommt keine Antwort und kein effektives Event.
  3. Leerlauf-Timeout: Der Stream hat begonnen, aber ungewöhnlich lange ist kein neues Event eingetroffen.
  4. Gesamtfrist: Der vollständige Vorgang hat das fachliche Zeitlimit der Arbeitslast überschritten.

Anfragen mit viel Reasoning oder vielen Tools können berechtigterweise länger bis zum sichtbaren Text brauchen als eine kurze Chat-Completion. Wählen Sie die Budgets anhand des beobachteten Verhaltens der Arbeitslast und brechen Sie bewusst ab, wenn das Ergebnis nicht mehr benötigt wird.

Abbrüche und 499-Einträge verstehen

Schließen Client, Reverse Proxy, Browser-Tab oder die Frist des Aufrufers die Downstream-Verbindung, kann das Gateway die Anfrage als vom Client abgebrochen erfassen. Die Kennzeichnung 499 in einem Anfragedatensatz belegt, dass die Downstream-Verbindung vor dem Abschluss endete; für sich genommen beweist sie nicht, dass das ausgewählte Modell oder der Kanal ausgefallen ist.

Vergleichen Sie bei der Untersuchung eines Abbruchs:

  • die Frist des Clients und das Abbruchsignal;
  • Pufferung und Leerlauf-Timeouts des Proxys;
  • die Zeit bis zur ersten effektiven Ausgabe;
  • ob überhaupt ein Event beim Client angekommen ist;
  • das ausgewählte Modell und die Gruppe;
  • die Anfrage-ID und den Zeitpunkt des Abbruchs.

Einen Stream ohne sichtbaren Text diagnostizieren

Gehen Sie in dieser Reihenfolge vor:

  1. Wiederholen Sie die Anfrage mit "stream": false.
  2. Bestätigen Sie, dass das Modell den gewählten Endpunkt unterstützt.
  3. Erfassen Sie die rohen Events, bevor die UI sie umwandelt.
  4. Prüfen Sie, ob die Antwort statt Text einen Tool-Aufruf oder ein Reasoning-Event enthält.
  5. Stellen Sie sicher, dass keine Zwischenstation den Antwortinhalt puffert.
  6. Bestätigen Sie, dass der Parser das abschließende Event des Endpunkts verarbeitet.
  7. Prüfen Sie in den Nutzungsprotokollen Status, erste Ausgabe, Gesamtzeit und Abbruch.

Funktioniert die Anfrage ohne Streaming und kommen rohe Streaming-Events an, liegt der Fehler meist beim Parsen oder Darstellen im Client und nicht bei Authentifizierung oder Modellzugriff. Kommt kein rohes Event an, fahren Sie mit dem KI-API-Fehlerleitfaden fort.

Checkliste für Streaming im Produktivbetrieb

  • Ordnen Sie den Parser ausdrücklich Chat Completions oder Responses zu.
  • Deaktivieren Sie die Pufferung im HTTP-Client und in jeder Proxy-Schicht, die Sie kontrollieren.
  • Testen Sie Text-, Reasoning-, reine Tool- und Fehler-Events, die die Anwendung verwendet.
  • Unterscheiden Sie die erste effektive Ausgabe vom ersten sichtbaren Text.
  • Verwenden Sie phasengerechte Timeouts und ein bewusstes Abbruchsignal.
  • Behandeln Sie Wiederholungen als neue Anfragen, sofern der Vorgang kein sicheres Idempotenz-Design hat.
  • Bewahren Sie Anfrage-ID, Status, ausgewähltes Modell, Gruppe und Zeiten für die Diagnose auf.
  • Prüfen Sie die Wahl des Endpunkts anhand von Responses API oder Chat Completions.

Häufige Fragen

Generiert das Modell mit Streaming schneller?

Nicht unbedingt. Streaming macht die Ausgabe früher sichtbar; Generierungsgeschwindigkeit und Zeit bis zum ersten Event hängen weiterhin von Modell, Route, Kontext, Reasoning und Tools ab.

Warum funktioniert curl, während die Anwendung nichts anzeigt?

Die Anwendung oder eine Zwischenstation puffert möglicherweise den Antwortinhalt, oder der Parser erwartet Chat-Completions-Chunks, erhält aber Responses-Events. Erfassen Sie die rohen Frames an der Grenze der Anwendung, bevor Sie Modell oder Route ändern.

Sollte ein Client nach einem abgebrochenen Stream erneut anfragen?

Nur wenn die Wiederholung des Vorgangs sicher ist. Ein getrennter Stream kann bereits Arbeit beim Dienstanbieter oder Tool-Aktivität ausgelöst haben. Verwenden Sie begrenzte Wiederholungen und Idempotenz auf Anwendungsebene, wenn doppelte Nebenwirkungen relevant sind.