Unbekannter Fehler im LLM-Streaming: Ursachen und Lösungen

Was die Meldung dir tatsächlich sagt

Wenn du nach unbekannter Fehler im LLM-Streaming gesucht hast, schaust du wahrscheinlich auf eine Toast-Meldung oder eine rote Zeile in einem Chat-Frontend, einem Editor-Plugin oder einem Agenten-Framework. Die Formulierung stammt von diesem Client. Sie bedeutet, dass die App eine gestreamte Antwort angefordert hat, etwas vor oder während des Streams schiefgelaufen ist und die App nicht wusste, wie sie es beschreiben soll. Die API selbst meldet Probleme mit einem HTTP-Status und einem JSON-Fehlerkörper, und der Client hat diese Details verworfen.

Das ist gute Nachricht, denn das bedeutet, dass du die Details zurückgewinnen kannst. Sende dieselbe Anfrage außerhalb des Clients, lies die Statuszeile und den Körper, und die Ursache ist meist innerhalb von ein oder zwei Versuchen offensichtlich. Der Rest dieser Seite geht die Ursachen in der Reihenfolge durch, in der sie auf dieser API tendenziell auftreten, und gibt dir dann einen kleinen Streaming-Client, der den echten Fehler ausgibt, anstatt ihn zu verbergen.

Eines von Anfang an: Eine gestreamte Anfrage hat zwei Fehlerstellen. Sie kann vor dem ersten Byte fehlschlagen, wenn der Server die Anfrage ablehnt (falscher Schlüssel, falsche URL, ein Limit). Oder sie kann in der Mitte fehlschlagen, wenn die Verbindung abbricht, nachdem bereits Text angekommen ist. Die Lösungen unterscheiden sich, also notiere, welche der beiden du siehst. Wenn die Antwort nie beginnt, schaue in die Abschnitte zwei bis vier. Wenn sie beginnt und dann stoppt, schaue in den Abschnitt über Proxies und Timeouts.

Prüfe zuerst Base URL, Schlüssel und Modell

Die meisten Streaming-Fehler bei einer frischen Einrichtung stammen von drei kleinen Fehlern. Sie auszuschließen, dauert nur eine Minute.

1. Basis-URL. Sie muss https://api.uncensoredllmhub.com/v1 lauten, einschließlich /v1 und ohne ein abschließendes /chat/completions. Clients hängen den Pfad selbst an. Wenn du den vollständigen Endpunkt in ein Feld einfügst, das eine Basis erwartet, fordert der Client einen Pfad an, der nicht existiert, und meldet einen vagen Fehler.
2. Schlüssel. Der Header lautet Authorization: Bearer YOUR_KEY. Ein falsches Leerzeichen, ein mit dem Schlüssel kopierter Zeilenumbruch oder ein Schlüssel eines anderen Dienstes führen alle zum gleichen Fehler. Erstelle oder kopiere den Schlüssel erneut von der API-Schlüssel-Seite, wenn du dir unsicher bist.
3. Modell-ID. Das einzige Modell ist uncensored. Clients, die ein Dropdown anbieten, füllen oft einen Namen eines anderen Anbieters voraus. Gib die ID manuell ein und rufe GET /v1/models auf, um zu bestätigen, was der Server auflistet.

Eine schnelle Möglichkeit, alle drei gleichzeitig zu testen, ist der models-Aufruf. Er streamt nicht, also trennt er ein Verbindungs- oder Schlüsselproblem von einem Streaming-Problem:

Copycurl -i https://api.uncensoredllmhub.com/v1/models   -H "Authorization: Bearer $API_KEY"

Wenn dies eine normale Liste zurückgibt, sind die URL und der Schlüssel in Ordnung und du kannst aufhören, sie zu verdächtigen. Wenn es fehlschlägt, behebe das, bevor du etwas am Streaming änderst. Prüfe auch, ob dein Konto Guthaben hat: Die API sendet dein verbleibendes Guthaben im X-Balance-USD-Header bei Antworten, was praktisch ist, wenn ein Schlüssel nach intensiver Nutzung plötzlich nicht mehr funktioniert. Die Preisseite erklärt Aufladungen, und neue Konten können von der Schlüsselseite aus ein $0,50-Testguthaben beanspruchen.

Ratenlimits und der Stream, der seinen Slot belegt

Die nächsthäufigste Ursache ist HTTP 429. Es gibt drei Geschmacksrichtungen, und dein Client wird alle in dieselbe wenig hilfreiche Meldung packen.

Das Parallelitätslimit ist das, was die Leute überrascht, wegen der Art und Weise, wie Streaming funktioniert. Eine gestreamte Anfrage belegt ihren Slot, bis der Stream endet, nicht bis das erste Token ankommt. Wenn deine App für jede Nachricht einen Stream öffnet und den alten nie schließt, zum Beispiel weil der Nutzer die Seite verlassen hat und die UI vergessen hat, die Anfrage abzubrechen, bleiben diese Slots belegt. Bei einem Test-Schlüssel mit einem Limit von 2 reichen zwei verlassene Streams aus, damit die dritte Nachricht fehlschlägt.

