스트리밍 추론 — 생성되는 대로 출력 받기

모델이 전체 결과를 다 만든 다음에야 응답을 받는 게 답답할 때가 있어요. 스트리밍은 모델이 생성하는 대로 출력을 조각조각 받아서, 토큰을 점진적으로 만들어내는 LLM이나 중간 미리보기를 보여주는 모델, 혹은 사용자에게 진행 상황을 보여주고 싶은 상황에 유용한 방식이에요. 내부적으로 stream()은 fal.run으로 직접 HTTP 요청을 보내는데, 이때 Server-Sent Events(SSE) 프로토콜을 써요. SDK가 이 SSE 커넥션을 이터레이터로 감싸줘서 각 이벤트가 파싱된 객체로 도착해요.

출처: fal.ai Streaming Inference

`stream()` 사용하기

모델 ID와 인자를 넣고 루프로 이벤트를 하나씩 받아오면 돼요.

import fal_client

for event in fal_client.stream(
    "fal-ai/flux/schnell",
    arguments={"prompt": "a sunset over mountains"},
):
    print(event)

각 이벤트는 모델에 따라 모양이 달라지는 딕셔너리/객체예요. REST API는 data: 프리픽스가 붙은 SSE 형식 이벤트를 돌려주고, SDK가 자동으로 객체로 파싱해요. 모델에 따라 진행률 업데이트에 이어 최종 결과가 이어서 도착하는 형태가 흔해요.

{ "progress": 0.25, "message": "Generating..." }
{ "progress": 0.50, "message": "Generating..." }
{ "progress": 0.75, "message": "Generating..." }
{ "images": [{ "url": "https://v3.fal.media/files/..." }], "seed": 42 }

스트리밍은 /stream 엔드포인트가 있는 모델에서만 지원돼요. stream()을 쓰기 전에 해당 모델의 API 페이지에서 지원 여부를 확인해 주세요.

`stream()` 파라미터

stream()은 path와 timeout 두 가지만 받아요. path는 모델 ID 뒤에 붙는 경로로, 스트리밍 엔드포인트에서는 기본값이 "/stream"이에요. timeout은 클라이언트가 SSE 커넥션을 기다리는 최대 HTTP 타임아웃(초)이에요.

주의할 점은, stream()은 큐를 우회해 직접 HTTP 요청을 보내기 때문에 hint·priority·start_timeout·client_timeout·headers를 지원하지 않는다는 거예요. 재시도도 없어요. 큐 기반 안정성이 필요하다면 submit()으로 제출한 뒤 with_logs=True로 진행 상황을 폴링하는 게 맞아요.

언제 스트리밍을 쓰나요

LLM·챗 모델처럼 토큰 단위로 결과가 나오는 경우, 실시간 진행 상황을 사용자에게 보여주고 싶은 인터랙티브 앱, 그리고 인지되는 지연(perceived latency)을 줄이고 싶은 경우에 스트리밍이 잘 어울려요. 반대로 중간 출력 없이 하나의 결과만 돌려주는 모델이나, 최종 응답만 필요한 백엔드 간 통합이라면 스트리밍이 필요 없어요. 그런 상황에서는 run()이나 subscribe()가 더 단순하죠.

스트리밍 추론 — 생성되는 대로 출력 받기