GPT-6 Astra 스트리밍 가이드: 응답 API 이벤트, 도구 및 오류 처리

스트리밍은 GPT-6 Astra가 작업 중인 동안 이벤트를 전달하여 인지된 지연 시간을 개선합니다. 이는 기본 계산을 무료로 만들거나 실패 사례를 제거하지 않습니다. 프로덕션 클라이언트는 증분 출력을 조합하고, 도구 진행 상황을 렌더링하며, 종료 상태를 구분하고, 연결이 실패할 때 복구해야 합니다.

타입 이벤트로 시작하기

stream: true로 설정하고 SDK의 타입이 지정된 이벤트 스트림을 반복합니다.

const stream = await client.responses.create({ model: "gpt-6-astra", input: "마이그레이션 계획을 다섯 단계로 설명해 주세요.", stream: true });

for await (const event of stream) { switch (event.type) { .output_text.delta process.stdout.write(event.delta); break; ."response.completed" console.log("\n완료"); break; .case "response.failed": console.error("실패", event.response.error); break; case "error": console.error(event.message); break; } }

일반적인 텍스트 생명주기 이벤트에는 `response.created`, `response.output_text.delta`, `response.completed`, `error`가 포함됩니다. 전체 이벤트 유니온에는 출력 항목, 콘텐츠 부분, 주석, 거부, 실패 및 기타 이벤트도 포함됩니다. 새로 추가된 이벤트가 이전 클라이언트를 충돌시키지 않도록 알 수 없는 이벤트 유형을 안전하게 처리하세요.

## 어셈블러를 구축하세요, 텍스트 추가 루프가 아닌

응답은 여러 출력 항목과 콘텐츠 부분을 포함할 수 있습니다. 모든 델타를 하나의 전역 문자열에 추가하는 대신 응답, 출력 항목, 콘텐츠 부분별로 상태를 인덱싱합니다. 사용 가능한 문서화된 식별자나 시퀀스 데이터를 사용하여 중복을 제거하고, 커밋된 로컬 상태만 렌더링합니다.

주석과 인용은 텍스트와 별도로 도착할 수 있습니다. 연결 중에 제거하지 않고 오프셋이나 연관성을 유지하십시오. 최종 응답 객체가 가능할 때는 이를 권위 있는 것으로 취급하십시오.

## 터미널 상태는 상호 교환할 수 없습니다

.completed는 성공적인 완료를 의미합니다. response.failed는 실패를 나타냅니다. response.incomplete는 토큰 제한이나 다른 이유를 반영할 수 있으며 유용한 부분 출력을 포함할 수 있습니다. 전송 수준의 error는 정상적인 응답 종료 이벤트 없이 발생할 수 있습니다.

소켓이 닫혔다고 해서 요청을 성공으로 표시하지 마세요. `response.created`가 도착하는 즉시 응답 ID를 저장하고, 종료 상태는 별도로 저장하세요.

## 스트리밍 도구 활동을 정직하게

도구 호출은 단계를 도입합니다: 모델 계획, 인수 생성, 서버 또는 클라이언트 실행, 도구 결과 및 재개된 생성. UI는 해당 이벤트/상태가 존재하는 경우에만 "검색 중" 또는 "승인 대기 중"이라고 표시해야 합니다. 진행률 백분율을 임의로 만들어서는 안 됩니다.

클라이언트에서 실행되는 함수의 경우, API 계약이 명시적으로 증분 처리를 지원하지 않는 한 구문 분석 전에 완전한 인수를 조립하십시오. 이를 검증하고 한 번 실행한 후 호출 ID를 사용하여 결과를 반환하십시오. 중복 이벤트를 스트리밍할 때 중복 부작용이 발생해서는 안 됩니다.

## 백프레셔와 UI 성능

토큰 크기의 델타는 브라우저가 렌더링해야 하는 속도보다 빠르게 도착할 수 있습니다. 잠시 버퍼링하고 제어된 속도로 UI를 업데이트하세요. 이렇게 하면 인지된 지연 시간에 실질적인 손해를 끼치지 않으면서 레이아웃 작업을 줄일 수 있습니다. 프레임워크가 지원하는 경우 메모리 내 버퍼를 제한하고 다운스트림 처리를 일시 중지하세요.

원시 이벤트 로그를 뷰 모델과 분리하세요. 이벤트 로그는 디버깅을 지원하고, 뷰 모델은 델타를 결합하여 안정적인 사용자 표시 콘텐츠를 만듭니다. 로깅 전에 민감한 도구 페이로드를 편집하세요.

## 연결 끊김, 시간 초과 및 취소

