메시지 스트리밍

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

SDK를 사용한 스트리밍

Python과 TypeScript SDK는 여러 가지 스트리밍 방법을 제공합니다. Python SDK는 동기 및 비동기 스트림을 모두 지원합니다. 자세한 내용은 각 SDK의 문서를 참조하세요.

이벤트 유형

각 서버 전송 이벤트는 명명된 이벤트 유형과 관련 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"}}

기타 이벤트

버전 관리 정책에 따라 새로운 이벤트 유형이 추가될 수 있으며, 코드는 알 수 없는 이벤트 유형을 원활하게 처리해야 합니다.

델타 유형

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

텍스트 델타

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

텍스트 델타
event: content_block_delta
data: {"type": "content_block_delta","index": 0,"delta": {"type": "text_delta", "text": "ello frien"}}

입력 JSON 델타

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

content_block_stop 이벤트를 받을 때까지 문자열 델타를 누적하고 Pydantic과 같은 라이브러리를 사용하여 JSON을 파싱하거나, 파싱된 증분 값에 접근하기 위한 헬퍼를 제공하는 SDK를 사용할 수 있습니다.

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

입력 JSON 델타
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으로 방출됩니다.

Raw HTTP 스트림 응답

스트리밍 모드를 사용할 때는 클라이언트 SDK를 사용하는 것을 강력히 권장합니다. 하지만 직접 API 통합을 구축하는 경우에는 이러한 이벤트를 직접 처리해야 합니다.

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

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

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

기본 스트리밍 요청

요청
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-5-sonnet-20241022",
  "messages": [{"role": "user", "content": "Hello"}],
  "max_tokens": 256,
  "stream": true
}'

응답
event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-3-5-sonnet-20241022", "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에게 도구를 사용하여 날씨를 알려달라고 요청합니다.

요청
  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-5-sonnet-20241022",
      "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
    }'

응답
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 사용하기

Amazon Bedrock API

Vertex AI

Anthropic API

메시지 스트리밍

SDK를 사용한 스트리밍

이벤트 유형

Ping 이벤트

오류 이벤트

기타 이벤트

델타 유형

텍스트 델타

입력 JSON 델타

Raw HTTP 스트림 응답

기본 스트리밍 요청

도구 사용이 포함된 스트리밍 요청

API 사용하기

Amazon Bedrock API

Vertex AI

Anthropic API

​SDK를 사용한 스트리밍

​이벤트 유형

​Ping 이벤트

​오류 이벤트

​기타 이벤트

​델타 유형

​텍스트 델타

​입력 JSON 델타

​Raw HTTP 스트림 응답

​기본 스트리밍 요청

​도구 사용이 포함된 스트리밍 요청

SDK를 사용한 스트리밍

이벤트 유형

Ping 이벤트

오류 이벤트

기타 이벤트

델타 유형

텍스트 델타

입력 JSON 델타

Raw HTTP 스트림 응답

기본 스트리밍 요청

도구 사용이 포함된 스트리밍 요청