Blog

Benutzerhandbuch

Kimi K3 Antwortverarbeitung in der Praxis: Vollständiges JSON, Streaming-Abbrüche und Retry-Grenzen

Nov 18, 2026
Abstrakte geometrische Titelgrafik mit zwei Gruppen flacher Gewebebänder, die sich auf dunkelgrünem Grund zu einem offenen Gitter verflechten, akzentuiert durch zurückhaltendes Messinggelb.
Auf dieser Seite

Zunächst zwei Antwortpfade unterscheiden

Bei derselben Kimi K3-Schnittstelle erhalten Sie möglicherweise zwei völlig verschiedene Dinge: eine vollständige JSON-Antwort oder eine Reihe von Streaming-Datenblöcken, die in Reihenfolge eintreffen. Ersteres ist die Dokumentenlieferung „Frage und Antwort“, letzteres eine inkrementelle Sequenz, die „während der Generierung gepusht“ wird. Die Ursache vieler Antwortverarbeitungsfehler ist nicht falsch geschriebene Parsing-Logik, sondern dass von Anfang an nicht klar war, auf welchem Pfad man sich befindet.

Beide Pfade teilen dasselbe Anfrageprotokoll (openai_chat_completions, Vertragsversion 2), die Unterschiede konzentrieren sich auf die Konsumart:

  • Nicht-Streaming: Nach der Rückkehr der Anfrage erhalten Sie einen vollständigen Antwortkörper, der Text, Denkinhalt und Nutzung enthält – alles auf einmal lesbar.
  • Streaming: Die Antwort wird im optionalen Modus gestartet, der Server pusht kontinuierlich Chunks und beendet den Stream schließlich mit dem SSE-Marker [DONE]. Unterwegs erhalten Sie möglicherweise Dutzende oder Hunderte von Blöcken oder der Stream bricht mittendrin ab; [DONE] bedeutet nur, dass der Stream beendet ist, nicht dass der Inhalt vollständig ist.

Klargestellt werden muss dies zuerst, damit alle weiteren Diskussionen Sinn ergeben. Wenn in Ihrer Geschäftskette beide Aufrufarten existieren (z. B. Backend-Batchverarbeitung und Frontend-Dialog einen Wrapper teilen), sollten Sie den Pfad im Client explizit kennzeichnen, anstatt ihn durch implizite Unterscheidung wie „ob ein Callback vorhanden ist“ zu unterscheiden – das legt bei Refactorings die Grundlage für Deserialisierungsfehler.

Eine einfache Entscheidungsregel: Verwenden Sie Streaming, wenn Sie dem Benutzer zeichenweise anzeigen müssen oder die Ausgabe möglicherweise sehr lang ist; verwenden Sie Nicht-Streaming, wenn Sie ein strukturiertes Ergebnis auf einmal benötigen, das später gespeichert oder weiterverarbeitet werden soll. Der Parsing-Code beider Pfade sollte getrennt geschrieben werden; gemeinsam genutzt werden nur die Anforderungserstellung und das Fehler-Mapping.

Derselbe Anfrage-Eingang teilt sich in zwei Konsumpfade: einer liefert die gesamte Antwort, der andere liefert scheibchenweise Fragmente.

Vollständiges JSON parsen: Text, Denkinhalt und strukturierte Felder

Die Nicht-Streaming-Antwort folgt dem Antwortkörperformat von OpenAI Chat Completions, aber es gibt einen leicht zu übersehenden Punkt: Text und Denkinhalt sind zwei verschiedene Felder.

Der Text befindet sich an der standardmäßigen Nachrichteninhaltsposition, während der Denkprozess von Kimi K3 über das Feld reasoning_content geliefert wird. Das bedeutet, Ihre Parsing-Schicht muss mindestens drei Dinge tun:

  • Die endgültige benutzerorientierte Antwort aus dem Nachrichteninhalt entnehmen;
  • Prüfen, ob reasoning_content vorhanden ist, und bei Vorhandensein entscheiden, ob protokolliert, dem Benutzer angezeigt oder verworfen wird;
  • usage separat speichern für Abrechnung und Quotenberechnung.

reasoning_content als Text anzuzeigen ist ein häufiger Unfall: Es ist für Debugging- und Erklärbarkeitsszenarien gedacht; direkt in Produkttexte oder Kundendienstantworten zu gelangen, passt weder im Ton noch im Inhalt. Die richtige Vorgehensweise ist, ihm einen separaten Konsumpfad zu geben, z. B. in Debug-Logs oder als optionalen Einstieg „Denkprozess anzeigen“.

