# 스트리밍 오류

스트리밍 오류란 LLM(대규모 언어 모델) 서비스에서 응답을 생성하여 클라이언트로 전송하는 과정에서, 서버와 클라이언트 간의 HTTP 지속 연결(Persistent Connection)이 예기치 않게 끊어지거나 토큰 생성 중 타임아웃이 발생하여 응답을 정상적으로 수신하지 못하는 현상을 의미합니다.

## 발생 원인

스트리밍 오류는 주로 다음과 같은 기술적 요인으로 인해 발생합니다.

- **네트워크 불안정**: 클라이언트와 서버 간의 네트워크 연결이 일시적으로 단절되거나 패킷 손실이 발생하는 경우
- **서버 측 타임아웃**: 모델의 추론 시간이 길어져 서버 설정에 정의된 응답 대기 시간(Timeout)을 초과한 경우
- **API 제한**: API 할당량(Quota)을 모두 소모했거나, 짧은 시간 내에 너무 많은 요청을 보내 속도 제한(Rate Limit)에 걸린 경우
- **클라이언트 로직 오류**: 서버에서 보내는 스트리밍 데이터(Server-Sent Events 등)를 처리하는 클라이언트 측의 파싱 로직에 결함이 있는 경우

## 해결 방법

### 사용자 대응 방안
일반 사용자는 다음의 단계를 통해 문제를 해결할 수 있습니다.
- **페이지 새로고침**: 브라우저를 새로고침하여 세션을 초기화합니다.
- **네트워크 상태 확인**: Wi-Fi 또는 데이터 연결 상태가 안정적인지 확인합니다.
- **재시도**: '재생성' 또는 '다시 시도' 버튼을 클릭하여 요청을 다시 보냅니다.

### 개발자 대응 방안
서비스 개발자는 시스템 안정성을 위해 다음과 같은 조치를 취해야 합니다.
- **연결 설정 최적화**: HTTP `keep-alive` 설정을 확인하여 연결 유지 시간을 적절히 조정합니다.
- **타임아웃 값 조정**: 모델의 최대 출력 길이를 고려하여 서버 및 게이트웨이의 타임아웃 설정을 늘립니다.
- **에러 핸들링 구현**: 지수 백오프(Exponential Backoff) 알고리즘을 적용한 재시도 로직(Retry logic)을 구현합니다.

## 참고 사항

### 주요 에러 코드
스트리밍 중 발생하는 대표적인 HTTP 상태 코드는 다음과 같습니다.

| 에러 코드 | 명칭 | 의미 및 원인 |
| :--- | :--- | :--- |
| `429` | Too Many Requests | API 요청 속도 제한 초과 |
| `500` | Internal Server Error | 서버 내부의 예상치 못한 오류 발생 |
| `502` | Bad Gateway | 게이트웨이 또는 프록시 서버의 응답 오류 |
| `504` | Gateway Timeout | 서버 응답 시간이 초과되어 연결 종료 |

### API 호출 예시
스트리밍 연결을 위한 기본적인 API 호출 구조는 다음과 같습니다.

```javascript
const response = await fetch('https://api.llm-service.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    model: 'llm-model-name',
    messages: [{ role: 'user', content: '안녕하세요!' }],
    stream: true // 스트리밍 활성화
  })
});

// ReadableStream을 통한 데이터 처리
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}
```