BroadRouter

채팅 완성 스트리밍과 끊긴 연결 처리하기

업데이트

/v1/chat/completions 요청에 stream을 true로 설정하고, 문자 그대로의 data: [DONE] 마커가 올 때까지 Server-Sent Events를 읽으면 됩니다. stream_options에 include_usage를 추가하면 마지막 청크로 토큰 수를 받을 수 있습니다. [DONE] 전에 연결이 끊기면 답변이 불완전한 것으로 보고 X-Request-ID를 기록하세요.

스트리밍을 쓰면 에이전트나 채팅 인터페이스가 답변을 생성되는 대로 보여 줄 수 있습니다. BroadNet Inference는 표준 chat completions 스트리밍 형식을 쓰므로 OpenAI Python SDK와 OpenAI Node SDK가 파싱을 대신 처리합니다.

curl로 스트리밍하기

curl -N -D stream-headers.txt https://inference.broadnet.ai/v1/chat/completions \
  -H "Authorization: Bearer $BROADNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"broadnet/gemma-4-26b-a4b","stream":true,"stream_options":{"include_usage":true},"messages":[{"role":"user","content":"Count from one to three."}]}'

-N은 curl의 버퍼링을 끄고, -D는 X-Request-ID를 포함한 응답 헤더를 파일로 저장합니다.

스트림은 어떤 모습인가요?

응답은 Server-Sent Events 스트림입니다. WHATWG HTML 표준에 따르면 각 이벤트는 하나 이상의 data: 줄과 그 뒤의 빈 줄로 이루어지며, 콜론으로 시작하는 줄은 무시해도 되는 주석입니다. data: 줄마다 JSON 청크가 하나씩 담기고, 텍스트는 choices[0].delta.content에 들어 있습니다.

지켜야 할 규칙

  1. 문자 그대로의 data: [DONE] 줄이 올 때까지 이벤트를 읽은 뒤 리더를 닫으세요.
  2. stream_options: {"include_usage": true}를 보내면 [DONE] 직전에 청크가 하나 더 옵니다. 이 청크에는 요청 전체의 usage와 빈 choices 리스트가 담겨 있으므로, 인덱스로 접근하기 전에 choices를 확인하세요.
  3. 모델이 보고하는 경우 이 usage에는 completion_tokens_details.reasoning_tokens(DeepSeek V4.1 Flash, GLM 5.3, Qwen3.8 27B는 먼저 추론합니다)와 prompt_tokens_details.cached_tokens가 포함됩니다. 캐시된 토큰은 더 낮은 캐시 입력 가격으로 과금됩니다.

Python SDK로 스트리밍하기

import os
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

stream = client.chat.completions.create(
    model="broadnet/gemma-4-26b-a4b",
    messages=[{"role": "user", "content": "Count from one to three."}],
    stream=True,
    stream_options={"include_usage": True},
)
usage = None
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:
        usage = chunk.usage
print()
print(usage)  # None means the stream ended before the usage chunk

SDK가 [DONE]까지 대신 읽어 줍니다. 마지막 줄에서 usage가 None이면 usage 청크가 오기 전에 스트림이 끝났다는 뜻입니다. 같은 루프를 JavaScript로 작성한 예는 OpenAI Node SDK 가이드에 있습니다.

스트림이 중간에 끊겼을 때

[DONE] 전에 연결이 닫히면 답변은 불완전합니다. BroadNet의 안내는 다음과 같습니다.

  • X-Request-ID를 기록하세요.
  • 애플리케이션이 새 요청을 안전하게 보낼 수 있는지 판단하세요. 재시도는 새로운 추론이며, 종량제에서는 다시 과금됩니다.

무제한 플랜을 쓰는 에이전트라면 재시도에 추가 비용이 들지 않지만, 재시도가 실행되는 동안에는 세션을 점유합니다.

BroadNet 문서에 따르면 프로덕션에서 스트리밍에 의존하기 전에 모델별 릴리스 검증이 여전히 필요합니다. 실제로 배포할 모델로 테스트하세요.

문제 해결

  • 모든 내용이 마지막에 한꺼번에 출력됩니다. curl에는 -N이 필요합니다. 자체 프록시를 거친다면 text/event-stream 응답의 버퍼링을 끄세요.
  • 마지막 청크에서 IndexError 또는 undefined가 발생합니다. usage 청크의 choices 리스트는 비어 있습니다. [0]을 읽기 전에 chunk.choices를 확인하세요.
  • usage가 전혀 오지 않습니다. stream_options를 보내지 않았거나, 마지막 청크 전에 스트림이 끊긴 것입니다.
  • finish_reason이 length이고 텍스트가 거의 없는 채로 스트림이 멈춥니다. 추론 모델이 max_tokens를 추론에 다 썼습니다. 추론 모델이 빈 응답을 반환하는 이유를 참고하세요.
  • 병렬로 스트리밍하다가 429가 발생합니다. 열려 있는 스트림은 각각 처리 중인 요청 하나로 계산됩니다. 종량제 키는 동시 처리 4 건까지 허용합니다. BroadNet 오류 코드와 재시도를 참고하세요.

자주 묻는 질문

채팅 완성을 스트리밍할 때 토큰 사용량은 어떻게 받나요?

stream_options에 include_usage를 true로 설정해 보내세요. data: [DONE] 직전에 청크가 하나 더 오며, 여기에는 usage가 채워져 있고 choices 배열은 비어 있습니다. 그 전에 스트림이 끊기면 이 청크는 오지 않습니다.

curl에서 스트리밍 응답이 한꺼번에 출력되는 이유는 무엇인가요?

curl은 기본적으로 출력을 버퍼링합니다. -N 플래그(버퍼링 끄기)를 추가하면 Server-Sent Events가 도착하는 대로 하나씩 출력됩니다.

스트림을 재시도하면 요금이 두 번 청구되나요?

종량제에서는 그렇습니다. 재시도는 새로운 추론 요청이기 때문입니다. DeepSeek V4.1 Flash 무제한 플랜에는 토큰 계량이 없지만, 재시도가 실행되는 동안에는 세션을 점유합니다.

스트리밍은 일반 요청보다 비싼가요?

아니요. 스트리밍은 답변을 전달하는 방식만 바꿀 뿐, 과금 방식은 바꾸지 않습니다. 종량제에서는 스트리밍을 쓰지 않는 요청과 똑같은 토큰당 입력 가격과 출력 가격을 냅니다.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기