스트리밍 응답 가이드

스트리밍 응답 가이드

Chat API가 텍스트 생성 같은 이벤트를 실시간으로 스트리밍할 수 있는 방법을 설명하는 문서예요.

출처: 문서

본문

Chat API는 이벤트(예: 텍스트 생성)가 나오는 대로 스트리밍할 수 있어요. 즉 전체 생성이 더 오래 걸리더라도 모델의 부분 결과를 몇 순간 안에 표시할 수 있단 뜻이에요.

여러분은 이미 스트리밍에 익숙할 거예요. Cohere 플레이그라운드로 모델에 질문하면, 인터페이스는 한 덩어리의 텍스트를 출력하는 대신 텍스트를 한 번에 몇 단어씩 스트리밍해요. 많은 사용자 인터페이스에서 스트리밍을 활성화하면 인지된 지연 시간(perceived latency)을 낮춰 사용자 경험이 개선됩니다.

스트림 이벤트(Stream Events)

스트리밍이 활성화되면 API는 이벤트를 하나씩 아래로 보내요. 각 이벤트는 type을 갖습니다. 서로 다른 유형의 이벤트는 올바르게 처리해야 합니다.

다음은 스트리밍된 응답에서 LLM 응답의 텍스트 내용을 담고 있는 content-delta 이벤트 유형을 출력하는 예시예요.

PYTHON

import cohere

co = cohere.ClientV2(api_key="<YOUR API KEY>")

res = co.chat_stream(
    model="command-a-plus-05-2026",
    messages=[{"role": "user", "content": "What is an LLM?"}],
)

for event in res:
    if event:
        if event.type == "content-delta":
            print(event.delta.message.content.text, end="")

cURL

curl --request POST \
  --url https://api.cohere.ai/v2/chat \
  --header 'accept: text/event-stream' \
  --header 'content-type: application/json' \
  --header "Authorization: bearer ***" \
  --data '{
    "model": "command-a-plus-05-2026",
    "messages": [
      {
        "role": "user",
        "content": "What is an LLM?"
      }
    ],
    "stream": true
  }'

# Sample output (streamed)

A large language model (LLM) is a type of artificial neural network model that has been trained on massive amounts of text data ...

다음 섹션들은 스트리밍 세션 동안 내보내지는 서로 다른 유형의 이벤트를 설명해요.

기본 Chat 스트림 이벤트(Basic Chat Stream Events)

message-start

스트림의 첫 번째 이벤트로, id 같은 요청에 대한 메타데이터를 담고 있어요. message-start 이벤트는 하나만 내보내집니다.

content-start

메시지의 콘텐츠 블록 시작을 나타내는 이벤트예요. content-start 이벤트는 하나만 내보내집니다.

content-delta

모델에서 텍스트의 다음 청크가 돌아올 때마다 내보내지는 이벤트예요. 모델이 텍스트 생성을 계속함에 따라 이 유형의 이벤트가 여러 번 내보내집니다. 각 이벤트는 delta.message.content.text 필드를 통해 토큰 하나를 생성해요.

# Sample events

type='content-delta' index=0 delta=ChatContentDeltaEventDelta(message=ChatContentDeltaEventDeltaMessage(content=ChatContentDeltaEventDeltaMessageContent(text='A')))

type='content-delta' index=0 delta=ChatContentDeltaEventDelta(message=ChatContentDeltaEventDeltaMessage(content=ChatContentDeltaEventDeltaMessageContent(text=' large')))

type='content-delta' index=0 delta=ChatContentDeltaEventDelta(message=ChatContentDeltaEventDeltaMessage(content=ChatContentDeltaEventDeltaMessageContent(text=' language')))

...

content-end

메시지의 콘텐츠 블록 끝을 나타내는 이벤트예요. content-end 이벤트는 하나만 내보내집니다.

message-end

스트리밍된 응답의 끝을 나타내는 스트림의 마지막 이벤트예요. message-end 이벤트는 하나만 내보내집니다.

