BroadRouter

Paliwanag sa LLM streaming: SSE chunk, delta, usage at cancel

Ng BroadNet Inference team · 4 minutong basa · Nailathala · Na-update

Ini-stream ng LLM API ang chat completion bilang Server-Sent Events: may JSON chunk ang bawat data line, at dala ng choices[0].delta nito ang susunod na piraso ng text. Pagdugtungin ang mga delta, huminto sa data: [DONE], at itakda ang include_usage sa stream_options para makuha ang bilang ng token sa huling chunk na walang laman ang choices list. Para mag-cancel, isara ang connection.

Kung walang streaming, walang ibinabalik ang chat completion hangga’t hindi handa ang buong sagot. Ilang segundong katahimikan ang ibig sabihin ng 600-token na sagot sa mga 100 token bawat segundo. Kapag may streaming, lumalabas ang mga unang salita sa sandaling isulat ng model ang mga ito. Tinatalakay ng post na ito kung ano talaga ang dumadaan sa wire, paano ito i-parse, paano kunin ang token usage mula sa stream, at paano ito ihinto nang malinis. Para sa maikling bersyon ng mga patakarang partikular sa BroadNet, tingnan ang reference guide sa streaming.

Ano ang itsura ng SSE stream sa wire?

Ang Server-Sent Events ay plain na HTTP response na may Content-Type: text/event-stream. Pinapanatiling bukas ng server ang connection at sumusulat ng mga event. Ang bawat event ay isa o higit pang data: line na sinusundan ng blank line. Naglalagay ang mga OpenAI-compatible na API ng isang JSON chunk sa bawat event at nagtatapos sa literal na [DONE]:

data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}],"usage":null}

data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"One, "},"finish_reason":null}],"usage":null}

data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"two, three."},"finish_reason":"stop"}],"usage":null}

data: {"id":"c1","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":6,"total_tokens":20}}

data: [DONE]

Halimbawa lang at pinaikli ang hugis sa itaas. May model at created din ang mga totoong chunk, at puwedeng mag-ulat ng reasoning token sa usage ang mga reasoning model.

Ano ang laman ng isang chunk?

Field Saan Ano ang ibig sabihin
choices[0].delta.role Unang chunk Kadalasang assistant. Isang beses lang ipinapadala.
choices[0].delta.content Karamihan ng chunk Ang susunod na piraso ng text. Puwedeng walang laman.
choices[0].delta.tool_calls Mga tool call Mga piraso ng pangalan ng function at JSON arguments, na pagdudugtungin ayon sa index.
choices[0].finish_reason Huling content chunk stop, length o tool_calls. null hanggang doon.
usage Huling chunk, kung hiniling Kabuuan para sa buong request. null sa lahat ng iba.

Ang pangunahing ideya ay delta, hindi snapshot. Ang bago lang ang laman ng bawat chunk. Binubuo mo ang message sa pagdudugtong ng mga piraso ayon sa pagkakasunod. Ganito rin mag-stream ang mga tool call: dumarating ang arguments bilang mga piraso ng string na hindi valid na JSON hangga’t hindi dumarating ang huli, kaya i-parse lang ang mga ito pagkatapos maging tool_calls ang finish_reason.

Paano kunin ang token usage mula sa stream?

Laging may usage ang non-streamed na response. Wala nito ang stream, maliban kung hihilingin mo. Itakda ang stream_options: {"include_usage": true} at magpapadala ang server ng isang dagdag na chunk bago ang [DONE]. Nasa chunk na iyon ang kabuuan at isang walang lamang choices array. Sa BroadNet Inference, puwede ring kasama sa usage ang prompt_tokens_details.cached_tokens at completion_tokens_details.reasoning_tokens kapag iniuulat ng model, na siyang kailangan mo para sa pag-log ng gastos.

Ang karaniwang bug: nagtatapon ng index error sa usage chunk ang code na nagbabasa ng chunk.choices[0] sa bawat chunk. I-check muna ang choices.

Python: mag-stream, kunin ang usage, mag-cancel

import os
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

stream = client.chat.completions.create(
    model="broadnet/deepseek-v4.1-flash",  # DeepSeek V4.1 Flash, a reasoning model
    messages=[{"role": "user", "content": "Explain SSE in three sentences."}],
    stream=True,
    stream_options={"include_usage": True},
    max_tokens=2000,  # reasoning counts toward this limit
)

def user_pressed_stop():  # replace with your own condition
    return False

parts, usage, finish = [], None, None
try:
    for chunk in stream:
        if chunk.choices:
            choice = chunk.choices[0]
            if choice.delta.content:
                parts.append(choice.delta.content)
                print(choice.delta.content, end="", flush=True)
            if choice.finish_reason:
                finish = choice.finish_reason
        if chunk.usage:
            usage = chunk.usage
        if user_pressed_stop():  # your own condition
            break
finally:
    stream.close()  # closes the HTTP connection

text = "".join(parts)

Pinapahinto lang ng break ang pagbasa, pero nananatiling bukas ang socket hanggang ma-garbage collect ito. Isara ito nang tahasan para makita ng server ang disconnect.

Node: mag-stream gamit ang AbortController

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://inference.broadnet.ai/v1", apiKey: process.env.BROADNET_API_KEY });
const controller = new AbortController();
setTimeout(() => controller.abort(), 30_000); // hard stop after 30 s

const stream = await client.chat.completions.create(
  {
    model: "broadnet/deepseek-v4.1-flash",
    messages: [{ role: "user", content: "Explain SSE in three sentences." }],
    stream: true,
    stream_options: { include_usage: true },
  },
  { signal: controller.signal },
);

