BroadRouter

LLM 스트리밍 원리: SSE 청크, 델타, usage, 취소

BroadNet Inference 팀 · 4분 분량 · 게시 · 업데이트

LLM API는 채팅 완성을 Server-Sent Events(SSE)로 스트리밍합니다. 각 data 줄에는 JSON 청크가 하나씩 담기며, 그 choices[0].delta에 다음 텍스트 조각이 들어 있습니다. 델타를 이어 붙이고 data: [DONE]에서 멈추세요. stream_options의 include_usage를 설정하면 choices 목록이 빈 마지막 청크에서 토큰 수를 받을 수 있습니다. 취소하려면 연결을 닫으세요.

스트리밍이 없으면 채팅 완성은 답변 전체가 준비될 때까지 아무것도 돌려주지 않습니다. 600토큰짜리 답변은 초당 약 100토큰 속도에서 몇 초 동안 아무 반응이 없습니다. 스트리밍을 쓰면 모델이 쓰는 즉시 첫 단어가 나타납니다. 이 글에서는 실제로 무엇이 전송되는지, 이를 어떻게 파싱하는지, 스트림에서 토큰 사용량을 어떻게 얻는지, 그리고 스트림을 어떻게 깔끔하게 멈추는지 다룹니다. BroadNet 전용 규칙을 짧게 보려면 스트리밍 레퍼런스 가이드를 참고하세요.

SSE 스트림은 실제로 어떻게 전송되나요?

Server-Sent Events는 Content-Type: text/event-stream을 가진 평범한 HTTP 응답입니다. 서버는 연결을 열어 둔 채 이벤트를 씁니다. 각 이벤트는 하나 이상의 data: 줄과 그 뒤의 빈 줄로 이루어집니다. OpenAI 호환 API는 이벤트마다 JSON 청크를 하나씩 넣고, 마지막에 문자 그대로의 [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]

위 형태는 설명을 위해 줄인 예시입니다. 실제 청크에는 model과 created도 들어 있으며, 추론 모델은 usage에 추론 토큰을 보고할 수 있습니다.

청크에는 무엇이 들어 있나요?

필드 위치 의미
choices[0].delta.role 첫 청크 보통 assistant. 한 번만 전송됩니다.
choices[0].delta.content 대부분의 청크 다음 텍스트 조각. 비어 있을 수 있습니다.
choices[0].delta.tool_calls 도구 호출 함수 이름과 JSON 인수의 조각. index별로 이어 붙입니다.
choices[0].finish_reason 마지막 콘텐츠 청크 stop, length 또는 tool_calls. 그전까지는 null.
usage 요청한 경우 마지막 청크 요청 전체의 합계. 나머지는 모두 null.

핵심은 스냅샷이 아니라 델타라는 점입니다. 각 청크에는 새로운 부분만 들어 있습니다. 조각을 순서대로 이어 붙여 메시지를 재구성합니다. 도구 호출도 같은 방식으로 스트리밍됩니다. 인수는 문자열 조각으로 도착하며 마지막 조각이 올 때까지 유효한 JSON이 아니므로, finish_reason이 tool_calls가 된 뒤에만 파싱하세요.

스트림에서 토큰 사용량은 어떻게 얻나요?

스트리밍하지 않는 응답에는 항상 usage가 들어 있습니다. 스트림에는 요청하지 않는 한 없습니다. stream_options: {"include_usage": true}를 설정하면 서버가 [DONE] 앞에 청크를 하나 더 보냅니다. 이 청크에는 합계와 빈 choices 배열이 들어 있습니다. BroadNet Inference에서는 모델이 보고하는 경우 usage에 prompt_tokens_details.cached_tokens와 completion_tokens_details.reasoning_tokens도 포함되며, 이는 비용 로깅에 필요한 값입니다.

흔한 버그가 있습니다. 모든 청크에서 chunk.choices[0]을 읽는 코드는 usage 청크에서 인덱스 오류를 냅니다. choices를 먼저 확인하세요.

Python: 스트리밍, usage 수집, 취소

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)

break만으로는 읽기만 멈출 뿐, 소켓은 가비지 컬렉션될 때까지 열려 있습니다. 서버가 연결 종료를 알 수 있도록 명시적으로 닫으세요.

Node: 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);
}

openai-node README에 signal 옵션이 문서화되어 있으며, 본문을 읽는 중에도 동작합니다. 웹 서버에서는 controller.abort()를 클라이언트 요청의 close 이벤트에 연결해, 사용자가 페이지를 떠나면 생성도 멈추게 하세요. 자세한 설정은 Node SDK 가이드에 있습니다.

curl: 원시 이벤트 보기

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."}]}'

-N은 출력 버퍼링을 꺼서 이벤트가 도착하는 대로 출력되게 합니다. 취소하려면 Ctrl+C를 누르세요. 그러면 연결이 닫힙니다. API 요청 빌더는 어떤 모델과 base URL에 대해서든 이 요청과 Python, Node 버전을 생성해 줍니다.

