스트리밍이 없으면 클라이언트는 답변 전체가 끝날 때까지 기다립니다. 스트리밍을 쓰면 모델이 쓰는 대로 텍스트가 나타납니다.
작동 방식
스트리밍은 서버 전송 이벤트(SSE)를 씁니다. 서버는 콘텐츠 유형 text/event-stream으로 응답하고 연결을 열어 둡니다. MDN은 형식을 이렇게 설명합니다. field: value 형태의 줄로 이루어지며, 메시지는 “separated by a pair of newline characters.”(번역: 줄바꿈 문자 두 개로 구분된다)입니다.
Chat Completions 형식에서는 이벤트마다 작은 delta가 든 청크가 담깁니다.
data: {"choices":[{"index":0,"delta":{"content":"Hel"}}]}
data: {"choices":[{"index":0,"delta":{"content":"lo"}}]}
data: {"choices":[],"usage":{"prompt_tokens":12,"completion_tokens":2}}
data: [DONE]
클라이언트는 델타를 이어 붙입니다. 문자 그대로의 data: [DONE] 줄이 끝을 표시합니다. 사용량 청크는 요청에서 stream_options: {"include_usage": true}로 요청한 경우에만 나타납니다.
왜 중요한가
- 체감 속도. 사용자는 응답 전체가 아니라 첫 토큰까지의 시간이 지나면 첫 단어를 봅니다. 그 뒤로는 모델의 초당 토큰 수 속도로 텍스트가 흘러나옵니다.
- 긴 출력. 스트리밍은 연결을 계속 활성 상태로 유지하므로, 유휴 요청을 끊는 프록시가 있을 때 도움이 됩니다.
- 빠른 대응. 에이전트와 UI가 끝나기 전에 파싱이나 렌더링을 시작할 수 있습니다.
비용도 있습니다. OpenAI는 스트리밍이 콘텐츠 검수를 어렵게 한다고 지적하는데, “partial completions may be more difficult to evaluate.”(번역: 부분적인 완성 결과는 평가하기가 더 어려울 수 있다)이기 때문입니다. 스트림은 중간에 끊길 수도 있고, 스트리밍 중인 응답은 끝날 때까지 동시 실행 슬롯 하나를 차지합니다.
BroadNet Inference에서는
BroadNet은 https://inference.broadnet.ai/v1/chat/completions 주소에서 표준 chat completions 스트리밍 형식을 쓰므로 Python SDK와 Node SDK가 알아서 파싱합니다. curl을 쓴다면 -N을 추가해 버퍼링을 끄세요.
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 three."}]}'
추론 모델은 마지막 사용량 청크에 reasoning_tokens와 cached_tokens를 보고할 수 있습니다. [DONE] 전에 연결이 닫히면 답변을 불완전한 것으로 처리하고, X-Request-ID 헤더를 기록하고, 새 요청을 보내도 안전한지 판단하세요. BroadNet 문서는 프로덕션에서 의존하기 전에 실제로 배포할 모델에서 스트리밍을 검증하라고 안내합니다. 자세한 내용은 스트리밍 가이드와 오류와 재시도에 있습니다.
흔한 실수
- 닫힌 연결을 완료된 답변으로 처리하는 것. 완료를 뜻하는 것은
[DONE]뿐입니다. - 클라이언트 앞에 버퍼링하는 프록시를 두는 것. 그러면 응답이 한꺼번에 도착합니다.