스트리밍이 없으면 채팅 완성은 답변 전체가 준비될 때까지 아무것도 돌려주지 않습니다. 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 레퍼런스에는 취소된 스트림의 과금이 문서화되어 있지 않으므로, 종량제에서는 연결이 끊길 때까지 생성된 토큰이 과금된다고 보고 계획하며 사용 기록을 확인하세요. 정액 플랜에서는 취소된 스트림에 추가 비용이 들지 않지만, 세션은 서버가 생성을 멈춰야 비로소 풀립니다.
확인해야 할 스트리밍 버그 다섯 가지
- 버퍼링하는 프록시. Nginx와 일부 CDN은 응답을 버퍼링하므로 클라이언트가 모든 것을 한꺼번에 받습니다. 스트리밍 경로에서는 프록시 버퍼링을 끄세요.
[DONE]확인 누락. 끊긴 연결은 짧은 답변처럼 보입니다. 오류 가이드에서 설명하듯이,[DONE]이 없으면 불완전한 것으로 처리하고X-Request-ID를 기록하세요.- 스트림 도중 재시도. SDK는 본문이 도착하기 시작하면 재시도하지 않습니다. 재시도는 새 요청이며, 종량제에서는 새 과금입니다.
finish_reason: length무시. DeepSeek V4.1 Flash 같은 추론 모델에서는 사고 과정이 max_tokens에 포함되므로, 한도가 작으면 보이는 텍스트가 나오기도 전에 스트림이 멈출 수 있습니다. 추론 토큰의 비용을 참고하세요.- 줄을 잘못 나누기. SSE를 직접 파싱한다면 빈 줄이 나올 때까지 바이트를 버퍼에 모으세요. TCP 읽기는 JSON 청크 중간에서 끝날 수 있습니다.
BroadNet Inference는 어디에 적합한가요?
BroadNet Inference는 표준 OpenAI 호환 스트리밍 형식을 쓰므로 Python과 Node SDK가 그대로 파싱합니다. 마지막 청크의 usage에는 모델이 보고하는 경우 캐시된 토큰과 추론 토큰이 포함됩니다. 문서에 따르면 프로덕션에 쓰기 전에 모델별로 스트리밍을 확인해야 하므로, 위 코드를 실제로 배포할 모델에서 실행해 보세요. 첫 토큰이 얼마나 빨리 오는지가 주된 관심사라면 다음으로 TTFT vs 처리량을 읽어 보세요. WebSocket 기반 실시간 음성이 필요하다면 이 API는 그 용도로 만들어지지 않았습니다. 채팅 완성과 파일 전사를 제공합니다.