Die Symptome sind konsistent. Die ersten paar Nachrichten funktionieren, dann beginnen Fehler, dann funktioniert alles wieder nach einer kurzen Wartezeit. Wenn das zutrifft, breche Streams ab, die du nicht mehr benötigst (ein AbortController im Browser, Schließen der Antwort auf einem Server), und begrenze die Anzahl der parallelen Aufrufe in deinem eigenen Code. Agenten sind die üblichen Übeltäter: Ein Planer, der zehn Function-Calling-Aufrufe gleichzeitig auslöst, wird das Limit auf einem Test-Schlüssel sofort erreichen.

Die Antwort-Header helfen dir zu sehen, wo du stehst. X-RateLimit-Limit-Requests und X-RateLimit-Limit-Concurrency zeigen die Limits, die für den verwendeten Schlüssel gelten, und X-Request-Id identifiziert den Aufruf, wenn du Support wegen ihm kontaktieren musst.

Anfragegröße und Kontextlänge

Eine Anfrage kann auch abgelehnt werden, weil sie zu groß ist. Zwei Zahlen sind wichtig. Der Körper darf maximal 8 MB groß sein, und der Prompt plus die Vervollständigung müssen in ein 100.000-Token-Kontextfenster passen. Chat-Frontends, die bei jedem Schritt die gesamte Konversation erneut senden, stoßen langsam an diese Grenzen und dann plötzlich: Der Chat funktioniert eine Stunde lang, dann kippt eine lange Nachricht oder eine eingefügte Datei ihn über die Grenze, und jeder spätere Schritt schlägt fehl, weil der Verlauf noch in der Anfrage ist.

Wenn der Fehler nach einer langen Sitzung beginnt, teste mit einem kurzen neuen Gespräch. Wenn das funktioniert, ist der Verlauf die Ursache. Kürze ihn, indem du alte Schritte entfernst, sie zu einer Nachricht zusammenfasst oder ein neues Chat startest. Große eingefügte Dokumente sind der andere Auslöser. Eine Textdatei mit einigen hundert Kilobyte ist in Ordnung, aber Base64-Blobs oder sehr große Logs können schneller 8 MB erreichen, als du erwartest.

Du musst max_tokens nicht setzen, da die Vervollständigung das verwenden kann, was vom Fenster übrig ist. Wenn du es doch setzt, stelle sicher, dass Prompt-Token plus max_tokens unter 100.000 bleiben. Ein Client, der ein großes max_tokens hart codiert, zusätzlich zu einem langen Verlauf, kann die Summe über das Fenster schieben, auch wenn der Prompt allein in Ordnung aussieht.

Proxies, Pufferung und Timeouts

Streaming nutzt server-sent events: eine langlebige HTTP-Antwort, die kleine Chunks liefert, sobald sie produziert werden. Alles zwischen dir und der API, das auf die ganze Antwort wartet, bevor es sie weiterleitet, wird das brechen. Das Ergebnis ist entweder lange Stille gefolgt von einem Burst, oder ein Timeout und der generische Fehler.

Suche nach diesen Punkten in deiner eigenen Einrichtung:

• Reverse Proxies. Wenn du die API durch nginx oder einen ähnlichen Proxy leitest, schalte die Antwortpufferung für diesen Standort aus und erhöhe den Read-Timeout über die längste Antwort, die du erwartest. Lange Antworten aus einem 100.000-Token-Fenster können eine Weile dauern.
• Unternehmens- oder Antivirus-Proxies. Einige untersuchen HTTPS-Verkehr und halten den Körper. Teste über einen Handy-Hotspot, um dies auszuschließen.
• Serverless Functions. Viele Plattformen begrenzen die Ausführungszeit oder puffern Antworten, es sei denn, du wählst Streaming aus. Wenn der Stream jedes Mal nach derselben Anzahl von Sekunden stirbt, ist ein Plattform-Zeitlimit die wahrscheinliche Ursache.
• Browser-Erweiterungen und VPNs. Selten, aber sie können inaktive Verbindungen unterbrechen.

Der Hinweis, der hierhin weist, ist ein Fehler in der Mitte einer Antwort, mit derselben Schnittzeit bei jedem Versuch. Ein Ratenlimit würde die Anfrage am Anfang ablehnen, also ist ein Mid-Stream-Schnitt, der immer bei, sagen wir, 30 Sekunden passiert, fast nie ein Limit.

Ein Client, der den echten Fehler zeigt

Verwende dies, wenn du die Wahrheit willst, statt der freundlichen Meldung. Er fängt OpenAI SDK-Ausnahmen ab, gibt den Status und den Fehlerkörper aus und liest den Retry-Hinweis, wenn einer vorhanden ist.