Wie strukturierte Ausgaben verwendet werden

Der Vertrag unterstützt den Parameter response_format und die strukturierte Ausgabefähigkeit jsonObject. Sie können das Modell auffordern, ein JSON-Objekt zurückzugeben, wodurch eine fragile reguläre Extraktionsebene entfällt. Aber zwei Voraussetzungen müssen klargestellt werden: Die Fähigkeit jsonObject bedeutet nicht Unterstützung des JSON-Schema-Modus; strukturierte Ausgabe ist auch keine Garantie für „garantierten Erfolg“.

Versuchen Sie erst dann, JSON zu parsen, wenn die Antwort normal abgeschlossen und der Inhalt vollständig ist. Nach dem Parsen müssen noch drei Fehlerklassen behandelt werden:

  • Parsing-Fehler: Der zurückgegebene Inhalt ist kein gültiges JSON oder Felder fehlen bzw. haben falsche Typen. In diesem Fall sollte die Rohzeichenkette nicht direkt an die übergeordnete Geschäftslogik weitergegeben werden, sondern in einen Degradationszweig wechseln.
  • Schema-Validierungsfehler: JSON-Syntax ist gültig, entspricht aber nicht der deklarierten Struktur. jsonObject garantiert keine Einschränkungen auf JSON-Schema-Ebene; die Geschäftsseite muss Felder, Typen und Pflichtfelder selbst validieren.
  • Abschneiden: Wenn die Ausgabelänge das Ausgabe-Token-Limit dieses Modells (131072) erreicht, kann finish_reason den Wert length haben und das JSON mittendrin enden. length darf nicht als vollständiger JSON-Erfolg betrachtet werden. Ein unvollständiger JSON-Parser meldet einen Fehler, aber gefährlicher ist der Fall, dass er „knapp erfolgreich parst“ und Sie mit einem halben Objekt weiter Geschäftslogik ausführen.

Es wird empfohlen, nach dem Parsen eine Prüfung der Vollständigkeit der Geschäftsfelder und der Evidenz hinzuzufügen, anstatt sich nur auf die Gültigkeit der JSON-Syntax zu verlassen. Das Kontextfenster beträgt 1000000; bei langen Dokumenten ist die Eingabe kein Engpass, aber das Abschneiden der Ausgabe bleibt eine reale Grenze.

Der Antwort-Umschlag wird in Schichten zerlegt: Text, Denkinhalt und Nutzung bilden je einen Zweig, der zu seinem eigenen Konsumenten fließt.

Streaming lesen: [DONE], finish_reason und Nutzung

Im Streaming-Modus pusht der Server Chunks in Reihenfolge; der SSE-Netzwerk-Endmarker ist [DONE]. Das klingt banal, wird aber oft falsch interpretiert: [DONE] bedeutet nur, dass dieser Stream beendet ist, nicht dass die Generierung erfolgreich war oder der Inhalt vollständig ist.

Zur Bestimmung des Endzustands ist choices[].finish_reason in jedem Chunk zu prüfen. Das aktuelle Frontend erkennt den Endzustand an einem nicht-leeren finish_reason; selbst wenn [DONE] empfangen wurde, sollte ein fehlendes finish_reason als Abbruch gelten. Ein error-Frame im Stream zeigt an, dass diese Anfrage fehlgeschlagen ist.

Der Stream kann in mehreren Zuständen enden:

  1. Normaler Abschluss: finish_reason ist ein erfolgreicher Endzustand, danach folgt [DONE]; der akkumulierte Inhalt kann als vollständiges Ergebnis betrachtet werden;
  2. Längenabschneidung: finish_reason=length, die Ausgabe wurde aufgrund der Längenobergrenze abgeschnitten, der Inhalt ist möglicherweise unvollständig und darf nicht als vollständiger JSON-Erfolg gewertet werden;
  3. Andere nicht erfolgreiche Gründe: z. B. Inhaltsfilterung, die separat behandelt werden müssen und nicht als normaler Abschluss gelten dürfen;
  4. Abbruch mittendrin: Verbindung geschlossen, Timeout oder ein error-Frame im Stream empfangen; dann liegt nur teilweiser Inhalt vor, der als fehlgeschlagen oder unvollständig markiert werden sollte.

Der letzte Fall wird am ehesten als „was man bekommt, wird genommen“ implementiert. Für die Chat-Anzeige mag das akzeptabel sein (der Benutzer sieht einen halben Satz und kann erneut senden), aber für Datenbankpersistenz, Abrechnung oder das Auslösen nachgelagerter Aktionen sind es falsche Daten. Bitte verwenden Sie „ob ein erfolgreicher Endzustand finish_reason empfangen wurde“ als Vollständigkeitskriterium, nicht nur [DONE].

