AI API 스트리밍: SSE와 타임아웃

AI API 스트리밍은 전체 응답을 기다리지 않고 모델이 생성하는 동안 이벤트를 전달합니다. 체감 반응성은 좋아지지만 모델 지연이 반드시 줄지는 않으며, 클라이언트는 선택한 엔드포인트의 프로토콜을 정확히 파싱해야 합니다.

Chat Completions는 completion chunk를, Responses는 타입이 있는 response event를 보냅니다. 잘못된 형식을 기대하면 HTTP 200을 받아도 화면에 아무것도 표시되지 않을 수 있습니다.

버퍼링 없이 시작하기

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.","stream":true}'

같은 요청을 스트리밍 없이 먼저 시험하면 요청 검증과 스트림 파싱 문제를 분리할 수 있습니다. 모델 및 가격의 실제 ID를 사용하세요.

SSE를 프로토콜로 다루기

Server-Sent Events는 경계가 있는 레코드이지 임의의 JSON 조각이 아닙니다. 클라이언트는 HTTP, 프록시, UI의 버퍼링을 막고, 부분 읽기를 완전한 이벤트까지 모으며, 텍스트, 추론, 도구, 완료, 오류 이벤트를 처리해야 합니다. 취소와 최종 사용량을 보존하고 종료 이벤트 뒤에는 연결을 닫습니다.

지연을 단계별로 측정하기

지표	의미
연결 및 인증	게이트웨이 도달과 키 검증
Upstream Header	선택 경로가 응답을 시작한 시점
첫 유효 출력	첫 유용한 텍스트, 추론 또는 도구 이벤트
첫 가시 텍스트	사용자가 실제로 보는 첫 문자열
전체 응답 시간	완료, 실패 또는 취소까지

도구 호출은 보이는 텍스트보다 먼저 유효한 출력이 될 수 있습니다. 운영에는 첫 유효 출력, UX에는 첫 가시 텍스트도 함께 측정합니다.

단계별 타임아웃 설계

연결, 헤더 또는 첫 출력, 스트림 유휴, 전체 deadline을 구분합니다. 추론이나 도구 요청은 가시 텍스트까지 더 오래 걸릴 수 있으므로 짧은 전역 타임아웃 하나 대신 실제 워크로드 자료로 설정합니다.

클라이언트, 브라우저 또는 프록시가 먼저 닫히면 Modelflare는 499를 기록할 수 있습니다. 이는 downstream 취소 증거이지 모델이나 채널 장애의 단독 증거가 아닙니다. Abort, 프록시 타임아웃, 첫 출력, 모델, 그룹, 취소 시각을 비교하세요.

텍스트가 보이지 않을 때

1. "stream": false로 같은 요청을 반복합니다.
2. 모델이 엔드포인트를 지원하는지 확인합니다.
3. UI 변환 전 원시 이벤트를 캡처합니다.
4. 텍스트 없는 도구나 추론 이벤트를 찾습니다.
5. 중간 버퍼링을 배제합니다.
6. 파서의 종료 이벤트 처리를 확인합니다.
7. 상태, 시간, 취소 기록을 비교합니다.

비스트리밍이 되고 원시 이벤트도 오면 파싱이나 렌더링 문제일 가능성이 큽니다. 이벤트가 없다면 AI API 오류 가이드를 보세요. 형식 선택은 Responses API와 Chat Completions을 참고하세요.