Потоковая передача сообщений
При создании сообщения вы можете установить "stream": true
, чтобы постепенно передавать ответ с использованием событий, отправляемых сервером (SSE).
Потоковая передача с использованием SDK
Наши SDK для Python и Typescript предлагают несколько способов потоковой передачи. SDK для Python позволяет использовать как синхронные, так и асинхронные потоки. Подробности смотрите в документации к каждому SDK.
Типы событий
Каждое событие, отправляемое сервером, включает именованный тип события и связанные с ним данные JSON. Каждое событие будет использовать имя события SSE (например, event: message_stop
) и включать соответствующий тип события type
в своих данных.
Каждый поток использует следующий поток событий:
message_start
: содержит объектMessage
с пустымcontent
.- Серия блоков контента, каждый из которых имеет события
content_block_start
, одно или несколько событийcontent_block_delta
и событиеcontent_block_stop
. Каждый блок контента будет иметьindex
, соответствующий его индексу в конечном массивеcontent
сообщения. - Одно или несколько событий
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
содержит delta
определенного типа, которая обновляет блок content
с заданным index
.
Текстовая дельта
Дельта контентного блока 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
всегда является объектом.
Вы можете накапливать строковые дельты и разбирать JSON после получения события content_block_stop
, используя библиотеку вроде Pydantic для частичного разбора JSON, или используя наши SDK, которые предоставляют вспомогательные функции для доступа к разобранным инкрементным значениям.
Дельта контентного блока tool_use
выглядит так:
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"}