Wat streaming je oplevert
Zonder streaming houdt de API het hele antwoord vast tot het model klaar is, en stuurt het dan als één JSON-lichaam. Voor een lang antwoord kan dit vele seconden een leeg scherm betekenen. Met stream: true stuurt de server hetzelfde antwoord als een reeks kleine gebeurtenissen, elk met een paar tekens van het antwoord, en je UI kan ze afdrukken zodra ze binnenkomen.
De draadindeling is server-sent events (SSE) over een normale HTTP-respons. Elke gebeurtenis is een regel die begint met data: gevolgd door een JSON-chunk, en de stream eindigt met data: [DONE]. Je parseert dit zelden handmatig, omdat de OpenAI-SDK's dit voor je doen. Als je de ruwe bytes wilt zien, toont het ontwikkelaarsoverzicht de endpoint-indeling en de API-documentatie somt elke parameter op.
Twee dingen zijn het overwegen waard voordat je code schrijft. Ten eerste: wie leest de stream: een browser die met je server praat, of alleen je server? Ten tweede: wat je doet als de verbinding halverwege breekt. De rest van deze pagina behandelt beide.
Python: stream met de OpenAI SDK
Installeer de SDK met pip install openai, maak een client aan met onze base URL en geef stream=True door. De model-ID is uncensored.
from openai import OpenAI
client = OpenAI(
base_url="https://api.uncensoredllmapi.com/v1",
api_key="YOUR_KEY",
)
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write a four-line poem about rain."}],
stream=True,
)
text = []
usage = None
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
piece = chunk.choices[0].delta.content
text.append(piece)
print(piece, end="", flush=True)
if getattr(chunk, "usage", None):
usage = chunk.usage
print()
print("tokens:", usage)
Let op de guard chunk.choices and .... De laatste chunk die gebruiksinformatie draagt, kan een lege choices-lijst hebben, en indexeren daarin veroorzaakt een fout. Stukjes verzamelen in een lijst en aan het eind samenvoegen is ook goedkoper dan herhaaldelijke string-concatenatie bij lange antwoorden.
Node: dezelfde aanroep in JavaScript
Met het officiële openai-pakket voor Node is de stream een async iterator. Dit voorbeeld gebruikt ES-modules.
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.uncensoredllmapi.com/v1",
apiKey: process.env.API_KEY,
});
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Name three uses for a stream." }],
stream: true,
});
let full = "";
let usage = null;
for await (const chunk of stream) {
const piece = chunk.choices?.[0]?.delta?.content;
if (piece) {
full += piece;
process.stdout.write(piece);
}
if (chunk.usage) usage = chunk.usage;
}
console.log("\nusage:", usage);
Als je de SDK niet wilt, werkt fetch ook: stuur hetzelfde JSON-lichaam met stream: true, lees dan response.body met een TextDecoder en split op lege regels. De SDK bespaart je het afhandelen van gebeurtenissen die in tweeën worden gesplitst bij een chunk-grens, wat de gebruikelijke bug is in handgeschreven parsers.
Usage en balans lezen
Gebruik wordt aan het einde van de stream gerapporteerd. Dat is het aantal dat je moet loggen voor kostenopvolging, omdat het is wat je saldo mee wordt belast. Bij $0,15 per 1M input tokens en $0,50 per 1M output tokens kost een antwoord met 1.200 input tokens en 800 output tokens 1.200 x 0,15 / 1.000.000 + 800 x 0,50 / 1.000.000 = $0,00018 + $0,0004 = $0,00058.
Elke respons bevat ook een X-Balance-USD-header met je resterende tegoed, zodat je een waarschuwing voor laag saldo kunt tonen zonder een tweede verzoek. Je kunt ook GET /v1/balance op een timer aanroepen. Mislukte of geweigerde verzoeken worden niet in rekening gebracht, wat betekent dat een fout vóór het eerste token niets kost.
Dezelfde responsheaders bevatten ook X-Request-Id. Sla deze op naast je eigen logregel voor elke stream. Als een stream zich vreemd gedraagt, is dat ID wat je aan support geeft zodat het verzoek kan worden gevonden.
Onderbroken streams en wat je ermee moet doen
Streams breken. Een telefoon schakelt van Wi-Fi naar mobiel data, een proxy sluit een inactieve verbinding, een gebruiker sluit het tabblad. Plan hier rekening mee vanaf het begin.
Bewaar de gedeeltelijke tekst
Voeg elk stuk toe aan een buffer zodra het aankomt en sla de buffer op wanneer de lus eindigt of een fout gooit. Als de stream faalde, heb je een bruikbaar half antwoord. Toon het met een retry-knop in plaats van het weg te gooien.
Opnieuw proberen of doorgaan
Het eenvoudigste herstel is het opnieuw verzenden van het oorspronkelijke verzoek. Voor een kort antwoord is dat prima. Voor een lang antwoord kun je de opgeslagen gedeeltelijke tekst als een assistant-bericht sturen en het model vragen om door te gaan waar het stopte. Het resultaat komt misschien niet overeen met wat de eerste stream zou hebben opgeleverd, dus behandel het als een best-effort en label het in je UI als nauwkeurigheid belangrijk is.
Sluit wat je verlaat
Een gestreamd verzoek bezet zijn concurrency slot tot de stream eindigt. Een volledige sleutel staat 8 gelijktijdige verzoeken toe, en een proefsleutel slechts 2. Als je server een stream blijft lezen voor een gebruiker die al weg is, blijft dat slot bezet. Annuleer het verzoek als de client disconnecteert. In Python, roep stream.close() aan; in Node, roep stream.controller.abort() aan.
Een stream doorsturen naar een browser
Zet je API-sleutel nooit in browsercode. De gebruikelijke setup is een klein endpoint op je eigen server dat de API aanroept met stream: true en elk stukje doorstuurt naar de pagina. In Node met Express, stel Content-Type: text/event-stream in, schrijf elk stukje als data: ... gevolgd door een lege regel, en luister naar het close-gebeurtenis op het verzoek om de upstream-oproep te annuleren. Op de pagina, EventSource behandelt GET-endpoints, terwijl fetch met een reader POST-lichamen behandelt, wat je nodig hebt wanneer je een berichtgeschiedenis stuurt.
Houd de berichtgeschiedenis op je server of in het verzoeklichaam, en knip de oudste beurten af wanneer het gesprek lang wordt. Het contextvenster is 100.000 tokens voor prompt plus voltooiing, wat veel chat is, maar een langlopende sessie zal dit uiteindelijk bereiken.
Rate limits tijdens streaming
De limieten zijn 300 verzoeken per minuut en 8 gelijktijdige verzoeken op een volledige sleutel, en 60 per minuut en 2 gelijktijdige op een proefsleutel. Overschrijden levert HTTP 429 op. De foutcode vertelt je welke limiet je raakte: rate_limited betekent te veel verzoeken per minuut, en concurrency betekent te veel tegelijk. Bij tijdelijke overbelasting retourneert de API ook 429 met een Retry-After: 5-header.
Omdat een 429 aankomt voordat er tokens worden gestreamd, moet je het afhandelen voordat je begint met lezen. Een kleine retry-wrapper is genoeg:
import time
from openai import OpenAI, RateLimitError
client = OpenAI(base_url="https://api.uncensoredllmapi.com/v1", api_key="YOUR_KEY")
def open_stream(messages, tries=4):
for n in range(tries):
try:
return client.chat.completions.create(
model="uncensored", messages=messages, stream=True
)
except RateLimitError as e:
wait = 5 if n == 0 else 5 * (n + 1)
time.sleep(wait)
raise RuntimeError("still rate limited")
Voor chat-apps met veel gebruikers is de echte oplossing voor concurrency-fouten een kleine wachtrij aan je kant die niet meer dan 8 live streams tegelijk toestaat.
Checklist voordat je een streaming chat releaseert
- Voorkom lege
choicesin het laatste fragment. - Buffer gedeeltelijke tekst en sla deze op bij een fout.
- Annuleer het upstream-verzoek wanneer de browser de verbinding verliest.
- Beperk live streams aan je gelijktijdigheidslimiet.
- Log verbruik en de verzoek-ID per stream.
- Schakel antwoordbuffering uit op elke omgekeerde proxy voor je server, anders komen tokens in bulten aan.
Het laatste punt verbaast veel eerste implementaties. Nginx buffert bijvoorbeeld proxied responses standaard, dus de stream werkt op localhost en lijkt in productie bevroren tot buffering voor die route is uitgeschakeld. Voor JSON output in plaats van vrije tekst, zie de notities over JSON-modus. Om de bovenstaande code te proberen, maak een API-sleutel aan; nieuwe accounts kunnen $0,50 aan proeftegoed claimen met één klik, geldig voor 7 dagen. Opwaarderingen zijn alleen crypto (USDT op TRC20 of USDC op Base), vanaf $20.
