메인 콘텐츠로 건너뛰기

짧은 답변

세 문장:
  1. 스트리밍과 비스트리밍은 전적으로 사용자의 코드에 의해 결정됩니다—요청 본문의 stream 필드입니다. 동일한 키, 동일한 모델, 동일한 엔드포인트에서 이 값이 계속 바뀐다면 값을 바꾸는 것은 클라이언트 코드(또는 이를 감싸는 SDK / 프레임워크)입니다. 게이트웨이는 이를 임의로 전환하지 않습니다.
  2. 두 모드는 최종 콘텐츠가 동일하게 반환되며 과금도 동일합니다. 차이는 텍스트를 받는 시점과 파싱하는 방법뿐입니다. 한 가지 예외는 콘텐츠 안전 필터링입니다. 비스트리밍 요청은 자동으로 다른 경로로 전환되지만, 스트리밍 요청은 중단됩니다. 자세한 내용은 콘텐츠가 필터링될 때 스트리밍 요청과 비스트리밍 요청은 어떻게 다른가요?를 참조하십시오.
  3. 선택 방법: 사람이 화면을 보고 있음 → 스트리밍, 프로그램이 결과를 처리함(JSON 파싱, 일괄 작업, 도구 호출) → 비스트리밍입니다.

차이점 한눈에 보기

요청이 스트리밍과 비스트리밍 사이에서 전환되는 이유는 무엇입니까?

가장 흔한 질문이며, 답은 다음과 같습니다. 요청을 변경하는 요소가 사용자 측에 있습니다. 다음 목록을 차례로 확인하십시오. 대부분의 경우 이 중 하나가 원인입니다.
전형적인 경우는 stream=config.get("stream", False) 또는 stream=is_web_request입니다. 서로 다른 진입점에서 서로 다른 값으로 동일한 함수에 도달하면 로그상 모드가 무작위로 전환되는 것처럼 보입니다.확인 방법: 실제로 전송하는 요청 본문을 출력하고 stream 필드를 확인하십시오.
동일한 비즈니스 로직도 클라이언트에 따라 다르게 동작합니다.
  • OpenAI SDK chat.completions.create(): 기본적으로 비스트리밍
  • client.chat.completions.stream() 또는 with_streaming_response: 스트리밍
  • LangChain / LlamaIndex와 같은 래퍼: invoke 또는 stream를 호출하는지, 그리고 모델 객체를 생성할 때 streaming=True를 전달했는지에 따라 달라짐
  • 데스크톱 클라이언트, 에이전트 도구, 워크플로 플랫폼: 일반적으로 설정에 “스트리밍 출력” 토글을 제공하며, 기본값은 서로 다름
확인 방법: 실제로 호출을 실행한 진입점을 확인하십시오.
웹 채팅 UI(스트리밍)와 야간 일괄 작업(비스트리밍)에서 하나의 키를 함께 사용하면 로그를 합쳐서 볼 때 무작위로 보입니다.확인 방법: 사용 사례별로 별도의 토큰을 생성하십시오. 그러면 로그가 자동으로 분리됩니다. 토큰 관리를 참조하십시오.
실제로 stream: true을 전송했지만 Nginx, 기업 게이트웨이 또는 일부 프록시가 응답을 버퍼링했을 수 있습니다. 서버는 응답을 청크 단위로 전송했지만 프록시가 이를 보관했다가 한 번에 모두 전달하므로 비스트리밍처럼 느껴집니다.확인 방법: 프록시를 우회하여 한 번 테스트하고, Nginx에서 버퍼링을 끄십시오(proxy_buffering off;). 이 경우 게이트웨이가 실제로 스트리밍하여 전송했으므로 콘솔 로그에는 여전히 is_stream = true이 표시된다는 점에 유의하십시오.
특정 호출이 실제로 어떻게 처리되었는지 확인하려면: 콘솔 로그에서 is_stream 필드를 확인하거나 로그 쿼리 API를 사용하여 일괄 조회하십시오. 이것이 사실을 판단하는 기준이며, 단순한 인상보다 훨씬 신뢰할 수 있습니다.

시나리오별 선택

스트리밍 사용

  • 채팅 UI 및 지원 봇 — 사용자는 즉각적인 피드백이 필요합니다
  • IDE 플러그인 / 코딩 어시스턴트(Claude Code, Cursor 등)
  • 장문 생성(긴 문서, 긴 번역, 대규모 코드 블록)
  • 장시간 추론 모델 작업 — 최소한 진행 상황을 확인할 수 있습니다
  • 사용자가 생성 도중 “중지”를 누를 수 있는 모든 경우

