메시지 스트리밍

메시지를 생성할 때 "stream": true를 설정하여 server-sent events (SSE)를 사용해 응답을 점진적으로 스트리밍할 수 있습니다.

SDK를 사용한 스트리밍

Python과 Typescript SDK는 다양한 방식의 스트리밍을 제공합니다. Python SDK는 동기 및 비동기 스트림을 모두 허용합니다. 자세한 내용은 각 SDK의 문서를 참조하세요.

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    model="claude-3-opus-20240229",
) as stream:
  for text in stream.text_stream:
      print(text, end="", flush=True)

이벤트 유형

각 server-sent 이벤트에는 명명된 이벤트 유형과 관련 JSON 데이터가 포함됩니다. 각 이벤트는 SSE 이벤트 이름(예: event: message_stop)을 사용하고 데이터에 일치하는 이벤트 type을 포함합니다.

각 스트림은 다음과 같은 이벤트 흐름을 사용합니다:

message_start: 빈 content를 가진 Message 객체를 포함합니다.
일련의 콘텐츠 블록으로, 각각 content_block_start, 하나 이상의 content_block_delta 이벤트, content_block_stop 이벤트를 가집니다. 각 콘텐츠 블록은 최종 Message content 배열에서의 인덱스에 해당하는 index를 가집니다.
하나 이상의 message_delta 이벤트로, 최종 Message 객체의 최상위 변경 사항을 나타냅니다.
최종 message_stop 이벤트.

Ping 이벤트

이벤트 스트림에는 임의 개수의 ping 이벤트가 포함될 수 있습니다.

오류 이벤트

이벤트 스트림에서 가끔 오류를 보낼 수 있습니다. 예를 들어, 사용량이 많은 기간 동안 overloaded_error를 받을 수 있는데, 이는 일반적으로 비스트리밍 컨텍스트에서 HTTP 529에 해당합니다:

오류 예시

event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

기타 이벤트

버전 정책에 따라 새로운 이벤트 유형을 추가할 수 있으며, 코드에서는 알 수 없는 이벤트 유형을 적절히 처리해야 합니다.

Delta 유형

각 content_block_delta 이벤트에는 주어진 index에서 content 블록을 업데이트하는 유형의 delta가 포함됩니다.

Text delta

text 콘텐츠 블록 delta는 다음과 같습니다:

Text delta

event: content_block_delta
data: {"type": "content_block_delta","index": 0,"delta": {"type": "text_delta", "text": "ello frien"}}

Input JSON delta

tool_use 콘텐츠 블록의 delta는 블록의 input 필드에 대한 업데이트에 해당합니다. 최대한의 세분성을 지원하기 위해 delta는 _부분 JSON 문자열_이며, 최종 tool_use.input은 항상 _객체_입니다.

문자열 delta를 누적하고 content_block_stop 이벤트를 받으면 Pydantic과 같은 라이브러리를 사용하여 부분 JSON 파싱을 수행하거나 SDK를 사용하여 파싱된 증분 값에 액세스할 수 있습니다.

tool_use 콘텐츠 블록 delta는 다음과 같습니다:

Input JSON delta

event: content_block_delta
data: {"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}

참고: 현재 모델은 input에서 한 번에 하나의 완전한 키와 값 속성만 내보낼 수 있습니다. 따라서 도구를 사용할 때 모델이 작업하는 동안 스트리밍 이벤트 사이에 지연이 있을 수 있습니다. input 키와 값이 누적되면 이를 여러 개의 content_block_delta 이벤트로 내보내 청크 단위의 부분 JSON으로 만들어 향후 모델에서 더 세밀한 세분성을 자동으로 지원할 수 있도록 합니다.

원시 HTTP 스트림 응답

스트리밍 모드를 사용할 때는 클라이언트 SDK를 사용하는 것이 좋습니다. 그러나 직접 API 통합을 구축하는 경우 이러한 이벤트를 직접 처리해야 합니다.

스트림 응답은 다음으로 구성됩니다:

message_start 이벤트
잠재적으로 여러 개의 콘텐츠 블록으로, 각각 다음을 포함합니다: a. content_block_start 이벤트 b. 잠재적으로 여러 개의 content_block_delta 이벤트 c. content_block_stop 이벤트
message_delta 이벤트
message_stop 이벤트

응답 전체에 ping 이벤트가 분산되어 있을 수 있습니다. 형식에 대한 자세한 내용은 이벤트 유형을 참조하세요.

기본 스트리밍 요청

Request

curl https://api.anthropic.com/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --data \
'{
  "model": "claude-3-opus-20240229",
  "messages": [{"role": "user", "content": "Hello"}],
  "max_tokens": 256,
  "stream": true
}'

Response

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-3-opus-20240229", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}

event: message_stop
data: {"type": "message_stop"}

도구 사용을 포함한 스트리밍 요청

이 요청에서는 Claude에게 도구를 사용하여 날씨를 알려달라고 요청합니다.

Request

  curl https://api.anthropic.com/v1/messages \
    -H "content-type: application/json" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "model": "claude-3-opus-20240229",
      "max_tokens": 1024,
      "tools": [
        {
          "name": "get_weather",
          "description": "Get the current weather in a given location",
          "input_schema": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
              }
            },
            "required": ["location"]
          }
        }
      ],
      "tool_choice": {"type": "any"},
      "messages": [
        {
          "role": "user",
          "content": "What is the weather like in San Francisco?"
        }
      ],
      "stream": true
    }'

Response

event: message_start
data: {"type":"message_start","message":{"id":"msg_014p7gG3wDgGV9EUtLvnow3U","type":"message","role":"assistant","model":"claude-3-haiku-20240307","stop_sequence":null,"usage":{"input_tokens":472,"output_tokens":2},"content":[],"stop_reason":null}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Okay"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":","}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" let"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"'s"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" check"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" the"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" weather"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" for"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" San"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Francisco"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":","}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" CA"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":":"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"tool_use","id":"toolu_01T1x1fJ34qAmk2tNTrN7Up6","name":"get_weather","input":{}}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"location\":"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" \"San"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" Francisc"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"o,"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" CA\""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":", "}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"\"unit\": \"fah"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"renheit\"}"}}

event: content_block_stop
data: {"type":"content_block_stop","index":1}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"tool_use","stop_sequence":null},"usage":{"output_tokens":89}}

event: message_stop
data: {"type":"message_stop"}

API 사용하기

Anthropic API

Amazon Bedrock API

Vertex AI

메시지 스트리밍

SDK를 사용한 스트리밍

이벤트 유형

Ping 이벤트

오류 이벤트

기타 이벤트

Delta 유형

Text delta

Input JSON delta

원시 HTTP 스트림 응답

기본 스트리밍 요청

도구 사용을 포함한 스트리밍 요청

API 사용하기

Anthropic API

Amazon Bedrock API

Vertex AI

​SDK를 사용한 스트리밍

​이벤트 유형

​Ping 이벤트

​오류 이벤트

​기타 이벤트

​Delta 유형

​Text delta

​Input JSON delta

​원시 HTTP 스트림 응답

​기본 스트리밍 요청

​도구 사용을 포함한 스트리밍 요청

SDK를 사용한 스트리밍

이벤트 유형

Ping 이벤트

오류 이벤트

기타 이벤트

Delta 유형

Text delta

Input JSON delta

원시 HTTP 스트림 응답

기본 스트리밍 요청

도구 사용을 포함한 스트리밍 요청