스트리밍을 쓰면 에이전트나 채팅 인터페이스가 답변을 생성되는 대로 보여 줄 수 있습니다. BroadNet Inference는 표준 chat completions 스트리밍 형식을 쓰므로 OpenAI Python SDK와 OpenAI Node SDK가 파싱을 대신 처리합니다.
curl로 스트리밍하기
curl -N -D stream-headers.txt 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 from one to three."}]}'
-N은 curl의 버퍼링을 끄고, -D는 X-Request-ID를 포함한 응답 헤더를 파일로 저장합니다.
스트림은 어떤 모습인가요?
응답은 Server-Sent Events 스트림입니다. WHATWG HTML 표준에 따르면 각 이벤트는 하나 이상의 data: 줄과 그 뒤의 빈 줄로 이루어지며, 콜론으로 시작하는 줄은 무시해도 되는 주석입니다. data: 줄마다 JSON 청크가 하나씩 담기고, 텍스트는 choices[0].delta.content에 들어 있습니다.
지켜야 할 규칙
- 문자 그대로의
data: [DONE]줄이 올 때까지 이벤트를 읽은 뒤 리더를 닫으세요. stream_options: {"include_usage": true}를 보내면[DONE]직전에 청크가 하나 더 옵니다. 이 청크에는 요청 전체의usage와 빈choices리스트가 담겨 있으므로, 인덱스로 접근하기 전에choices를 확인하세요.- 모델이 보고하는 경우 이 usage에는
completion_tokens_details.reasoning_tokens(DeepSeek V4.1 Flash, GLM 5.3, Qwen3.8 27B는 먼저 추론합니다)와prompt_tokens_details.cached_tokens가 포함됩니다. 캐시된 토큰은 더 낮은 캐시 입력 가격으로 과금됩니다.
Python SDK로 스트리밍하기
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/gemma-4-26b-a4b",
messages=[{"role": "user", "content": "Count from one to three."}],
stream=True,
stream_options={"include_usage": True},
)
usage = None
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
if chunk.usage:
usage = chunk.usage
print()
print(usage) # None means the stream ended before the usage chunk
SDK가 [DONE]까지 대신 읽어 줍니다. 마지막 줄에서 usage가 None이면 usage 청크가 오기 전에 스트림이 끝났다는 뜻입니다. 같은 루프를 JavaScript로 작성한 예는 OpenAI Node SDK 가이드에 있습니다.
스트림이 중간에 끊겼을 때
[DONE] 전에 연결이 닫히면 답변은 불완전합니다. BroadNet의 안내는 다음과 같습니다.
X-Request-ID를 기록하세요.- 애플리케이션이 새 요청을 안전하게 보낼 수 있는지 판단하세요. 재시도는 새로운 추론이며, 종량제에서는 다시 과금됩니다.
무제한 플랜을 쓰는 에이전트라면 재시도에 추가 비용이 들지 않지만, 재시도가 실행되는 동안에는 세션을 점유합니다.
BroadNet 문서에 따르면 프로덕션에서 스트리밍에 의존하기 전에 모델별 릴리스 검증이 여전히 필요합니다. 실제로 배포할 모델로 테스트하세요.
문제 해결
- 모든 내용이 마지막에 한꺼번에 출력됩니다. curl에는
-N이 필요합니다. 자체 프록시를 거친다면text/event-stream응답의 버퍼링을 끄세요. - 마지막 청크에서
IndexError또는undefined가 발생합니다. usage 청크의choices리스트는 비어 있습니다.[0]을 읽기 전에chunk.choices를 확인하세요. - usage가 전혀 오지 않습니다.
stream_options를 보내지 않았거나, 마지막 청크 전에 스트림이 끊긴 것입니다. finish_reason이length이고 텍스트가 거의 없는 채로 스트림이 멈춥니다. 추론 모델이max_tokens를 추론에 다 썼습니다. 추론 모델이 빈 응답을 반환하는 이유를 참고하세요.- 병렬로 스트리밍하다가 429가 발생합니다. 열려 있는 스트림은 각각 처리 중인 요청 하나로 계산됩니다. 종량제 키는 동시 처리 4 건까지 허용합니다. BroadNet 오류 코드와 재시도를 참고하세요.