Copyimport time
from openai import OpenAI, APIConnectionError, APIStatusError, RateLimitError

client = OpenAI(
    base_url="https://api.uncensoredllmhub.com/v1",
    api_key="YOUR_API_KEY",
)

def stream_once(messages):
    stream = client.chat.completions.create(
        model="uncensored",
        messages=messages,
        stream=True,
    )
    for chunk in stream:
        if chunk.choices and chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="", flush=True)
        if getattr(chunk, "usage", None):
            print("\n[usage]", chunk.usage)

messages = [{"role": "user", "content": "Write two sentences about harbours."}]

for attempt in range(4):
    try:
        stream_once(messages)
        break
    except RateLimitError as e:
        wait = int(e.response.headers.get("retry-after", 5))
        print("429:", e.body, "- waiting", wait, "s")
        time.sleep(wait)
    except APIStatusError as e:
        print("status", e.status_code, e.body)
        print("request id:", e.response.headers.get("x-request-id"))
        break
    except APIConnectionError as e:
        print("connection problem:", e)
        time.sleep(2)

Die gleiche Idee in Node, mit einem Abort-Signal, damit verwaiste Streams ihren Slot freigeben:

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.uncensoredllmhub.com/v1",
  apiKey: process.env.API_KEY,
});

const controller = new AbortController();

try {
  const stream = await client.chat.completions.create(
    {
      model: "uncensored",
      messages: [{ role: "user", content: "Write two sentences about harbours." }],
      stream: true,
    },
    { signal: controller.signal }
  );
  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
  }
} catch (err) {
  console.error("status:", err.status, "body:", err.error);
}
// call controller.abort() when the user leaves the page

Und ein roher curl-Aufruf, der jeden Client aus dem Bild nimmt. -N schaltet cURLs eigene Pufferung aus und -i gibt die Statuszeile und Header aus, einschließlich X-Request-Id:

Copycurl -N -i https://api.uncensoredllmhub.com/v1/chat/completions   -H "Authorization: Bearer $API_KEY"   -H "Content-Type: application/json"   -d '{"model":"uncensored","stream":true,"messages":[{"role":"user","content":"Say hello."}]}'

Wenn curl Text gut streamt und deine App nicht, ist die API gesund und das Problem sitzt in der App, ihrem Proxy oder ihren Einstellungen. Wenn curl einen 429 oder einen anderen Status zeigt, hast du jetzt die genaue Ursache.

Retry-Regeln, die die Dinge nicht verschlimmern

Wiederholungen helfen bei vorübergehenden Problemen und schaden bei permanenten. Eine kurze Richtlinie hält dich aus der Patsche.

• Wiederhole 429 und abgebrochene Verbindungen. Warte auf Retry-After, wenn es vorhanden ist, andernfalls verzögere dich um ein paar Sekunden und füge etwas zufälliges Jitter hinzu, damit parallele Arbeiter nicht im Takt wiederholen.
• Wiederhole keine Authentifizierungsfehler oder zu große Anfragen. Das Ergebnis wird sich nicht ändern, und jede Wiederholung fügt nur Rauschen hinzu.
• Begrenze Versuche auf drei oder vier, und zeige dem Benutzer dann den echten Fehlertext.
• Begrenze deine eigenen parallelen Aufrufe unter das Schlüssel-Limit. Ein Semaphore von 6 auf einem vollen Schlüssel lässt Platz für ein zweites Tool, das denselben Schlüssel verwendet.
• Wenn ein Stream in der Mitte abbricht, behalte den teilweisen Text. Sende ihn erneut mit diesem Text als Assistent-Nachricht und bitte das Modell, fortzufahren, anstatt von vorne zu beginnen.

Fehlgeschlagene oder abgelehnte Anfragen werden nicht berechnet, also treibt das Debuggen mit wiederholten Testaufrufen dein Guthaben nicht ab. Erfolgreiche Aufrufe werden mit $0,15 pro 1M Eingabetokens und $0,50 pro 1M Ausgabetokens abgerechnet, und ein teilweiser Stream, der normal abgeschlossen wird, ist einfach eine kurze Antwort. Mehr Details zum Anfrageformat findest du in der API-Dokumentation.

Wenn du alles oben Genannte getan hast und die Meldung immer noch siehst, sende die X-Request-Id eines fehlgeschlagenen Aufrufs an die Support-Seite, mit der Zeit des Versuchs und ob der Fehler vor oder nach dem ersten Token kam. Diese Information reicht aus, um nachzuvollziehen, was passiert ist.

Weitere Anleitungen

• Wie du ein LLM selbst hostest oder es mit einer API überspringst
• Uncensored LLM Hub: Ein Endpunkt für Chat und Agenten
• Uncensored Ollama-Modelle vs. gehostete APIs