Nutzung wird nach Stream-Ende aggregiert

Im Streaming-Modus kann usage in einem choices:[]-Frame nach finish_reason erscheinen. Der Client sollte den gesamten Stream lesen und dann die Nutzung aggregieren; es kann nicht garantiert werden, dass [DONE] selbst usage enthält.

Das führt zu zwei direkten Codierungseinschränkungen:

  • Nicht beim ersten Chunk abrechnen oder Quoten verrechnen. Zu diesem Zeitpunkt kennen Sie weder die endgültige Ausgabelänge noch haben Sie das Nutzungsfeld.
  • Nutzung nicht in Zwischen-Chunks akkumulieren und [DONE] nicht als Nutzungsträger behandeln. Zwischen-Chunks enthalten keine zuverlässigen Nutzungsdaten; jede „Schätzung“ weicht vom endgültigen Wert ab.

Die richtige Reihenfolge: Während des Streamings nur Text und Status akkumulieren; nach dem vollständigen Lesen des Streams die Nutzung aus dem choices:[]-Frame aggregieren und eine Abrechnung durchführen. Wenn der Stream mittendrin abbricht und Sie dem Benutzer bereits Inhalte angezeigt haben, ist der Nutzungsstatus dieses Aufrufs unbekannt – Sie benötigen ein Statusflag „unvollständig“, anstatt standardmäßig mit 0 oder einem geschätzten Wert zu buchen.

Außerdem müssen interne Metadaten von Netzwerkfeldern unterschieden werden: response.stream.terminal=done, response.usage.delivery=final_chunk sind interne Metadaten-Tags der Plattform, keine SSE-Netzwerkfelder und keine vom Client zu matchenden Terminierungsstrings. Der Client sollte sich nur auf [DONE], finish_reason, error-Frames und das Feld usage selbst verlassen.

Ein weiteres praktisches Detail: Beim Akkumulieren von Text eine Liste anhängen und dann joinen, anstatt Zeichenketten wiederholt zu verketten – bei langen Ausgaben ist der Performance-Unterschied deutlich.

Die obere Zeitlinie erreicht einen messingfarbenen Endblock mit erfolgreichem finish_reason; die untere Zeitlinie bricht mittendrin ab und erreicht keinen erfolgreichen Endzustand, daher darf nicht angenommen werden, dass ein vollständiges Ergebnis vorliegt.

Warum POST-Retries nicht kostenlos idempotent sind

Viele Retry-Logiken sind so geschrieben: Die Anfrage wirft eine Timeout-Ausnahme, diese wird abgefangen, eine Weile gewartet und erneut gesendet. Dieser Artikel behandelt nur die Semantik von POST-Generierungsoperationen wie Chat-Completions: Solche Retries können doppelte Abrechnung und doppelte Nebenwirkungen verursachen und dürfen nicht als kostenlos idempotent betrachtet werden.

Der Grund ist schlicht: Ein Timeout ist eine Client-Entscheidung, kein Server-Versprechen. Wenn Ihr Timer auslöst, kann die Anfrage den Server bereits vollständig erreicht, die Inferenz begonnen oder sogar abgeschlossen und abgerechnet worden sein – nur die Antwort ging unterwegs verloren. Der Client kann allein anhand des Ausnahmetyps nicht zwischen diesen beiden Situationen unterscheiden:

  • Die Anfrage hat den Server nicht erreicht; ein Retry führt nicht zu einer zweiten Ausführung;
  • Die Anfrage wurde angenommen und hat Wirkung erzeugt; ein Retry ist ein zweiter Aufruf.

Die „Wirkung“ einer Chat-Completion umfasst in der Regel Token-Verbrauch und Abrechnung sowie Aktionen, die Sie auf der Geschäftsseite aufgrund der Antwort auslösen (Datenbank schreiben, Formular absenden, Nachricht senden). Ein POST mit unsicherem Ergebnis erneut abzuspielen bedeutet, diese Nebenwirkungen zweimal auszuführen. Das ist kein theoretisches Risiko: Netzwerk-Schwankungen, Gateway-Timeouts und Verbindungsresets durch Zwischengeräte erzeugen stabil solche mehrdeutigen Zustände.

Erschwerend kommt hinzu: Eine vollständige 5xx-Antwort, ein Timeout, eine Verbindungsunterbrechung oder ein JSON-Parsing-Fehler können nicht beweisen, dass die Anfrage nicht generiert, nicht abgerechnet oder ohne Nebenwirkungen war. Der Fehler, den Sie sehen, zeigt nur, dass der Client diesmal kein verwertbares Ergebnis erhalten hat.

