스트리밍 응답 계약 Streaming Response Contract
스트리밍 응답 계약은 LLM 서비스의 클라이언트·게이트웨이·공급자 간 API 계약 계층에서 입력·판단·관측·복구 조건을 일관된 형식으로 관리하기 위한 운영 설계 개념이다.
개념과 원리
섹션 제목: “개념과 원리”개요와 적용 범위
섹션 제목: “개요와 적용 범위”스트리밍 응답 계약은 LLM 서비스의 클라이언트·게이트웨이·공급자 간 API 계약 계층에서 특정한 판단과 통제를 분리해 설명하기 위한 운영 설계 개념이다. 스트리밍 응답 계약의 정의, 구성 요소, 의사결정 기준, 실패 모드와 운영 검증 범위를 다룬다.
이 개념의 목적은 기술 이름을 하나 더 만드는 데 있지 않다. 실제 시스템에서 어떤 입력과 상태를 관측하고, 어떤 기준으로 변경을 허용하며, 실패했을 때 어떤 경로로 복구할지를 하나의 문서화된 판단 단위로 묶는 것이 핵심이다. 적용 범위는 워크로드, 사용자 위험, 비용 제약을 명시한 경우로 한정한다.
용어의 위치와 경계
섹션 제목: “용어의 위치와 경계”스트리밍 응답 계약은 단일 표준이 정의한 고유명사로 단정하지 않는다. 이 문서에서는 인접한 연구·표준·구현 관행을 연결해 프로덕션 의사결정을 설명하는 조합적 운영 개념으로 사용한다. 따라서 제품명이나 특정 공급자의 기능과 동의어가 아니다.
특정 공급자의 현재 제품 매뉴얼만을 요약하거나 검증하지 않은 성능 수치를 일반화하지 않는다. 구현이 다르더라도 입력, 판단 규칙, 관측 결과, 복구 조건을 같은 형식으로 나란히 놓으면 비교가 가능하다. 용어를 사용할 때는 팀 내부의 적용 범위와 버전을 함께 밝혀 의미가 조직마다 달라지는 문제를 줄인다.
작동 구조
섹션 제목: “작동 구조”스트리밍 응답 계약은 델타의 주소, 누적 규칙, 항목 완료와 전체 응답 종료를 구분하는 상태 전이 규칙이다. OpenAI Responses의 이벤트에서는 type과 sequence_number를 읽고 item_id·output_index·content_index에 따라 대상 항목에 델타를 합친다. 텍스트 조각, 도구 인수 조각, 추론 관련 항목을 하나의 문자열로 섞지 않는다. 항목이 추가된 시점의 불완전 값만 저장하지 말고 완료 이벤트의 최종 값을 반영한다.
텍스트나 도구 인수의 done 이벤트는 그 항목의 완료를 뜻하며 전체 응답 성공과 같지 않다. response.completed, response.failed, response.incomplete를 별도로 처리하고, 연결 종료만 발생했다면 최종 상태가 불명확하다고 기록한다. 애플리케이션은 도구 인수의 파싱·검증과 실행 권한 확인이 끝나기 전에 부분 JSON으로 외부 행동을 실행하지 않으며, UI에 표시한 부분 텍스트와 확정 결과도 구별한다.
구성 요소와 정보 흐름
섹션 제목: “구성 요소와 정보 흐름”스트리밍 응답 계약은 입력 계약, 정책 저장소, 실행기, 관측 파이프라인, 복구 제어기로 구성할 수 있다. 입력 계약은 필수 필드와 유효 범위를 고정하고, 정책 저장소는 조건과 우선순위를 버전별로 보관한다. 실행기는 정책을 결과로 변환하며 관측 파이프라인은 실제 결과를 지표와 이벤트로 전환한다.
정보 흐름은 양방향이어야 한다. 제어 계층이 실행 계층에 정책을 내리는 것만으로는 부족하며, 관측 결과가 정책 수정과 자동 중단으로 되돌아와야 한다. 최종 복구 제어기는 롤백, 대체 경로, 사람 승인 중 하나를 선택하고 선택 이유를 남긴다.
활용과 검증
섹션 제목: “활용과 검증”측정 지표와 판단 기준
섹션 제목: “측정 지표와 판단 기준”스트리밍 응답 계약을 평가할 때는 요청 성공률, 오류 유형별 빈도, 말단 지연 시간, 재시도 증폭률, 하위 호환성 테스트 통과율을 함께 본다. 평균값 하나로 결론을 내리지 않고 워크로드, 사용자 군, 요청 크기, 모델 버전 슬라이스로 나눈다. 기준선은 목표, 경고, 중단의 세 단계로 나누고 각 단계의 대응 행동을 미리 결정한다.
측정값에는 표본 수와 관측 기간, 분모의 정의를 함께 기록한다. 지표가 좋아져도 다른 지표의 악화를 감출 수 있으므로 품질, 비용, 지연, 안전성을 같은 릴리스 표에서 비교한다. 최소 표본에 도달하지 못한 결과는 확정 판정이 아니라 보류로 분류한다.
설계 선택과 트레이드오프
섹션 제목: “설계 선택과 트레이드오프”스트리밍 응답 계약은 품질·지연·비용·안전성 사이의 교환 관계를 드러낸다. 더 강한 검증과 이중화는 실패를 줄이지만 지연과 비용을 늘릴 수 있다. 반대로 빠른 대체 경로는 가용성을 높이지만 품질 일관성과 추적성을 떨어뜨릴 수 있다.
따라서 전체 요청에 하나의 정책을 적용하지 않는다. 사용자 영향, 요청 가치, 실패 후 복구 가능성에 따라 보수적·표준·속도 우선 정책으로 분리한다. 각 정책은 적용 조건, 예산, 허용 오류, 롤백 조건을 포함하고 운영 데이터로 주기적으로 재조정한다.
실패 모드와 진단
섹션 제목: “실패 모드와 진단”스트리밍 응답 계약에서 우선 검토할 실패 후보는 스키마 드리프트, 중복 요청, 재시도 폭주, 부분 실패, 비밀 키 노출이다. 실패 항목은 증상, 추정 원인, 탐지 신호, 사용자 영향, 임시 조치, 근본 조치로 나눠 기록한다. 이 구조를 사용하면 같은 증상을 만드는 서로 다른 원인을 구분할 수 있다.
진단은 최종 출력에서 역순으로 진행한다. 결과 검증, 실행 기록, 정책 선택, 입력 정규화 순으로 경계를 확인하면 변수를 빠르게 줄일 수 있다. 재현이 어려운 경우에는 실제 민감 데이터를 제거한 최소 재현 입력과 정책 버전을 함께 보존한다.
SSE의 연결 재개와 모델 작업의 재실행은 같은 동작이 아니다. EventSource의 Last-Event-ID는 서버가 해당 이벤트의 보관·재생 계약을 구현했을 때만 유효한 복구 단서다. 단순 HTTP 스트림이나 공급자 SDK가 같은 재개 기능을 제공한다고 가정하지 않는다. 중복 이벤트 제거, 최종 완료 확인과 결과가 불명확한 외부 작업의 상태 조회를 별도로 구현한다.
운영·관측·복구
섹션 제목: “운영·관측·복구”스트리밍 응답 계약을 변경할 때는 버전, 적용 대상, 관측 지표, 예상 영향, 롤백 조건을 하나의 변경 기록에 남긴다. 배포는 오프라인 재현, 쉐도 실행, 소규모 카나리, 단계적 확대 순으로 진행하고 각 단계에서 중단 기준을 자동 판정할 수 있게 한다.
관측 화면은 성공 지표만 보여주지 않고 거부, 대체 경로, 재시도, 사람 개입, 복구 소요 시간을 함께 보여준다. 복구 절차는 담당자와 권한, 예상 소요 시간, 데이터 영향, 복구 후 검증 항목을 포함해야 한다. 주기적 후속 검토로 임시 조치가 영구 정책으로 남는 것을 방지한다.
공급자 교체 시험에는 텍스트 없이 도구 호출만 나온 응답, 인수 델타 중간 단절, 항목 완료 뒤 전체 incomplete, 같은 커서 이벤트 재수신을 포함한다. OpenAI의 sequence_number를 모든 SSE 서버의 Last-Event-ID와 같은 것으로 취급하지 않는다. 재연결 가능 여부는 해당 API의 저장·재생 계약과 별도로 확인하며, 실패한 스트림 뒤 도구를 다시 호출할지는 외부 작업 상태를 조회한 뒤 결정한다.
안전·보안·거버넌스
섹션 제목: “안전·보안·거버넌스”스트리밍 응답 계약을 운영할 때는 멱등성 키, 타임아웃 예산, 회로 차단기, 서명 검증, 버전 고정과 적합성 테스트를 기본 통제로 검토한다. 통제는 단순히 있는지만 확인하지 않고 어떤 위협을 줄이며, 어떤 잔여 위험이 남고, 실패했을 때 어떤 신호로 알 수 있는지를 연결한다.
민감 데이터와 비밀 값은 로그에 남기지 않고 필요한 시점에 최소 권한으로만 제공한다. 정책 예외는 승인자, 사유, 적용 범위, 만료 시점을 필수로 남겨야 한다. 사고 후에는 탐지부터 복구까지의 시간선과 의사결정 근거를 보존하고, 조치가 실제로 재발을 막았는지 동일 시나리오로 재시험한다.
적용 예시와 검토 목록
섹션 제목: “적용 예시와 검토 목록”스트리밍 응답 계약을 적용할 수 있는 대표 상황은 두 LLM 공급자 사이를 전환하면서 클라이언트 계약과 재시도 특성을 보존하는 상황이다. 먼저 기존 흐름을 변경하지 않고 입력·판단·결과·복구 경계의 관측 가능성을 확보한다. 그런 다음 소규모 대상에 정책을 적용하고 기준선을 넘으면 즉시 기존 경로로 되돌린다.
검토 목록은 다음과 같다.
- 용어의 범위와 소유 팀을 문서화했는가?
- 입력과 출력 계약, 정책 버전을 식별할 수 있는가?
- 성공, 경고, 중단 기준과 표본 수를 정했는가?
- 주요 실패 모드별 탐지 신호와 임시 조치가 있는가?
- 롤백·대체 경로·사람 승인의 시작 조건이 명확한가?
- 민감 데이터와 비밀 값의 로깅·보유·접근 정책을 검토했는가?
실제 배포 후에는 체크리스트의 통과 여부보다 각 항목에서 발생한 예외와 사람 개입을 기록해 다음 버전의 정책을 개선한다.
문서 관계
섹션 제목: “문서 관계”선행 개념
섹션 제목: “선행 개념”관련 문서
섹션 제목: “관련 문서”이 문서를 가리키는 문서
섹션 제목: “이 문서를 가리키는 문서”이 문서를 포함하는 코스
섹션 제목: “이 문서를 포함하는 코스”에이전트 상호운용과 실행 계약 · 프로덕션 AI API 시스템
참고와 다음 학습
섹션 제목: “참고와 다음 학습”참고 문헌
섹션 제목: “참고 문헌”- RFC 3986: Uniform Resource Identifier - standard
- HTTP Semantics RFC 9110 - standard
- RFC 8446: The Transport Layer Security Protocol Version 1.3 - standard
- RFC 1034: Domain Names - Concepts and Facilities - standard
- WHATWG HTML - Server-sent events - standard
- Responses streaming events - documentation
- Function calling - documentation
- Background mode - documentation
- Errors and recovery - documentation
코스에서 계속 읽기
섹션 제목: “코스에서 계속 읽기”- 에이전트 상호운용과 실행 계약: 다음 문서 — A2A 프로토콜 바인딩
- 프로덕션 AI API 시스템: 다음 문서 — 스트림 재개 프로토콜