웹 스트리밍(토큰) 데이터 송수신(SSE)

ChatGPT처럼 실시간으로 글자 쪼개어 뿌리기: 웹 스트리밍(토큰) 데이터 송수신 원리와 풀스택 구현 가이드

1. 웅장한 대기 시간은 끝났다: 전통적인 HTTP 응답과 스트리밍 방식의 근본적 패러다임 차이

우리가 평소에 작성하는 전통적인 HTTP 요청-응답 모델은 서버가 비즈니스 로직을 모두 수행하고, 데이터베이스 조회를 완전히 마친 뒤 완성된 하나의 덩어리(JSON 등)를 클라이언트에게 한 방에 내려줍니다. 데이터 크기가 작거나 연산이 빠를 때는 아무런 문제가 없습니다. 하지만 생성형 AI 모델이 긴 문장을 추론해 내거나, 대용량 로그 데이터를 가공해야 하는 상황이라면 어떨까요? 서버가 처리를 마칠 때까지 유저가 10초, 20초 동안 먹통이 된 빈 화면과 로딩 바만 바라봐야 하는 최악의 UX(사용자 경험)가 발생합니다.

이 긴 지연 시간을 혁신적으로 깨부수는 아키텍처가 바로 **스트리밍(Streaming) 방식**입니다. 서버는 전체 결과가 다 완성될 때까지 기다리지 않고, 준비되는 대로 데이터를 '토큰(Token)' 혹은 '청크(Chunk)' 단위로 쪼개어 클라이언트에게 실시간으로 계속 밀어냅니다. ChatGPT가 한 글자 한 글자 타이핑되듯 화면에 출력되는 원리가 바로 이겁니다. 첫 번째 글자가 도달하는 시간(TTFB, Time to First Byte)이 밀리초(ms) 단위로 단축되기 때문에, 유저는 전체 연산 시간이 똑같더라도 서비스가 압도적으로 빠르다고 체감하게 됩니다.

네트워크 아키텍처	데이터 송수신 방식 메커니즘	주요 활용 시나리오 및 장점
전통적 HTTP JSON	서버 내부 연산이 완벽히 종료될 때까지 커넥션을 유지하며 대기한 후, 단일 통으로 응답 처리.	일반적인 단발성 CRUD API, 정적 데이터 조회.
SSE (Server-Sent Events)	한 번의 HTTP 연결 후, 서버에서 클라이언트로 지속적인 text/event-stream 규격 기반 데이터 푸시.	AI 토큰 스트리밍 실시간 출력, 알림 피드, 실시간 시세 주입.

2. 기술적 뼈대: SSE(Server-Sent Events) 프로토콜의 표준 규격 이해

웹에서 스트리밍을 구현할 때 양방향 통신이 필요하다면 대공사인 웹 소켓(WebSocket)을 파야 하지만, 서버가 클라이언트에게 일방적으로 텍스트를 흘려보내는 구조라면 **SSE(Server-Sent Events)**가 최고의 대안입니다. SSE는 별도의 복잡한 가상 프로토콜을 쓰지 않고 오직 표준 HTTP 프로토콜 위에서 동작하므로 방화벽 통과도 쉽고 세션 관리가 매우 간결합니다.

SSE 스트리밍의 핵심은 HTTP 응답 헤더의 Content-Type: text/event-stream 바인딩에 있습니다. 이 헤더가 선언되는 순간 브라우저는 연결을 끊지 않고 상시 대기 상태로 들어갑니다. 그리고 서버는 데이터를 보낼 때 W3C 표준에 맞춰 data: {"text": "안녕"} \n\n 구조와 같이 반드시 접두어 data:와 끝을 알리는 두 번의 개행 문자(\n\n)를 패킷 끝에 붙여주어야 합니다. 이 약속된 규격만 지켜주면 브라우저에 내장된 API가 파싱 작업을 알아서 처리해 줍니다.

3. 백엔드 구현 스펙: Node.js (Express) 기반의 청크(Chunk) 스트리밍 서버 구축

실제 토큰 데이터를 0.5초 간격으로 쪼개서 클라이언트에게 스트리밍 형태로 밀어내는 Node.js 백엔드 엔드포인트 핵심 코드 레퍼런스입니다. 응답 버퍼링을 강제로 해제하는 설정이 포함되어 있습니다.

const express = require('express');
const app = express();

