OpenAI Responses 스트리밍 실무 가이드: 토큰과 이벤트를 안정적으로 다루는 법

OpenAI Responses의 스트리밍은 응답을 한 번에 받지 않고, 생성 중인 결과를 조금씩 소비하는 방식입니다. 채팅 UI, 긴 생성 작업, 도구 호출 중간 상태 표시처럼 사용자에게 즉시 반응을 보여줘야 하는 화면에서 특히 유용합니다.

이 글은 스트리밍을 왜 쓰는지, 이벤트를 어떻게 해석하는지, 실무에서 어디에 붙여야 하는지를 중심으로 설명합니다.

이런 때 유용합니다

#

• 답변이 길어 사용자 대기 시간이 체감될 때
• 생성 중간에 진행 상태를 보여주고 싶을 때
• 도구 호출과 모델 출력을 한 화면에서 함께 보여줘야 할 때
• 음성, 에이전트, 실시간 보조 UI처럼 즉시 반응이 중요한 경우

스트리밍의 핵심

#

스트리밍의 목적은 단순히 “빠르게 보이게 하는 것"이 아닙니다. 모델이 어떤 단계에 있는지 클라이언트가 알 수 있게 만드는 데 있습니다. 실무에서는 다음 세 가지를 분리해서 봐야 합니다.

• 텍스트 델타
• 도구 호출 상태
• 최종 완료 이벤트

이 구분이 되면 UI도 명확해집니다. 텍스트는 바로 렌더링하고, 도구 호출은 상태로 표시하고, 완료 이벤트가 오면 결과를 확정하면 됩니다.

장점과 한계

#

장점은 체감 속도입니다. 사용자 입장에서는 첫 토큰이 빨리 보이면 응답 품질이 더 좋게 느껴집니다. 또 긴 작업의 중간 상태를 드러낼 수 있어, “멈췄다"는 인상을 줄일 수 있습니다.

한계는 상태 관리입니다. 스트리밍 이벤트를 제대로 합치지 못하면 UI가 중복되거나 깨질 수 있습니다. 특히 도구 호출이 섞이면 일반 텍스트 스트리밍보다 처리 로직이 복잡해집니다.

빠른 시작

#

기본 흐름은 단순합니다.

1. Responses API 요청을 보냅니다.
2. 스트리밍 이벤트를 수신합니다.
3. 텍스트 델타를 누적합니다.
4. 완료 시 최종 상태를 반영합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

from openai import OpenAI

client = OpenAI()

stream = client.responses.stream(
    model="gpt-4.1",
    input="이 문단을 3줄로 요약해줘",
)

for event in stream:
    print(event)

실제 앱에서는 이벤트 타입별로 분기해서 UI 상태를 갱신하는 구조가 필요합니다.

실전 체크리스트

#

• 텍스트 델타와 최종 결과를 분리했는가
• 도구 호출 중간 상태를 사용자에게 보여주는가
• 연결 끊김 시 재시도 전략이 있는가
• 이벤트를 누적할 때 중복 렌더링이 없는가
• 스트리밍이 꼭 필요한 화면에만 적용했는가

함께 읽으면 좋은 글

#

• OpenAI Responses API 실무 가이드
• OpenAI Web Search 실무 가이드
• OpenAI File Search 실무 가이드
• OpenAI Realtime API 실무 가이드

결론

#

Responses 스트리밍은 실시간 UX를 만드는 가장 기본적인 수단입니다. 답변이 길거나 도구 호출이 섞인 앱이라면, 스트리밍을 먼저 설계한 뒤 모델 호출을 붙이는 편이 좋습니다.