스트리밍 (Streaming)

스트리밍 (Streaming interactions)

모델이 답을 전부 만든 뒤에 한 번에 받는 대신, 생성되는 중간중간 텍스트 조각을 실시간으로 받고 싶을 때가 있어요. Gemini API는 stream: true를 켜면 server-sent events(SSE) 방식으로 응답을 조각조각 내려보냅니다. 길게 렌더링되는 에이전트나 채팅 UI에서 유용해요.

출처: 스트리밍 - Google 공식 문서

기본 사용법

interactions.create에 stream=True만 붙이면 이벤트 스트림이 반환돼요. step.delta 이벤트가 텍스트 조각을 실어 보내니, 그걸 누적해서 화면에 찍어 주면 됩니다.

from google import genai

client = genai.Client()

stream = client.interactions.create(
    model="gemini-3.7-flash",
    input="Count from 1 to 25.",
    stream=True,
)
for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "text":
            print(event.delta.text, end="", flush=True)

REST에서는 URL에 ?alt=sse를 붙이고 --no-buffer로 스트림을 그대로 받으면 됩니다:

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  --no-buffer \
  -d '{
    "model": "gemini-3.7-flash",
    "input": "Count from 1 to 25.",
    "stream": true
  }'

이벤트 흐름

Interactions API는 텍스트·도구 호출·생각 같은 모든 콘텐츠를 스텝(step) 기반의 대칭 이벤트로 다뤄요. 각 스트림은 보통 이런 순서로 진행됩니다.

  1. interaction.created — 인터랙션 생성, ID·모델·상태 포함
  2. 일련의 스텝들 — 각각 step.start(스텝 타입 시작) → step.delta(증분 데이터) → step.stop(완료)
  3. interaction.completed — 최종 usage 통계와 함께 종료

stream: false로 두면 API는 steps 배열이 든 단일 interaction 객체를 돌려줘요. 배열의 각 원소가 하나의 step.start → step.delta(s) → step.stop 주기의 완성본이 되는 구조죠.

주요 이벤트와 델타 타입

  • interaction.created — 인터랙션 처음 생성 시, ID·모델·초기 상태를 담아요.
  • interaction.status_update — 스텝 사이에 인터랙션 수준의 상태 전이를 알려줘요.
  • step.start — 새 스텝 시작. 스텝 타입에 따라 기대할 델타가 달라집니다.
    • model_output: text, image, audio 델타 — 모델의 최종 응답
    • thought: thought_signature, thought_summary 델타 — 생각(추론)
    • function_call: arguments_delta — 함수 호출, 상태를 requires_action으로 전환
    • 서버 측 도구: google_search_call, code_execution_call 등
  • step.delta — 현재 스텝의 증분 데이터. delta의 type 필드가 형태를 결정해요. 텍스트 델타는 type: "text", 함수 인자는 type: "arguments_delta"로 부분 JSON을 실어 보냅니다.
  • step.stop — 스텝 종료. 스텝 index 포함.
  • interaction.completed — 최종 인터랙션 객체와 usage 통계. 비스트리밍 모드에서는 이 객체가 곧 응답 본문이에요.
  • error — 오류 발생 시 message와 code를 담아 보냅니다.

스트리밍과 함수 호출

함수 호출을 스트리밍으로 하려면 멀티턴 대화를 직접 처리해야 해요.

  1. 1턴(함수 요청): tools를 정의해 stream: true로 호출. API가 function_call 스텝을 스트리밍하므로, step.delta의 arguments_delta JSON 조각들을 누적해서 모아야 합니다.
  2. 2턴(결과 전달): 첫 인터랙션의 previous_interaction_id를 넘기고 input 배열 안에 function_result 블록을 실어 다시 호출. 스트림이 재개되며 모델이 최종 응답을 생성해요.

인식하지 못하는 이벤트 타입이 나오면 예외를 던지지 말고, 로그만 남기고 건너뛰도록 코드를 짜 두는 게 안전해요. API 버전 정책상 새 이벤트·델타 타입이 계속 추가될 수 있기 때문입니다.

더 알아보기