app.get('/api/stream', (req, res) => {
    // SSE 표준 및 캐싱 방지 헤더 필수 구성
    res.writeHead(200, {
        'Content-Type': 'text/event-stream',
        'Cache-Control': 'no-cache',
        'Connection': 'keep-alive'
    });

    const dummyTokens = ["인프라 ", "트래픽 ", "분산과 ", "실시간 ", "스트리밍 ", "연동 ", "성공!"];
    let index = 0;

    const intervalId = setInterval(() => {
        if (index < dummyTokens.length) {
            // 표준 규격 명세 바인딩 (data: 표기와 \n\n 마크다운 필수)
            res.write(`data: ${dummyTokens[index]}\n\n`);
            index++;
        } else {
            clearInterval(intervalId);
            res.end(); // 스트리밍 스트림 종료
        }
    }, 500);
});

app.listen(3000, () => console.log('Streaming Server Active on Port 3000'));

4. 프론트엔드 구현 스펙: 브라우저 Fetch API ReadableStream 파싱 기법

네이티브 EventSource 객체는 GET 요청만 지원하고 커스텀 헤더 인증 처리가 까다롭다는 치명적인 약점이 있습니다. 이를 극복하기 위해 실무에서는 POST 요청과 인증 토큰 주입이 자유로운 **Fetch API와 ReadableStream** 조합을 표준으로 채택합니다. 바이너리 스트림을 텍스트 조각으로 실시간 디코딩하여 화면에 즉시 렌더링하는 클라이언트 스크립트입니다.

async function startTokenStreaming() {
    const targetDiv = document.getElementById('output-screen');
    targetDiv.innerText = "";

    try {
        const response = await fetch('/api/stream', {
            method: 'GET', // POST 스펙 변환 및 Bearer 토큰 탑재 가능
            headers: { 'Accept': 'text/event-stream' }
        });

        // 최하위 스트림 리더 추출 연동
        const reader = response.body.getReader();
        const decoder = new TextDecoder('utf-8');

        while (true) {
            const { value, done } = await reader.read();
            if (done) break;

            // 바이트 청크 데이터를 문자열로 변환
            const chunkText = decoder.decode(value);
            
            // 표준 규격 파싱 처리 (data: 슬라이싱)
            const lines = chunkText.split('\n');
            for (const line of lines) {
                if (line.startsWith('data: ')) {
                    const token = line.slice(6);
                    // 화면에 토큰 조각을 파도치듯 결합 및 가치 렌더링
                    targetDiv.innerText += token;
                }
            }
        }
    } catch (error) {
        console.error('Streaming Failure:', error);
    }
}

5. 트러블슈팅 편: 스트리밍이 작동 안 하고 한방에 터지는 복병, Nginx 버퍼링 해결책

로컬 개발 환경에서는 글자가 한 땀 한 땀 아름답게 끊어져 나오던 스트리밍이, 실제 프로덕션 인프라 서버에만 올리면 다시 예전처럼 응답을 통째로 모았다가 한 방에 무겁게 출력되는 현상을 자주 만나게 됩니다. 십중팔구 중간에 서 있는 **Nginx나 리버스 프록시 장비의 프록시 버퍼링(Proxy Buffering)** 정책이 원인입니다.

Nginx는 기본적으로 백엔드 서버의 응답 패킷을 효율적으로 처리하기 위해 일정 크기만큼 버퍼에 데이터를 모았다가 클라이언트에게 전달하려는 성향이 있습니다. 대량 파일 다운로드에는 유리하지만 실시간 토큰 스트리밍에는 치명적인 방해 요소가 되죠. 이를 타파하려면 Nginx 설정 파일(nginx.conf)의 해당 라우팅 location 블록에 proxy_buffering off; 옵션을 명시해 주어야 합니다. 또는 백엔드 응답 헤더에 X-Accel-Buffering: no를 심어서 보내면 Nginx가 버퍼링을 하지 않고 청크 데이터를 들어오는 즉시 유저 브라우저로 패스해 주어 먹통 문제를 깔끔하게 해결할 수 있습니다.

📚 공식 기술 레퍼런스 (References)

• W3C Server-Sent Events Specification: "The EventSource Interface and Text/Event-Stream Wire Protocol Standard" 웹 크롤러 표준 참조
• MDN Web Docs Architecture Guide: "Using Server-Sent Events and Streams API with ReadableStream Controller" 자바스크립트 명세 인용
• Nginx Proxy Module Directives: "Module ngx_http_proxy_module - Tuning proxy_buffering and Chunked Responses" 공식 인프라 가이드라인 준수

---

#데이터스트리밍방법 #SSE토큰출력 #ServerSentEvents #FetchReadableStream #TextDecoder파싱 #Nodejs스트리밍서버 #Nginx버퍼링해제 #ChatGPT글자출력원리 #웹실시간데이터송수신