BroadRouter
시작하기

서버 전송 이벤트(SSE, Server-Sent Events)

업데이트

서버 전송 이벤트(SSE, Server-Sent Events)는 서버가 text/event-stream 콘텐츠 타입의 오래 유지되는 HTTP 응답 하나로 클라이언트에 텍스트 이벤트 스트림을 보내는 웹 표준입니다. 각 이벤트는 data: 같은 필드 줄 하나 이상으로 이루어지며 빈 줄로 끝납니다.

다른 이름: 서버 전송 이벤트, 서버 센트 이벤트, SSE 스트리밍, 이벤트 스트림, SSE, server-sent events, text/event-stream, event stream, EventSource

SSE는 스트리밍되는 거의 모든 LLM 응답 밑에 깔린 일반 텍스트 프레이밍입니다. 형식을 알아 두면 SDK를 쓸 수 없거나 스트림이 이상하게 동작할 때 도움이 됩니다.

작동 방식

형식은 WHATWG HTML 표준이 정의합니다. 응답의 MIME 타입은 text/event-stream이고 항상 UTF-8입니다. 본문은 field: value 형태의 줄로 이루어집니다.

: keep-alive comment, ignored by clients

event: update
id: 42
data: first line
data: second line

data: {"choices":[{"delta":{"content":"Hi"}}]}

data: [DONE]

중요한 파싱 규칙은 다음과 같습니다.

  • 빈 줄이 이벤트를 전달합니다. 빈 줄이 오기 전까지 클라이언트는 버퍼에 쌓아 둡니다.
  • 여러 data: 줄은 줄바꿈으로 이어져 메시지 하나가 됩니다.
  • 콜론으로 시작하는 줄은 주석입니다. 서버는 유휴 연결을 유지하려고 이를 보냅니다.
  • 콜론 뒤의 공백 하나는 제거됩니다. 줄은 CRLF, LF, CR 중 무엇으로든 끝날 수 있습니다.
  • **event, id, retry**는 각각 이벤트 타입, 마지막 이벤트 ID, 밀리초 단위의 재연결 지연을 정합니다.

네트워크 읽기 단위는 이벤트와 맞아떨어지지 않습니다. 한 번 읽을 때 이벤트 절반이 들어올 수도, 세 개가 들어올 수도 있습니다. 따라서 파서는 읽기 단위가 아니라 빈 줄을 기준으로 바이트를 버퍼링하고 나눠야 합니다.

재연결, 프록시, [DONE]

표준에는 브라우저용 복구 기능이 내장되어 있습니다. 연결이 끊기면 EventSource가 다시 연결하면서 Last-Event-ID 헤더를 보내고, 서버는 HTTP 204로 재시도를 멈출 수 있습니다. 명세는 또한 “legacy proxy servers”(번역: 레거시 프록시 서버)가 짧은 타임아웃 후 HTTP 연결을 끊을 수 있다고 경고하며, “every 15 seconds or so”(번역: 대략 15초마다) 주석 줄을 보내라고 제안합니다.

LLM API는 이 기능을 덜 씁니다. OpenAI Chat Completions 스트림은 data: 줄만 보내고 data: [DONE]으로 끝나는데, 이는 SSE가 아니라 API의 관례입니다. 재개할 이벤트 ID가 없으므로 끊긴 스트림은 이어서 받을 수 없고, 재시도는 새 요청이 됩니다. 스트리밍의 전체 그림과 첫 토큰까지의 시간 단축 효과는 해당 페이지에서 다룹니다.

BroadNet Inference에서는

BroadNet 문서는 stream=true를 설정하고 “read Server-Sent Events until the literal data: [DONE] marker”(번역: data: [DONE] 표시가 그대로 나올 때까지 서버 전송 이벤트를 읽을 것)라고 안내합니다. 그 전에 연결이 끝나면 응답을 불완전한 것으로 취급하고, X-Request-ID 헤더를 기록한 뒤, 새 추론 요청을 보내도 안전한지 판단하세요. stream_options: {"include_usage": true}를 쓰면 사용량은 마지막 청크로 옵니다. 문서의 curl 예시는 curl이 버퍼링하지 않도록 -N을 씁니다. 스트림은 끝날 때까지 동시 처리 슬롯 하나를 차지합니다. 종량제 키는 동시 처리 4 건, 시간제 키는 1건입니다. 문서는 프로덕션에 쓰기 전에 모델별로 스트리밍을 확인하라고 권합니다. SDK별 코드는 스트리밍 가이드에 있고, 청크 내용은 LLM 스트리밍 쉽게 이해하기에서 설명합니다.

자주 묻는 질문

LLM API에 브라우저의 EventSource API를 쓸 수 있나요?

보통은 바로 쓸 수 없습니다. 명세의 EventSource 생성자는 URL과 withCredentials 플래그만 받기 때문에 POST 본문이나 Authorization 헤더를 보낼 수 없습니다. fetch로 받아 스트림을 직접 파싱하거나 SDK를 쓰세요.

"data: [DONE]"은 무슨 뜻인가요?

SSE 표준의 일부가 아닙니다. OpenAI 방식 API가 응답이 끝났음을 알리려고 마지막 이벤트로 "data: [DONE]"이라는 줄을 그대로 보내는 것입니다.

스트림이 한꺼번에 도착하는 이유는 무엇인가요?

리버스 프록시, 프레임워크, -N 없이 실행한 curl처럼 서버와 코드 사이의 무언가가 응답을 버퍼링하고 있기 때문입니다. 해당 경로의 버퍼링을 끄세요.

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