스트리밍 AI 인터페이스가 연결 끊김에 살아남게 만들기: Claude Code 및 Vercel AI SDK를 활용한 실용적 아키텍처

고요한 스트림 드롭으로 인해 새벽 3시에 호출되는 온콜 알림만큼 취약한 프론트엔드 아키텍처를 노출시키는 것은 없습니다. 스트리밍 채팅 UI는 항상 localhost에서 로컬 데모를 통과하지만, 프로덕션에서는 빠르게 깨집니다. 개발자가 Wi-Fi를 토글하거나, 기업 프록시가 SSE(Server-Sent Events) 스트림을 타임아웃될 때까지 버퍼링하거나, 모델이 React가 프레임을 드롭할 때까지 초당 80개의 토큰을 방출하는 식입니다. 실제 엔지니어링 문제는 첫 번째 토큰을 렌더링하는 것이 결코 아니며, 스트림이 중간에 무너질 때 결정론적 UI 상태를 보존하는 것입니다.

이러한 운영상의 현실은 anthropics/claude-code와 같은 터미널 에이전트를 평가할 때 특히 크게 다가옵니다. Claude Code는 CLI(Command Line Interface)에서 실행되며, 전체 리포지토리 트리를 읽고, 여러 단계의 편집을 계획하며, 자연어 지시를 통해 Git 워크플로우를 구동합니다. 이러한 에이전트 워크로드를 웹에 통합하거나 미러링하는 것은

최신 Vercel AI SDK 모델은 메시지를 레거시 문자열(string) 대신 구조화된 parts로 분할합니다. 이러한 분리는 매우 중요합니다. 에이전트가 텍스트와 함께 구조화된 도구 호출(tool invocations)을 방출할 때, 플랫한 문자열 디코더는 중요한 메타데이터를 버립니다. 또한, 라우트는 반드시 req.signal을 전파해야 합니다. 성급한 사용자가 '중지' 버튼을 누르면, 서버는 렌더링되지 않은 토큰에 값비싼 GPU 사이클을 소모하는 대신 업스트림 추론(upstream inference)을 즉시 종료해야 합니다.

다음은 명시적인 스트림 타임아웃과 안티-버퍼링 헤더를 구현한 Next.js 라우트와 React 클라이언트입니다:

// app/api/chat/route.ts
import {
  convertToModelMessages,
...

세 가지 운영 안전장치를 주목하세요:

1. **X-Accel-Buffering: no**는 Nginx 및 리버스 프록시가 청크를 4KB/8KB 버퍼에 보관하는 대신 즉시 스트리밍하도록 강제합니다.
2. **firstChunkMs: 15_000**은 사용자가 정지된 커서를 응시하기 전에 콜드 스타트(cold-start) 업스트림 지연을 포착합니다.
3. **chunkMs: 20_000**는 소켓이 열린 상태로 남아 있으면서 업스트림 호스트가 패킷을 조용히 드롭하는 반쯤 열린 TCP 연결을 감지합니다.

부하 조건에서 취미 구현(Toy Implementations)이 실패하는 이유

대부분의 기본적인 튜토리얼은 원시 ReadableStream을 문자열 누산기(string accumulator)로 파이프합니다. 이 접근 방식은 세 가지 즉각적인 엣지 케이스를 초래합니다:

• 청크 경계 손상: TCP 청크는 SSE 이벤트나 유효한 멀티바이트 UTF-8 시퀀스와 1:1 매핑되지 않습니다. 코드 포인트(code-points)를 가로질러 슬라이싱하면 깨진 렌더링(``)이 발생합니다.
• 취소와 오류의 혼동: 사용자가 '중지' 버튼을 클릭하는 것은 의도적인 중단입니다. 이를 치명적인 500 오류로 처리하면 불필요한 오류 토스트가 발생하고 재시도 버튼이 비활성화됩니다. 클라이언트는 부분 출력을 유효한 과거 컨텍스트로 보존해야 합니다.
• 메인 스레드 토큰 변동: 매 5ms 토큰 변화마다 거대한 Markdown AST를 다시 파싱하는 것은 UI 스레드를 잠급니다. 스트리밍 레이어는 원시 텍스트 업데이트를 처리해야 하며, 무거운 구문 강조(syntax highlighting)는 블록이 안정화될 때까지 디바운스(debounce)되어야 합니다.

Relay 통합 및 프로덕션 트레이드오프

OpenAI와 호환되는 릴레이(relay)를 사용하면 애플리케이션 코드를 특정 제공업체 클라이언트 라이브러리로부터 분리할 수 있습니다. Vercel AI SDK 채팅 인터페이스를 버퍼링되지 않은 SSE 릴레이에 직접 연결하면 리버스 프록시 버퍼링 지연을 제거하고 멀티 모델 설정 전반의 엔드포인트 라우팅을 단순화합니다.

하지만 호환성은 JSON 스키마가 아닌 와이어 레벨(wire-level) 동작에 의해 정의됩니다. 릴레이 계층이 AbortController 신호를 상위로 적극적으로 전달하는지, 에지 프록시를 활성화하기 위해 주기적인 keep-alive 주석(`: keep-alive

`)을 전송하는지, 그리고 청크 순서를 엄격하게 보존하는지 확인해야 합니다.

텔레메트리(telemetry)를 캡처할 때는 다음 트랜스포트 메타데이터를 기록하세요: 상관관계 ID(correlation IDs), 첫 토큰까지 걸리는 시간(Time-to-First-Token, TTFT), 완료 플래그, 그리고 TCP 연결 끊김 원인. 로그 싱크에는 원본 프롬프트와 민감한 코드베이스 경로는 포함하지 마세요.

결론: 스트리밍 신뢰성 딜레마

웹 프런트엔드가 단순 채팅 입력과 Claude Code 같은 에이전트 시스템 사이의 격차를 메우면서, 가장 어려운 설계 문제는 모델 품질에서 전송 탄력성(transport resiliency)으로 이동하고 있습니다. 여러분은 즉각적인 렌더링 응답과 네트워크 백프레셔(backpressure), 클라이언트 측 AST 파싱 트래싱(thrashing) 사이에서 끊임없이 균형을 맞추고 있습니다.

여러 팀은 높은 부하 상태의 게이트웨이 토폴로지를 어떻게 처리하고 있나요? 직접적인 SSE 통과를 사용하는 에지 런타임을 신뢰하시나요, 아니면 인증 및 스트림 검증을 상위 게이트웨이에 오프로드(offloading) 하시나요? 아래 댓글에 여러분의 경험담을 공유해 주세요.