스트림은 어떻게 취소하며, 비용은 얼마나 드나요?

SSE에서 취소란 연결을 닫는 것뿐입니다. “중지” 메시지는 없습니다. 그다음은 서버에 달려 있습니다. 잘 동작하는 서버는 소켓이 닫힌 것을 알아채고 생성을 멈춥니다. 그 시점 전에 생성된 토큰은 실제로 수행된 작업입니다. BroadNet API 레퍼런스에는 취소된 스트림의 과금이 문서화되어 있지 않으므로, 종량제에서는 연결이 끊길 때까지 생성된 토큰이 과금된다고 보고 계획하며 사용 기록을 확인하세요. 정액 플랜에서는 취소된 스트림에 추가 비용이 들지 않지만, 세션은 서버가 생성을 멈춰야 비로소 풀립니다.

확인해야 할 스트리밍 버그 다섯 가지

  1. 버퍼링하는 프록시. Nginx와 일부 CDN은 응답을 버퍼링하므로 클라이언트가 모든 것을 한꺼번에 받습니다. 스트리밍 경로에서는 프록시 버퍼링을 끄세요.
  2. [DONE] 확인 누락. 끊긴 연결은 짧은 답변처럼 보입니다. 오류 가이드에서 설명하듯이, [DONE]이 없으면 불완전한 것으로 처리하고 X-Request-ID를 기록하세요.
  3. 스트림 도중 재시도. SDK는 본문이 도착하기 시작하면 재시도하지 않습니다. 재시도는 새 요청이며, 종량제에서는 새 과금입니다.
  4. finish_reason: length 무시. DeepSeek V4.1 Flash 같은 추론 모델에서는 사고 과정이 max_tokens에 포함되므로, 한도가 작으면 보이는 텍스트가 나오기도 전에 스트림이 멈출 수 있습니다. 추론 토큰의 비용을 참고하세요.
  5. 줄을 잘못 나누기. SSE를 직접 파싱한다면 빈 줄이 나올 때까지 바이트를 버퍼에 모으세요. TCP 읽기는 JSON 청크 중간에서 끝날 수 있습니다.

BroadNet Inference는 어디에 적합한가요?

BroadNet Inference는 표준 OpenAI 호환 스트리밍 형식을 쓰므로 Python과 Node SDK가 그대로 파싱합니다. 마지막 청크의 usage에는 모델이 보고하는 경우 캐시된 토큰과 추론 토큰이 포함됩니다. 문서에 따르면 프로덕션에 쓰기 전에 모델별로 스트리밍을 확인해야 하므로, 위 코드를 실제로 배포할 모델에서 실행해 보세요. 첫 토큰이 얼마나 빨리 오는지가 주된 관심사라면 다음으로 TTFT vs 처리량을 읽어 보세요. WebSocket 기반 실시간 음성이 필요하다면 이 API는 그 용도로 만들어지지 않았습니다. 채팅 완성과 파일 전사를 제공합니다.

자주 묻는 질문

LLM 스트리밍에서 SSE와 WebSocket은 무엇이 다른가요?

SSE는 일반 HTTP 응답 위에서 서버에서 클라이언트로 가는 단방향 통신입니다. 채팅 완성에는 그것으로 충분하므로 OpenAI 호환 API는 SSE를 씁니다. WebSocket은 양방향이며 프로토콜 업그레이드가 필요합니다. 채팅 완성이 아니라 실시간 음성에 쓰입니다.

스트리밍 청크에서 usage가 null로 나오는 이유는 무엇인가요?

usage는 요청할 때만 전송됩니다. include_usage를 true로 설정한 stream_options를 추가하세요. 그러면 마지막 청크를 제외한 모든 청크의 usage는 null이고, 마지막 청크가 빈 choices 목록과 함께 합계를 담습니다.

스트림을 취소해도 요금이 부과되나요?

제공업체마다 다르며 문서화하지 않은 곳이 많습니다. 서버가 연결이 닫힌 것을 알아차리기 전에 생성된 토큰은 과금된다고 가정하세요. X-Request-ID를 로그에 남기고 사용 기록과 비교하세요.

스트림이 정상적으로 끝났는지 어떻게 알 수 있나요?

data: [DONE]을 받았고, 마지막 콘텐츠 청크의 finish_reason이 stop 같은 값이면 정상 종료입니다. finish_reason이 length라면 max_tokens 때문에 답변이 잘린 것입니다. [DONE]이 없다면 연결이 끊긴 것입니다.

스트리밍을 쓰면 모델이 빨라지나요?

아닙니다. 전체 생성 시간은 같습니다. 스트리밍은 사용자가 첫 단어를 보기까지의 시간을 줄여 주며, 그 덕분에 채팅 화면이 빠르게 느껴집니다.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기