검색 증강 생성 스트림 이벤트(Retrieval Augmented Generation Stream Events)

message-start

기본 chat 스트림 이벤트와 동일해요.

content-start

기본 chat 스트림 이벤트와 동일합니다.

content-delta

기본 chat 스트림 이벤트와 동일해요.

citation-start

응답에서 생성된 인용(citation)마다 내보내집니다.

# Sample event

type='citation-start' index=0 delta=CitationStartEventDelta(message=CitationStartEventDeltaMessage(citations=Citation(start=14, end=29, text='gym memberships', sources=[DocumentSource(type='document', id='doc:1', document={'id': 'doc:1', 'text': 'Health and Wellness Benefits: We care about your well-being and offer gym memberships, on-site yoga classes, and comprehensive health insurance.'})])))

citation-end

인용의 끝을 나타내기 위해 내보내집니다. 생성된 인용이 여러 개라면, 이벤트는 citation-start와 citation-end 쌍의 연속으로 오게 돼요.

content-end

기본 chat 스트림 이벤트와 동일합니다.

message-end

기본 chat 스트림 이벤트와 동일해요.

도구 사용 스트림 이벤트 (툴 호출용, Tool Use Stream Events)

message-start

기본 chat 스트림 이벤트와 동일해요.

tool-plan-delta

도구 계획(tool plan)의 다음 토큰이 생성될 때 내보내집니다.

# Sample events

type='tool-plan-delta' delta=ChatToolPlanDeltaEventDelta(tool_plan=None, message={'tool_plan': 'I'})

type='tool-plan-delta' delta=ChatToolPlanDeltaEventDelta(tool_plan=None, message={'tool_plan': ' will'})

type='tool-plan-delta' delta=ChatToolPlanDeltaEventDelta(tool_plan=None, message={'tool_plan': ' use'})

...

tool-call-start

모델이 실행을 요구하는 도구 호출을 생성할 때 내보내집니다. 이 이벤트는 도구의 이름과 도구 호출 ID를 담고 있는 tool_calls 목록을 포함해요.

# Sample event

type='tool-call-start' index=0 delta=ChatToolCallStartEventDelta(tool_call=None, message={'tool_calls': {'id': 'get_weather_nsz5zm3w56q3', 'type': 'function', 'function': {'name': 'get_weather', 'arguments': ''}}})

tool-call-delta

도구 호출의 다음 토큰이 생성될 때 내보내집니다.

# Sample events

type='tool-call-delta' index=0 delta=ChatToolCallDeltaEventDelta(tool_call=None, message={'tool_calls': {'function': {'arguments': '{\n    "'}}})

type='tool-call-delta' index=0 delta=ChatToolCallDeltaEventDelta(tool_call=None, message={'tool_calls': {'function': {'arguments': 'location'}}})

type='tool-call-delta' index=0 delta=ChatToolCallDeltaEventDelta(tool_call=None, message={'tool_calls': {'function': {'arguments': '":'}}})

...

tool-call-end

도구 호출이 끝났을 때 내보내집니다.

message-end

기본 chat 스트림 이벤트와 동일해요.

도구 사용 스트림 이벤트 (응답 생성용, Tool Use Stream Events)

message-start

기본 chat 스트림 이벤트와 동일합니다.

content-start

기본 chat 스트림 이벤트와 동일해요.

content-delta

기본 chat 스트림 이벤트와 동일합니다.

citation-start

응답에서 생성된 인용마다 내보내집니다.

citation-end

인용의 끝을 나타내기 위해 내보내집니다. 생성된 인용이 여러 개라면, 이벤트는 citation-start와 citation-end 쌍의 연속으로 오게 돼요.

content-end

기본 chat 스트림 이벤트와 동일합니다.

message-end

기본 chat 스트림 이벤트와 동일해요.

더 알아보기 (Learn more)

• Cohere 문서