논스트리밍 사용

  • 구조화된 출력: 전체 JSON이 필요한 경우 json.loads()
  • 함수 호출 / 도구 호출 인수 파싱
  • 일괄 처리, 오프라인 작업, 예약된 작업
  • 최종 결과만 중요하고 대기하는 사용자가 없는 백엔드 흐름
  • 빠른 확인, 디버깅, 테스트 케이스 작성
몇 가지 특수한 경우는 다음과 같습니다.

통합 작업: 동일한 작업을 두 방식으로

Claude의 네이티브 형식(/v1/messages)은 다른 스트리밍 프로토콜을 사용합니다. 즉, OpenAI의 통일된 data: 청크가 아니라 Anthropic의 명명된 이벤트 SSE(message_start / content_block_delta / message_delta 및 기타)를 사용하며, usage는 message_start 및 message_delta 이벤트에 걸쳐 분할됩니다. 전체 파싱 가이드는 Claude 네이티브 형식: 스트리밍 및 비스트리밍 응답을 참조하십시오.

과금 및 사용량: 어느 쪽이든 동일합니다

스트리밍은 더 저렴하지도, 더 비싸지도 않습니다. 과금은 token 단위로 이루어지며, 바이트가 전송되는 방식과는 관련이 없습니다.중간에 연결을 끊어도 과금됩니다—Ctrl+C에 도달하거나 클라이언트에서 시간 초과가 발생한 후에도 업스트림 생성은 완료될 때까지 계속 실행되며 요청에는 정상적으로 과금됩니다. 따라서 “비용을 절약하려고 스트림을 일찍 중단하기”는 통하지 않습니다.
usage와 관련된 두 가지 함정은 다음과 같습니다.
  1. 스트리밍에서는 기본적으로 사용량이 반환되지 않습니다. OpenAI 호환 엔드포인트에서는 stream_options: {"include_usage": true}를 전달해야 하며, 사용량은 최종 청크에 포함되어 도착합니다(이때 choices 배열은 비어 있으므로 인덱싱하기 전에 확인해야 합니다). APIYI의 여러 모델에서 정상 작동하는 것이 확인되었습니다.
  2. API가 반환한 usage을 기준으로 청구서를 대조하지 마십시오. 특히 캐시 관련 필드는 더욱 그렇습니다. 반환된 값이 실제 과금 내역과 항상 일치하는 것은 아니며, 캐시 적중 여부는 **콘솔 로그의 “캐시 과금 세부 정보”**로 판단합니다. 캐시 과금 설명을 참조하십시오.
어느 경우든 콘솔 로그에는 모든 호출의 token 수, 지연 시간 및 과금 내역이 기록되므로 전송 모드는 아무런 차이를 만들지 않습니다. 필드 의미는 로그 과금 세부 정보 이해를 참조하십시오.

6가지 일반적인 오해

두 가지를 구분해야 합니다. 스트리밍은 전체 생성 시간을 단축하지 않습니다. 첫 token부터 마지막 token까지의 총 시간은 원래 걸리던 만큼 걸리며, 이 부분은 변하지 않습니다.하지만 스트리밍은 “아무것도 반환되지 않는” 문제를 해결합니다. 클라이언트 읽기 타임아웃을 이벤트 사이의 간격을 감당할 수 있도록 설정하면 됩니다. (추론 모델의 사고 단계에서 측정된 최대 무응답 간격은 약 42초이며, 그 사이에 keepalive 핑이 전송되므로 90~120초면 충분합니다.) 그러면 타임아웃이 잘못 발생하지 않습니다. 진정으로 유지할 수 없는 것은 순수 비스트리밍입니다. 즉, 10분이 넘는 생성을 처음부터 끝까지 하나의 타임아웃 값으로 처리하는 방식입니다.따라서 올바른 접근 방식은 긴 출력을 스트리밍하고, 이벤트 간 간격에 맞춰 읽기 타임아웃을 설정하는 것입니다. 시나리오별 값은 API 타임아웃을 방지하는 방법에 있으며, 전체 방법은 장문 출력 사용 방법에 설명되어 있습니다.
첫 바이트는 더 빠르지만, 전체 시간은 그렇지 않습니다. 동일한 모델과 prompt를 사용하는 경우 스트리밍과 비스트리밍은 대략 같은 시간에 완료됩니다.스트리밍이 제공하는 것은 체감 속도입니다. 사용자는 30초 동안 스피너를 바라보는 대신 1초 이내에 화면의 움직임을 볼 수 있습니다. 아무도 화면을 보고 있지 않다면 그 가치는 0입니다.
아닙니다. 위의 “과금 및 사용량”을 참조하십시오. 과금은 동일하며, 중간에 연결을 끊어도 요금이 부과됩니다.
아닙니다. 텍스트 채팅 모델은 일반적으로 지원하지만, 이미지 생성, 임베딩 및 리랭크 엔드포인트에는 스트리밍 개념이 없으며 stream을 무시하거나 거부합니다.일부 모델은 스트리밍 사용 시 특정 매개변수 조합에 추가 제한이 있습니다. 확실하지 않다면 먼저 비스트리밍으로 호출이 작동하도록 한 다음 stream: true을 추가하십시오.
둘 다 각각의 실패 방식이 있습니다.
  • 비스트리밍의 위험: 전체 생성 과정 동안 연결이 무응답 상태이므로 프록시, CDN 및 기업 게이트웨이가 유휴 타임아웃으로 연결을 끊을 수 있습니다. 응답 본문이 매우 큰 경우(base64 이미지 출력은 쉽게 수십 MB에 이를 수 있음) 멈춘 종료 처리 문제가 발생할 수도 있습니다. 전송은 완료되었지만 반환되지 않는 요청 및 로그에는 완료로 표시되지만 클라이언트가 아무것도 받지 못하는 경우를 참조하십시오.
  • 스트리밍의 위험: SSE를 지원하지 않거나 버퍼링을 강제하는 미들박스와 호환하기 어렵고, 클라이언트 파싱이 더 복잡하며 미묘한 오류가 발생하기 쉽습니다.