Daher ist die richtige Voraussetzung für einen Retry nicht „es ist ein Fehler aufgetreten“, sondern „diese Anfrage wurde nachweislich nicht ausgeführt“. Beantworten Sie diese Frage, bevor Sie Retry-Code schreiben; wenn Sie sie nicht beantworten können, spielen Sie nicht automatisch erneut ab.

Retry-Grenzen ziehen: In welchen Fällen darf erneut abgespielt werden

Retries als abgestufte Tabelle umzusetzen ist zuverlässiger als ein einheitliches for retry in range(3). Im Folgenden finden Sie eine Behandlungsstrategie nach Fehlertyp.

Nachweislich nicht ausgeführt, Retry möglich

  • Verbindungsaufbau fehlgeschlagen (DNS-Fehler, Verbindung abgelehnt): Die Anfrage hat den Server offensichtlich nicht erreicht; sie wurde eindeutig nicht gesendet, ein Retry führt nicht zu einer zweiten Ausführung.
  • Rate-Limit-Antwort (z. B. 429): Nur wenn die API-Dokumentation oder die Antwortsemantik ausdrücklich garantiert, dass die Ablehnung vor der Ausführung erfolgt, darf mit Backoff gemäß dieser Semantik erneut versucht werden; allein aufgrund eines 429 oder eines anderen Statuscodes darf nicht auf „nicht ausgeführt“ oder „nicht abgerechnet“ geschlossen werden. Der Backoff muss mit zufälligem Jitter versehen sein, damit nicht mehrere Clients synchron erneut versuchen.
  • Vom Interface ausdrücklich bereitgestellter und serverseitig tatsächlich verwendeter Deduplizierungsmechanismus: Nur wenn die API-Dokumentation dies ausdrücklich beschreibt und der Server tatsächlich danach dedupliziert, darf gemäß dieser Semantik erneut versucht werden. Vom Client selbst generierte Request-IDs dienen nur der Nachverfolgung; es darf nicht angenommen werden, dass ein bestimmter Header oder ein Feld eine idempotente Wirkung hat.

Ergebnis unbekannt, explizite Behandlung erforderlich

  • Timeout: Dies ist die gefährlichste Kategorie. Ein Timeout beweist nicht, dass die Anfrage nicht ausgeführt wurde; ein erneutes Senden kann eine neue kostenpflichtige Generierung auslösen. Vom Client selbst generierte Request-IDs können nur zur Nachverfolgung dienen; nur wenn der Server einen Deduplizierungsmechanismus ausdrücklich unterstützt und tatsächlich verwendet, können doppelte Inferenz und doppelte Abrechnung möglicherweise verhindert werden. Eine Deduplizierung auf Geschäftsseite verhindert höchstens doppelte nachgelagerte Aktionen, nicht jedoch, dass das Modell erneut generiert und berechnet. Wenn die serverseitige Deduplizierungssemantik nicht bestätigt werden kann, nicht automatisch erneut abspielen, sondern dem Benutzer einen Fehler melden oder in einen manuellen/asynchronen Kompensationsprozess wechseln.
  • Vollständige 5xx-Antwort: Selbst wenn der Antwortkörper vollständig lesbar ist, kann nicht bewiesen werden, dass keine Generierung, keine Abrechnung oder keine Nebenwirkung erfolgte. Ein Retry ist nur möglich, wenn eindeutig keine Ausführung erfolgte oder die API-Dokumentation ausdrücklich besagt, dass der Server anhand der Deduplizierungs-ID tatsächlich dedupliziert; andernfalls als Ergebnis unbekannt behandeln.
  • Antwort-Parsing-Fehler: Einschließlich JSON-Parsing-Fehler und Schema-Validierungsfehler. Die Anfrage kann bereits erfolgreich und abgerechnet worden sein; ein Parsing-Fehler beweist nicht, dass keine Generierung erfolgte. Ein Retry kann doppelte Abrechnung und doppelte Nebenwirkungen verursachen; es wird empfohlen, das Ergebnis explizit als unbekannt zu markieren und zu protokollieren, um die Nutzung später abgleichen zu können.
  • Streaming-Verbindungsabbruch oder error-Frame im Stream: Bereits gepushte Inhalte dürfen nicht mit dem neuen Ergebnis zusammengefügt werden; eine erneute Wiedergabe gilt als völlig neue Generierung.