연결이 끊어지면 상태를 복구할 때까지 작업을 알 수 없음으로 분류하세요. 모델 응답이 서버 측에서 계속되었을 수 있으며, 외부 도구가 이미 작업을 수행했을 수 있습니다. 쓰기를 자동으로 재실행하지 마십시오.

요청 마감 시간과 유휴 스트림 타이머를 사용하되, "텍스트 델타 없음"과 "활동 없음"을 구분하세요. 장기 도구 호출은 여전히 정상일 수 있습니다. 취소는 자체 취소 가능한 도구로 전파되어야 합니다. 완료된 효과의 롤백은 보장할 수 없습니다.

응답 상태를 계속 진행하는 경우, 마지막으로 커밋된 응답과 도구 결과를 유지하세요. WebSocket 특화 복구 시 `previous_response_not_found`가 보고될 수 있습니다. 공식 오류 가이드에서는 상태를 해결할 수 없을 때 전체 입력 컨텍스트와 `previous_response_id: null`로 재시도할 것을 권장합니다.

## 관찰 가능성

.created까지의 기록 시간, 첫 번째 텍스트 델타, 첫 번째 도구 이벤트, 터미널 이벤트; 총 지속 시간; 이벤트 수; 터미널 상태; 연결 끊김; 재시도; 사용자 취소. 모든 이벤트를 하나의 애플리케이션 요청 ID와 OpenAI 응답 ID와 연관시키세요.

잘못된 주문, 중복 배송, 알 수 없는 이벤트, 도구 시간 초과, 표시 텍스트 이후의 지연 실패, 쓰기 후 연결 끊김을 테스트합니다. 스트리밍 정확성은 상태 머신 정확성입니다.

## 브라우저 및 서버 구현 패턴

많은 제품에서 애플리케이션 서버가 OpenAI 연결을 유지하고 정제된 이벤트 스트림을 브라우저로 중계해야 합니다. 이렇게 하면 API 자격 증명이 클라이언트에 노출되지 않고, 인증이 중앙화되며, 서버가 내부 도구 인수를 숨길 수 있습니다. 브라우저는 렌더링에 필요한 이벤트(상태, 안전한 텍스트 델타, 인용, 승인 프롬프트, 최종 결과)만 수신합니다.

모든 문자 대신 대략적인 체크포인트를 유지하세요. 모든 델타를 저장하면 과도한 쓰기가 발생하고, 완료 시에만 저장하면 연결 끊김 시 너무 많은 데이터가 손실됩니다. 짧은 간격이나 콘텐츠 부분 경계가 일반적으로 더 나은 절충안입니다. 재연결 시 가장 최근에 커밋된 뷰를 전송하고, 전송 설계에 따라 다음으로 알려진 이벤트부터 계속 진행하세요.

중재와 안전을 위해서는 스트리밍 정책이 필요합니다. 최종 응답이 완성되기 전에 부분 텍스트가 사용자에게 도달하므로, 완료 시에만 실행되는 다운스트림 검토는 너무 늦을 수 있습니다. 위험에 따라 사전 생성 제어, 점진적 안전 장치, 버퍼링 또는 제한된 스트리밍을 선택하십시오. 고위험 워크플로우는 의도적으로 즉시성의 일부를 검토와 맞바꿀 수 있습니다.

마지막으로, 브라우저 새로고침 후 재개된 응답이 분석에서 이중으로 계산되지 않도록 하세요. OpenAI 응답 ID와 안정적인 애플리케이션 요청 ID가 모든 세그먼트를 하나의 논리적 작업으로 연결해야 합니다.

## 자주 묻는 질문

### 스트리밍이 토큰 비용을 절감하나요?

아니요. 전달 방식을 바꿀 뿐, 생성되는 토큰 수는 바뀌지 않습니다.

### 부분 출력을 즉시 보여줄 수 있나요?

네, 진행 중으로 표시하되 거절, 불완전 또는 실패 결과에 대비하세요.

### 연결이 종료되었을 때 재시도해야 하나요?

특히 도구가 부작용을 일으킬 수 있는 경우 먼저 복구하거나 조정하세요. 무작정 재실행하면 작업이 중복될 수 있습니다.

### SSE와 WebSocket 이벤트 처리는 동일한가요?

응답 개념은 공유하지만 전송 및 연속 동작은 다릅니다. 선택한 모드에 대한 가이드를 따르세요.

## 결론

신뢰할 수 있는 GPT-6 Astra 스트리밍을 위해서는 타입 기반 이벤트 처리, 구조화된 어셈블러, 명시적인 종료 상태, 멱등성 있는 도구 실행, 역압력, 복구가 필요합니다. 사용자의 진행 상황 인식을 최적화하되, 부분 텍스트나 닫힌 연결을 잘못된 성공으로 전환하지 않도록 해야 합니다.