AI API 스트리밍 가이드: SSE, 첫 출력, 타임아웃
올바른 Chat·Responses 이벤트 처리, SSE 파싱, 첫 유효 출력 지표, 단계별 타임아웃, 499 진단으로 안정적인 AI API 스트리밍을 구현합니다.

AI API 스트리밍은 전체 응답 본문이 완성될 때까지 기다리지 않고, 모델이 생성하는 동안 출력을 조금씩 보내는 방식입니다. 체감 응답성은 좋아질 수 있지만 모델 지연 시간이 자동으로 줄어드는 것은 아니며, 클라이언트가 올바르게 파싱해야 하는 프로토콜 계약이 하나 더 생깁니다.
첫 번째 원칙은 파서를 엔드포인트에 맞추는 것입니다. Chat Completions는 스트리밍 완성 청크를 사용하고, Responses는 타입이 지정된 응답 이벤트를 사용합니다. 클라이언트가 잘못된 이벤트 형식을 기대하면 HTTP 200을 받고도 아무것도 렌더링하지 못할 수 있습니다.
버퍼링하지 않는 요청으로 시작하기
Chat Completions 모델에서는 curl -N으로 curl의 출력 버퍼링을 끌 수 있습니다.
curl -N -sS https://modelflare.dev/v1/chat/completions \
-H "Authorization: Bearer $MODELFLARE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_CHAT_MODEL",
"messages": [{"role": "user", "content": "Explain SSE in three points."}],
"stream": true
}'
Responses 호환 모델에서는 다음과 같이 요청합니다.
curl -N -sS https://modelflare.dev/v1/responses \
-H "Authorization: Bearer $MODELFLARE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_RESPONSES_MODEL",
"input": "Explain SSE in three points.",
"stream": true
}'
모델 및 요금에 표시된 정확한 모델 ID를 사용하세요. 먼저 스트리밍을 끈 상태로 같은 요청을 한 번 테스트하면 요청 자체의 유효성 문제와 스트림 파싱 문제를 분리할 수 있습니다.
이벤트 스트림을 프로토콜로 다루기
Server-Sent Events는 임의의 JSON 조각이 아니라 프레임 단위로 구분된 레코드입니다. 프로덕션 클라이언트는 다음을 처리해야 합니다.
- HTTP 라이브러리, 프록시, UI 계층 전체에서 응답 본문을 버퍼링하지 않습니다.
- 완전한 이벤트가 만들어질 때까지 부분적으로 읽힌 네트워크 데이터를 누적합니다.
- 선택한 엔드포인트가 사용하는 이벤트 유형을 파싱합니다.
- 텍스트 델타, 추론 또는 도구 이벤트, 완료 이벤트, 오류 이벤트를 처리합니다.
- 유용한 응답에 항상 화면에 보이는 텍스트가 있다고 가정하지 않습니다.
- 취소 정보와 최종 사용량 정보를 보존합니다.
- 종료 이벤트를 받으면 무한정 기다리지 말고 스트림을 닫습니다.
가능하면 선택한 프로토콜을 기본으로 지원하는 SDK를 사용하세요. 직접 만든 파서는 조각난 프레임, 한 번의 읽기에 함께 들어온 여러 이벤트, 도구 전용 출력, 정상적인 종료 이벤트로 테스트해야 합니다.
첫 토큰까지의 시간만 측정하지 않기
‘첫 토큰까지의 시간’은 에이전트 트래픽에서는 너무 모호한 경우가 많습니다. 다음 측정값을 나눠서 보세요.
| 측정 항목 | 의미 |
|---|---|
| 연결 및 인증 | 게이트웨이에 도달하고 키를 검증하기까지의 시간 |
| 공급사 응답 헤더 | 선택된 경로가 응답을 시작하기까지의 시간 |
| 첫 유효 출력 | 첫 번째로 유용한 텍스트, 추론 또는 도구 이벤트 |
| 첫 표시 텍스트 | 사용자가 실제로 볼 수 있는 첫 텍스트 |
| 출력 처리량 | 출력이 시작된 뒤 화면에 표시되는 생성 속도 |
| 전체 응답 시간 | 완료, 실패 또는 취소될 때까지의 시간 |
도구 호출은 화면에 보이는 텍스트보다 먼저 유효 출력을 만들 수 있습니다. 그래서 운영 지표로는 첫 유효 출력이 더 안전하고, 첫 표시 텍스트는 사용자 경험을 볼 때 유용합니다.
Modelflare 사용 로그는 요청 단위의 시간 근거를 보관하므로 이러한 단계를 모델, 그룹, 상태, 토큰, 비용과 함께 비교할 수 있습니다.
단계별로 타임아웃 설계하기
짧은 전역 타임아웃 하나만 두면 원인을 알기 어려운 실패가 생깁니다. 스트리밍 클라이언트는 여러 시간 예산을 나눠서 고려해야 합니다.
- 연결 타임아웃: HTTP 연결을 수립하지 못한 경우입니다.
- 헤더 또는 첫 출력 타임아웃: 요청이 수락된 뒤 응답이나 유효 이벤트가 오지 않는 경우입니다.
- 유휴 타임아웃: 스트림은 시작되었지만 예상보다 오랫동안 새 이벤트가 도착하지 않는 경우입니다.
- 전체 기한: 작업 전체가 워크로드의 비즈니스 한도를 초과한 경우입니다.
추론 비중이 높거나 도구를 많이 쓰는 요청은 짧은 채팅 완성보다 화면에 텍스트가 나타나기까지 정상적으로 더 오래 기다릴 수 있습니다. 실제 워크로드에서 관측한 동작을 바탕으로 시간 예산을 정하고, 사용자에게 더 이상 결과가 필요하지 않을 때는 의도적으로 취소하세요.
취소와 499 기록 이해하기
클라이언트, 리버스 프록시, 브라우저 탭 또는 호출자 기한 때문에 다운스트림 연결이 닫히면 게이트웨이는 해당 요청을 클라이언트 취소로 기록할 수 있습니다. 요청 기록의 499 라벨은 완료 전에 다운스트림 연결이 끝났다는 근거일 뿐, 그것만으로 선택된 모델이나 채널이 실패했다는 증거는 아닙니다.
취소 원인을 조사할 때는 다음을 비교하세요.
- 클라이언트 기한과 중단(abort) 신호
- 프록시 버퍼링과 유휴 타임아웃
- 첫 유효 출력까지의 시간
- 클라이언트에 도달한 이벤트가 있었는지 여부
- 선택된 모델과 그룹
- 요청 ID와 취소 시각
화면에 텍스트가 표시되지 않는 스트림 진단하기
다음 순서로 확인하세요.
- "stream": false로 같은 요청을 다시 보냅니다.
- 모델이 선택한 엔드포인트를 지원하는지 확인합니다.
- UI가 변환하기 전에 원본 이벤트를 캡처합니다.
- 응답에 텍스트 대신 도구 호출이나 추론 이벤트가 포함되어 있는지 확인합니다.
- 중간 계층이 본문을 버퍼링하고 있지 않은지 확인합니다.
- 파서가 해당 엔드포인트의 종료 이벤트를 처리하는지 확인합니다.
- 사용 로그에서 상태, 첫 출력, 전체 시간, 취소 여부를 검토합니다.
비스트리밍 요청이 성공하고 원본 스트리밍 이벤트도 도착한다면, 문제는 대개 인증이나 모델 액세스가 아니라 클라이언트의 파싱이나 렌더링에 있습니다. 원본 이벤트가 하나도 도착하지 않는다면 AI API 오류 가이드로 진단을 이어 가세요.
프로덕션 스트리밍 체크리스트
- 파서를 Chat Completions 또는 Responses에 명시적으로 맞춥니다.
- HTTP 클라이언트와 직접 관리하는 모든 프록시 계층에서 버퍼링을 끕니다.
- 애플리케이션이 사용하는 텍스트, 추론, 도구 전용, 오류 이벤트를 테스트합니다.
- 첫 유효 출력과 첫 표시 텍스트를 구분합니다.
- 단계에 맞는 타임아웃과 의도적인 중단 신호를 사용합니다.
- 작업에 안전한 멱등성 설계가 없다면 재시도를 새 요청으로 취급합니다.
- 진단을 위해 요청 ID, 상태, 선택된 모델, 그룹, 시간 정보를 보존합니다.
- 엔드포인트 선택은 Responses API와 Chat Completions 비교에서 다시 검토합니다.
자주 묻는 질문
스트리밍을 사용하면 모델이 더 빨리 생성합니까?
반드시 그렇지는 않습니다. 스트리밍은 출력을 더 일찍 보여 줄 뿐이며, 생성 속도와 첫 이벤트까지의 시간은 여전히 모델, 경로, 컨텍스트, 추론, 도구에 따라 달라집니다.
curl에서는 동작하는데 애플리케이션에는 아무것도 표시되지 않는 이유는 무엇입니까?
애플리케이션이나 중간 계층이 본문을 버퍼링하고 있거나, 파서가 Responses 이벤트를 받으면서 Chat Completions 청크를 기대하고 있을 수 있습니다. 모델이나 경로를 바꾸기 전에 애플리케이션 경계에서 원본 프레임을 캡처하세요.
스트림 연결이 끊기면 클라이언트가 재시도해야 합니까?
작업을 반복해도 안전한 경우에만 재시도하세요. 연결이 끊긴 스트림이라도 이미 공급사 쪽 작업이나 도구 실행이 일어났을 수 있습니다. 중복된 부작용이 문제가 된다면 횟수를 제한한 재시도와 애플리케이션 수준의 멱등성을 사용하세요.