Kein automatischer Retry

  • Fehlerhafte Anforderungsparameter (Parameterfehler unter den 4xx): Egal wie oft wiederholt wird, das Ergebnis ist gleich; es wird nur der Fehler vergrößert.
  • Ablehnung durch Inhaltsprüfung: Eine erneute Wiedergabe ändert die Schlussfolgerung nicht.
  • Jeder Fall, in dem Sie nicht sicher sein können, ob „die Anfrage bereits wirksam wurde“, und keine serverseitige Deduplizierungssemantik vorliegt.

Grenzen in den Code schreiben

Zwei technische Einschränkungen sollten fest verankert werden: Die Anzahl der Retries muss begrenzt sein (in der Regel reichen 1 bis 2), und sie dürfen nur bei eindeutig nicht gesendeten Anfragen oder wenn die API-Dokumentation ausdrücklich garantiert, dass die Ablehnung vor der Ausführung erfolgt, wirksam werden; bei jedem Retry müssen Request-ID, Fehlertyp und Dauer protokolliert werden, denn „wie oft wiederholt wurde“ bestimmt direkt Ihre Nutzungsabrechnung und den Fehlerbehandlungspfad. Bei Streaming-Anfragen ist zusätzlich zu beachten: Wird nach einem mittendrin abgebrochenen Verbindungsversuch erneut abgespielt, entsteht eine völlig neue kostenpflichtige Generierung; bereits gepushte Inhalte dürfen nicht mit dem neuen Ergebnis zusammengefügt werden.

Wenn Sie sich noch in der Auswahlphase befinden, können Sie zunächst die Modellseite von Kimi K3 aufrufen, um die Vertragsdetails kennenzulernen, und dann die Granularität Ihrer Retry-Strategie festlegen.

Praktische Checkliste

Fassen Sie die vorstehenden Regeln zu einer Checkliste zusammen, die bei Reviews Punkt für Punkt abgeglichen werden kann:

  • Unterscheidet der Client explizit zwischen den beiden Konsumpfaden Streaming und Nicht-Streaming, anstatt sich auf implizite Entscheidungen zu verlassen?
  • Behandelt das Nicht-Streaming-Parsing Text und reasoning_content getrennt, und gelangt reasoning_content nicht direkt in benutzersichtbare Texte?
  • Wird usage separat gespeichert und kann mit Geschäftsdatensätzen verknüpft werden?
  • Wird die strukturierte Ausgabe erst geparst, wenn die Antwort normal abgeschlossen und der Inhalt vollständig ist, und gibt es eine unabhängige Absicherung für Parsing-Fehler, Schema-Validierungsfehler, Geschäfts- und Evidenzvalidierungsfehler sowie finish_reason=length?
  • Wird beim Streaming-Lesen der Endzustand an einem nicht-leeren finish_reason erkannt, anstatt nur auf [DONE] zu warten?
  • Wird [DONE] nur als Stream-Endmarker betrachtet und bei fehlendem finish_reason als Abbruch markiert?
  • Wird die Nutzung nach dem vollständigen Lesen des Streams aus dem choices:[]-Frame aggregiert und nicht angenommen, dass [DONE] usage enthält?
  • Wird ein error-Frame im Stream als Fehler erkannt und nicht als normales Ende behandelt?
  • Wird der Retry nach Fehlertyp abgestuft und nur bei eindeutig nicht gesendeten Anfragen oder wenn die API-Dokumentation ausdrücklich garantiert, dass die Ablehnung vor der Ausführung erfolgt, wirksam?
  • Werden Timeout, Verbindungsabbruch, vollständige 5xx oder JSON-Parsing-Fehler als „Ergebnis unbekannt“ explizit behandelt, anstatt Retry-Sicherheit zu versprechen?
  • Gibt es eine Obergrenze für die Anzahl der Retries, und gibt es für jeden Retry Logs zur Überprüfung der Nutzung?
  • Wird eine Wiedergabe nach einem Streaming-Abbruch als neue Generierung betrachtet und nicht als Fortsetzung?

Diese Checkliste muss nicht auf einmal vollständig erfüllt werden, aber jeder Punkt entspricht einem real auftretenden Online-Problem. Behandeln Sie zuerst die beiden Punkte „Endzustandskriterium finish_reason“ und „Retry-Grenzen“ – der Nutzen ist am direktesten.

Ähnliche Artikel

Alle Artikel ansehen →

Starte mit persistenten KI-Artefakten

Hol dir deinen API-Key und rufe Bild-, Video- und Audiomodelle über eine einzige task-basierte API auf.

API-Dokumentation lesen