Mensagens de Streaming
Ao criar uma Mensagem, você pode definir "stream": true
para transmitir incrementalmente a resposta usando server-sent events (SSE).
Streaming com SDKs
Nossos SDKs Python e Typescript oferecem várias maneiras de streaming. O SDK Python permite streams síncronos e assíncronos. Consulte a documentação em cada SDK para obter detalhes.
Tipos de eventos
Cada evento enviado pelo servidor inclui um tipo de evento nomeado e dados JSON associados. Cada evento usará um nome de evento SSE (por exemplo, event: message_stop
) e incluirá o type
correspondente em seus dados.
Cada stream usa o seguinte fluxo de eventos:
message_start
: contém um objetoMessage
comcontent
vazio.- Uma série de blocos de conteúdo, cada um com um evento
content_block_start
, um ou mais eventoscontent_block_delta
e um eventocontent_block_stop
. Cada bloco de conteúdo terá umindex
que corresponde ao seu índice no arraycontent
final da Mensagem. - Um ou mais eventos
message_delta
, indicando alterações de nível superior no objetoMessage
final. - Um evento final
message_stop
.
Eventos de ping
Os streams de eventos também podem incluir qualquer número de eventos ping
.
Eventos de erro
Ocasionalmente, podemos enviar erros no stream de eventos. Por exemplo, durante períodos de alto uso, você pode receber um overloaded_error
, que normalmente corresponderia a um HTTP 529 em um contexto sem streaming:
event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Sobrecarregado"}}
Outros eventos
De acordo com nossa política de versão, podemos adicionar novos tipos de eventos e seu código deve lidar com tipos de eventos desconhecidos de maneira graciosa.
Tipos de delta
Cada evento content_block_delta
contém um delta
de um tipo que atualiza o bloco content
em um determinado index
.
Delta de texto
Um delta de bloco de conteúdo text
se parece com:
event: content_block_delta
data: {"type": "content_block_delta","index": 0,"delta": {"type": "text_delta", "text": "lá amig"}}
Delta de JSON de entrada
Os deltas para blocos de conteúdo tool_use
correspondem a atualizações para o campo input
do bloco. Para suportar a granularidade máxima, os deltas são strings JSON parciais, enquanto o tool_use.input
final é sempre um objeto.
Você pode acumular os deltas de string e analisar o JSON assim que receber um evento content_block_stop
, usando uma biblioteca como Pydantic para fazer a análise parcial de JSON, ou usando nossos SDKs, que fornecem auxiliares para acessar valores incrementais analisados.
Um delta de bloco de conteúdo tool_use
se parece com:
event: content_block_delta
data: {"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"São Fra"}}}
Nota: Nossos modelos atuais suportam apenas a emissão de uma propriedade completa de chave e valor de input
por vez. Assim, ao usar ferramentas, pode haver atrasos entre os eventos de streaming enquanto o modelo está trabalhando. Assim que uma chave e valor de input
são acumulados, nós os emitimos como vários eventos content_block_delta
com json parcial fragmentado para que o formato possa suportar automaticamente uma granularidade mais fina em modelos futuros.
Resposta de Stream HTTP bruto
Recomendamos fortemente que você use nossos SDKs de cliente ao usar o modo de streaming. No entanto, se você estiver criando uma integração direta de API, precisará lidar com esses eventos você mesmo.
Uma resposta de stream é composta por:
- Um evento
message_start
- Potencialmente vários blocos de conteúdo, cada um contendo:
a. Um evento
content_block_start
b. Potencialmente vários eventoscontent_block_delta
c. Um eventocontent_block_stop
- Um evento
message_delta
- Um evento
message_stop
Pode haver eventos ping
dispersos ao longo da resposta também. Consulte Tipos de eventos para obter mais detalhes sobre o formato.
Solicitação básica de streaming
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": "Olá"}],
"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": "Olá"}}
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"}
Solicitação de streaming com uso de ferramenta
Nesta solicitação, pedimos ao Claude para usar uma ferramenta para nos dizer o clima.
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": "Obter o clima atual em um determinado local",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "A cidade e o estado, por exemplo, São Francisco, CA"
}
},
"required": ["location"]
}
}
],
"tool_choice": {"type": "any"},
"messages": [
{
"role": "user",
"content": "Como está o clima em São 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":"Ok"}}
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":" vamos"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" verificar"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" o"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" clima"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" para"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" São"}}
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":" \"São"}}
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"}