웹 스트리밍은 데이터를 청크 단위로 처리해 전체 페이로드 대기 없이 즉시 소비할 수 있게 하는 기술이다. 브라우저 표준 Streams API(ReadableStream, WritableStream, TransformStream)의 동작 원리부터 백프레셔 제어, Server-Sent Events, AI 응답 스트리밍 구현까지 코드 예제와 함께 설명한다.
핵심 포인트- 스트림의 세 가지 타입: ReadableStream(읽기), WritableStream(쓰기), TransformStream(변환)이 파이프라인으로 연결된다.
- 청크 크기는 데이터 소스, MTU, 네트워크 거리 등 여러 요인에 따라 달라지며, 직접 제어가 가능하다.
- 백프레셔(backpressure)는 생산자가 소비자보다 빠를 때 발생하며, writer.ready로 일시 정지·재개를 제어한다.
- Server-Sent Events(SSE)는 HTTP 연결을 유지하며 서버에서 클라이언트로 지속적으로 이벤트를 푸시하고, OpenAI 같은 AI 제공자가 토큰 스트리밍에 많이 사용한다.
- Vercel AI SDK의 OpenAIStream + StreamingTextResponse로 LLM 응답을 스트리밍으로 처리할 수 있다.
상세 정리- 기본 개념: 스트림은 데이터를 청크 단위로 비동기 처리해 대용량 데이터를 전체 로드 없이 순차적으로 처리할 수 있게 한다.
- ReadableStream: start(controller) 콜백에서 controller.enqueue()로 청크를 푸시하고, controller.close()로 스트림을 종료한다.
- 파이프라인: readableStream.pipeThrough(transformStream).pipeTo(writableStream)으로 변환과 쓰기를 연결한다. 텍스트를 대문자로 변환하는 TransformStream을 중간에 삽입하는 예제가 포함된다.
- Fetch API 통합: response.body.getReader()로 청크를 순차적으로 읽는다. reader.read()는 { value, done }을 반환하며, done이 true가 될 때까지 루프를 반복한다.
- 백프레셔 제어: WritableStream의 writer.ready promise가 스트림 준비 완료를 알린다. await writer.ready를 각 청크 전에 호출해 소비자 속도에 맞춰 생산자를 자동으로 조절한다.
- SSE 원리: WebSocket과 달리 단방향(서버→클라이언트)이고 일반 HTTP 연결을 재사용한다. 웹 스트림과의 차이점은 SSE는 장시간 연결을 유지한다는 것이다.
- SSE 파싱: eventsource-parser 라이브러리로 스트리밍 응답을 파싱한다. [DONE] 시그널 수신 시 controller.close()로 종료하고, 각 이벤트의 delta.content를 추출해 큐에 넣는다.
- Edge Function 점진적 렌더링: runtime을 "edge"로 설정하고 ReadableStream을 Response로 감싸 반환한다. 500ms 딜레이를 두고 HTML 청크를 순차 전송해 점진적 UI 렌더링을 구현한다.
- Vercel AI SDK 구현: OpenAIStream()이 스트리밍 응답을 ReadableStream으로 변환하고, StreamingTextResponse가 HTTP 응답으로 래핑한다. useChat/useCompletion 훅으로 클라이언트에서 청크를 실시간으로 UI에 반영한다.
왜 읽나Streams API를 처음 접하거나 LLM 스트리밍 응답 처리를 구현하려는 프론트엔드/풀스택 개발자에게 개념부터 실전 코드까지 이어지는 체계적인 레퍼런스.
Vercel Blog·
LINE Engineering·