스트리밍 응답, 왜 붙이면 챗봇이 달라 보일까

직접 만든 챗봇을 친구한테 보여줬는데 "야, 이거 ChatGPT랑 다르게 왜 다 쓰고 나서 한 번에 나와?" 라는 말 들어본 적 있어요? 저는 있습니다. 처음 API 붙일 때 응답을 그냥 기다렸다가 한꺼번에 출력하면 딱 그 느낌이 나거든요. 타이핑되는 것처럼 한 글자씩 흘러나오는 게 아니라, 3~4초 침묵하다가 텍스트가 와르르 쏟아지는. 기능은 똑같아도 "뭔가 다르다"는 인상을 주는 부분이 바로 이 스트리밍 구현 여부입니다.

이 글은 Claude API로 스트리밍 응답을 붙여보려는 분들 위한 거예요. 코드 몇 줄 보여주고 끝나는 게 아니라, 왜 이걸 써야 하는지부터 실제로 어디서 막히는지까지 같이 짚어볼게요.

스트리밍이 뭔지 모르면 왜 쓰는지도 모른다

스트리밍 응답이란 쉽게 말하면 이런 거예요. 모델이 응답 전체를 다 만들 때까지 기다렸다가 한 번에 보내는 게 아니라, 생성되는 토큰을 즉시즉시 클라이언트한테 흘려보내는 방식입니다. HTTP에서 Transfer-Encoding: chunked나 SSE(Server-Sent Events) 방식으로 구현돼요.

사용자 입장에서 체감 차이가 꽤 크거든요. 예를 들어 300토큰짜리 응답을 생성하는 데 3초가 걸린다고 할 때, 논스트리밍은 3초 기다렸다가 전부 나오고, 스트리밍은 0.1초 간격으로 한 단어씩 흘러나옵니다. 결과를 받는 총 시간은 같아도 느껴지는 속도가 완전히 달라요. 이게 UX에서 "지각된 응답성"이라고 부르는 겁니다. 실제로 빠른 게 아니라 빠른 것처럼 느껴지게 만드는 거죠.

Python에서 실제로 어떻게 붙이냐면

Claude API 기본 연결 방법은 Claude API, 처음 연결하는 날 생기는 일들에서 다뤘으니 거기서 기본 세팅을 먼저 하고 오면 더 빠르게 따라올 수 있어요.

기본 호출 코드에서 스트리밍으로 바꾸는 건 생각보다 간단합니다. 핵심은 stream=True 옵션 하나예요.

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "양자역학 쉽게 설명해줘"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

messages.create() 대신 messages.stream()을 쓰고, 반환된 스트림 객체에서 text_stream을 이터레이트하면 됩니다. flush=True는 꼭 넣어야 해요. 안 넣으면 버퍼링 때문에 터미널에서 한 번에 나오는 것처럼 보이거든요. 이거 빠뜨리고 "어? 스트리밍 안 되는데?" 하는 경우가 꽤 있습니다.

전체 응답 텍스트가 필요하면 루프 끝나고 stream.get_final_message()로 받으면 되고요.

웹 서비스에 붙이려면 SSE를 알아야 한다

터미널에서 출력하는 건 위에서 됐는데, 실제 웹 챗봇에 붙이려면 한 단계가 더 있어요. 브라우저까지 스트리밍을 전달해야 하니까요. 이 때 쓰는 게 SSE, 즉 Server-Sent Events입니다. 서버가 클라이언트한테 단방향으로 이벤트를 밀어주는 HTTP 기반 방식이에요.

FastAPI로 구현하면 이런 형태가 됩니다.

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import anthropic

app = FastAPI()
client = anthropic.Anthropic()

async def generate_stream(prompt: str):
    with client.messages.stream(
        model="claude-opus-4-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "prompt"}]
    ) as stream:
        for text in stream.text_stream:
            yield f"data: {text}\n\n"

@app.get("/chat")
async def chat(q: str):
    return StreamingResponse(
        generate_stream(q),
        media_type="text/event-stream"
    )

media_type="text/event-stream"이 SSE를 활성화하는 부분입니다. data: {내용}\n\n 형식은 SSE 프로토콜 규격이에요. 이 포맷 안 지키면 프론트엔드에서 파싱이 안 됩니다. \n\n 두 개가 이벤트 하나의 끝을 나타내는 거거든요.