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을 참고하세요.

두 엔드포인트를 버퍼링 없이 비교하기

앞의 Responses 예제와 함께 Chat Completions도 고유 형식으로 테스트합니다.

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": "SSE를 세 가지로 설명해 주세요."}],
    "stream": true
  }'

파서는 다음을 처리해야 합니다.

• HTTP 라이브러리, 프록시, 화면에서 응답을 버퍼링하지 않기.
• 부분 읽기를 완전한 이벤트가 될 때까지 합치기.
• 선택한 엔드포인트의 이벤트 유형을 해석하기.
• 텍스트, 추론, 도구, 완료, 오류를 구분하기.
• 가시 텍스트가 없어도 유효한 응답을 처리하기.
• 취소 상태와 최종 사용량을 보존하기.
• 종료 이벤트 뒤에 스트림을 닫기.

운영 스트리밍 점검 목록

• 파서를 Chat Completions 또는 Responses 중 하나에 명시적으로 맞춥니다.
• 텍스트, 추론, 도구 전용, 오류, 정상 종료 이벤트를 테스트합니다.
• 첫 이벤트, 첫 유효 출력, 첫 가시 텍스트를 따로 측정합니다.
• 연결, 첫 출력, 유휴, 전체 작업에 별도 시간 제한을 둡니다.
• 의도가 분명한 취소 신호를 사용합니다.
• 안전한 멱등성이 없으면 재시도를 새 요청으로 취급합니다.
• 진단을 위해 ID, 상태, 모델, 그룹, 시간을 보존합니다.
• 어떤 중간 계층도 스트림을 다시 버퍼링하지 않는지 확인합니다.

자주 묻는 질문

스트리밍이 모델 생성 자체를 빠르게 합니까?

반드시 그렇지는 않습니다. 출력을 더 일찍 보여 줄 뿐이며, 첫 이벤트까지의 시간과 이후 속도는 모델, 경로, 문맥, 추론, 도구에 좌우됩니다.

curl은 되는데 애플리케이션에 아무것도 안 보이는 이유는 무엇입니까?

애플리케이션이나 중간 계층이 응답을 버퍼링하거나, Chat Completions 파서가 Responses 이벤트를 읽고 있을 수 있습니다. 모델을 바꾸기 전에 원시 이벤트를 캡처하십시오.

중단된 스트림을 재시도해야 합니까?

작업을 안전하게 반복할 수 있을 때만 해야 합니다. 상위 작업이나 도구가 이미 실행됐을 수 있으므로 횟수를 제한하고 부수 효과가 있으면 멱등성을 요구하십시오.