let text = "";
for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) text += delta;
  if (chunk.usage) console.log(chunk.usage);
}

Dinodokumento ng README ng openai-node ang signal option, at gumagana ito habang binabasa pa ang body. Sa isang web server, ikonekta ang controller.abort() sa close event ng request ng client para mapahinto rin ang generation kapag umalis sa page ang user. Mas maraming setup sa gabay sa Node SDK.

curl: tingnan ang mga raw na event

curl -N https://inference.broadnet.ai/v1/chat/completions \
  -H "Authorization: Bearer $BROADNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"broadnet/gemma-4-26b-a4b","stream":true,"stream_options":{"include_usage":true},"messages":[{"role":"user","content":"Count to five."}]}'

Ino-off ng -N ang output buffering para mag-print ang mga event habang dumarating. Pindutin ang Ctrl+C para mag-cancel; isinasara nito ang connection. Ginagawa ng API request builder ang request na ito, pati ang bersyon sa Python at Node, para sa kahit anong model at base URL.

Paano mag-cancel ng stream, at magkano ang gastos nito?

Ang pag-cancel sa SSE ay pagsara lang ng connection. Walang “stop” na message. Ang server ang bahala sa susunod na mangyayari: napapansin ng maayos na server ang saradong socket at humihinto sa pag-generate. Totoong trabaho ang mga token na nagawa bago ang sandaling iyon. Hindi dinodokumento ng API reference ng BroadNet ang pagsingil sa mga na-cancel na stream, kaya magplano na parang sinisingil sa pay-as-you-go ang mga token na nagawa hanggang sa disconnect, at i-check ang usage records mo. Sa flat na plan, walang dagdag na gastos ang na-cancel na stream, pero napapalaya lang ang session kapag huminto na ang server.

Limang streaming bug na dapat i-check

  1. Mga proxy na nagba-buffer. Nagba-buffer ng response ang Nginx at ilang CDN, kaya sabay-sabay na natatanggap ng client ang lahat. I-disable ang proxy buffering para sa streaming route.
  2. Walang check sa [DONE]. Mukhang maikling sagot ang naputol na connection. Ituring na hindi kumpleto ang walang [DONE] at i-record ang X-Request-ID, gaya ng inilalarawan ng gabay sa errors.
  3. Pag-retry sa gitna ng stream. Hindi nagre-retry ang mga SDK kapag nagsimula nang dumating ang body. Bagong request ang retry at, sa pay-as-you-go, bagong singil.
  4. Hindi pagpansin sa finish_reason: length. Sa mga reasoning model gaya ng DeepSeek V4.1 Flash, kasama ang pag-iisip sa max_tokens, kaya puwedeng huminto ang stream bago pa lumabas ang anumang nakikitang text dahil sa maliit na limit. Tingnan ang magkano ang reasoning token.
  5. Maling paghahati ng mga linya. Kung mano-mano mong pina-parse ang SSE, i-buffer ang mga byte hanggang makakita ka ng blank line. Puwedeng matapos ang isang TCP read sa gitna ng JSON chunk.

Saan bagay ang BroadNet Inference

Ginagamit ng BroadNet Inference ang standard na hugis ng OpenAI-compatible na streaming, kaya pina-parse ito ng Python at Node SDK nang walang pagbabago. Kasama sa usage ng huling chunk ang cached at reasoning token kapag iniuulat ng model. Sabi ng docs nito, dapat pa ring i-verify ang streaming kada model bago gamitin sa production, kaya patakbuhin ang code sa itaas laban sa eksaktong model na ilalabas mo. Kung pinakamahalaga sa iyo kung gaano kabilis dumating ang unang token, basahin ang TTFT vs throughput sunod. Kung kailangan mo ng realtime na voice sa WebSockets, hindi ginawa ang API na ito para doon; chat completions at file transcription ang inaalok nito.

Mga tanong

Ano ang pagkakaiba ng SSE at WebSockets para sa LLM streaming?

One-way ang SSE, mula server papuntang client, sa isang normal na HTTP response. Iyon lang ang kailangan ng chat completion, kaya SSE ang gamit ng mga OpenAI-compatible na API. Two-way ang WebSockets at nangangailangan ng protocol upgrade; ginagamit ito sa realtime na voice, hindi sa chat completions.

Bakit null ang usage sa mga streaming chunk ko?

Ipinapadala lang ang usage kapag hiniling mo. Idagdag ang stream_options na naka-true ang include_usage. Null na ang usage sa bawat chunk maliban sa huli, at dala ng huling chunk ang kabuuan na may walang lamang choices list.

Sisingilin ba ako kapag nag-cancel ako ng stream?

Magkakaiba ang mga provider at marami ang hindi nagdodokumento nito. Ipagpalagay na sinisingil ang mga token na nagawa bago napansin ng server ang saradong connection. I-log ang X-Request-ID at ihambing sa usage records mo.

Paano ko malalaman na normal na natapos ang stream?

Natanggap mo ang data: [DONE] at may finish_reason gaya ng stop ang huling content chunk. Kapag length ang finish_reason, pinutol ng max_tokens ang sagot. Kapag walang [DONE], naputol ang connection.

Pinapabilis ba ng streaming ang model?

Hindi. Pareho ang kabuuang oras ng generation. Pinapaikli ng streaming ang oras bago makita ng user ang mga unang salita, na siyang nagpaparamdam na mabilis ang isang chat interface.

Basahin bilang MarkdownTanungin ang ChatGPTTanungin ang ClaudeTanungin ang Perplexity