메시지 스트리밍
메시지를 생성할 때 "stream": true
를 설정하여 server-sent events (SSE)를 사용해 응답을 점진적으로 스트리밍할 수 있습니다.
SDK를 사용한 스트리밍
Python과 Typescript SDK는 다양한 방식의 스트리밍을 제공합니다. Python SDK는 동기 및 비동기 스트림을 모두 허용합니다. 자세한 내용은 각 SDK의 문서를 참조하세요.
이벤트 유형
각 server-sent 이벤트에는 명명된 이벤트 유형과 관련 JSON 데이터가 포함됩니다. 각 이벤트는 SSE 이벤트 이름(예: event: message_stop
)을 사용하고 데이터에 일치하는 이벤트 type
을 포함합니다.
각 스트림은 다음과 같은 이벤트 흐름을 사용합니다:
message_start
: 빈content
를 가진Message
객체를 포함합니다.- 일련의 콘텐츠 블록으로, 각각
content_block_start
, 하나 이상의content_block_delta
이벤트, 그리고content_block_stop
이벤트를 가집니다. 각 콘텐츠 블록은 최종 Messagecontent
배열에서의 인덱스에 해당하는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는 다음과 같습니다:
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
은 항상 _객체_입니다.
Pydantic과 같은 라이브러리를 사용하여 부분 JSON 파싱을 수행하거나 SDK에서 제공하는 도우미를 사용하여 파싱된 증분 값에 액세스함으로써 문자열 delta를 누적하고 content_block_stop
이벤트를 받으면 JSON을 파싱할 수 있습니다.
tool_use
콘텐츠 블록 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
이벤트가 분산되어 있을 수 있습니다. 형식에 대한 자세한 내용은 이벤트 유형을 참조하세요.
기본 스트리밍 요청
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-20240620",
"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-20240620", "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-20240620",
"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"}