또한 api-cf.apiyi.com (CDN 엔드포인트)에는 약 100초의 요청 제한 시간이 있으며 두 모드 모두에 영향을 미친다는 점에 유의하십시오. 긴 요청에는 api.apiyi.com 또는 b.apiyi.com를 사용하십시오. 기본 URL 구성 가이드를 참조하십시오.
가져올 수 있습니다. 다만 직접 조합해야 합니다. 각 청크의 delta.content를 순서대로 연결하면 비스트리밍 message.content과 정확히 동일한 결과를 얻을 수 있습니다.조합한 텍스트가 불완전해 보인다면 다음 세 가지를 확인하십시오. finish_reason을 무시했는지, data: [DONE]을 받기 전에 루프를 종료했는지, 그리고 미들박스가 응답을 잘라냈는지 확인해야 합니다.

스트리밍이 작동하지 않습니까? 네 단계

1

요청 본문에 실제로 stream: true가 포함되어 있는지 확인합니다

실제로 전송하는 JSON을 출력합니다. 래퍼 라이브러리를 사용하는 경우 “전달했다고 생각한 것”과 “실제로 전달된 것”이 다른 경우가 많습니다.
2

curl -N으로 직접 테스트합니다

위의 “cURL 나란히 보기” 탭에 있는 명령을 사용하여 자체 코드와 모든 프록시를 우회합니다. curl에서 청크가 점진적으로 도착하는 것이 확인되면 서버 측은 정상이며, 문제는 클라이언트 또는 중간 장비에 있습니다.
3

중간 장비의 버퍼링을 확인합니다

Nginx에 proxy_buffering off;를 추가합니다. 기업 게이트웨이와 보안 어플라이언스는 text/event-stream를 전체 페이로드로 검사할 수 있으므로 네트워크 관리자에게 통과를 허용해 달라고 요청합니다.
4

파싱 로직을 검토합니다

SSE를 한 줄씩 읽고, 빈 줄과 :로 시작하는 주석 줄은 건너뛴 다음 data: [DONE]에서 중지합니다. usage를 전달하는 마지막 청크에는 빈 choices 배열이 있으므로 해당 배열을 인덱싱하지 마십시오.
여기까지 진행했는데도 답을 찾지 못했다면 request_id와 함께 지원팀에 문의하십시오. 콘솔 로그에서 해당 호출이 스트림으로 처리되었는지와 총 지연 시간 및 첫 바이트까지 걸린 시간을 바로 확인할 수 있습니다.

관련 문서

API 타임아웃을 방지하는 방법

시나리오별 타임아웃 값과 긴 출력을 스트리밍해야 하는 이유

기본 URL 구성 가이드

엔드포인트 간 차이와 CDN 노드의 100초 제한

로그에는 완료로 표시되지만 응답이 없는 경우

세그먼트 타이밍을 포함한 대표적인 대규모 비스트리밍 응답 문제

Claude 스트리밍 및 비스트리밍

Anthropic의 네이티브 명명 이벤트 SSE 프로토콜 파싱

텍스트 생성 API

전체 매개변수 목록 및 호출 예시

로그 과금 세부 정보 이해하기

is_stream을 포함한 각 콘솔 로그 필드의 의미