BroadRouter
Começar

Server-sent events (SSE)

Atualizado em

Server-sent events (SSE) é um padrão web para um servidor enviar a um cliente um fluxo de eventos de texto por uma única resposta HTTP de longa duração, com content type text/event-stream. Cada evento tem uma ou mais linhas de campo, como data:, e termina com uma linha em branco.

Também chamado de: SSE, server-sent events, eventos enviados pelo servidor, streaming SSE, text/event-stream, event stream, EventSource

SSE é o enquadramento em texto puro por trás de quase toda resposta de LLM em streaming. Conhecer o formato ajuda quando não há um SDK disponível ou quando um stream se comporta mal.

Como funciona

O padrão HTML do WHATWG define o formato. A resposta tem tipo MIME text/event-stream e é sempre UTF-8. O corpo é formado por linhas campo: valor:

: keep-alive comment, ignored by clients

event: update
id: 42
data: first line
data: second line

data: {"choices":[{"delta":{"content":"Hi"}}]}

data: [DONE]

As regras de parsing que importam:

  • Uma linha em branco despacha o evento. Até ela chegar, o cliente acumula em buffer.
  • Várias linhas data: se juntam com quebras de linha em uma só mensagem.
  • Uma linha que começa com dois-pontos é um comentário. Os servidores enviam esses comentários para manter abertas as conexões ociosas.
  • Um espaço depois dos dois-pontos é removido. As linhas podem terminar em CRLF, LF ou CR.
  • event, id e retry definem o tipo do evento, o ID do último evento e o atraso de reconexão em milissegundos.

As leituras da rede não coincidem com os eventos. Uma leitura pode trazer meio evento ou três, então o parser precisa acumular bytes e dividir nas linhas em branco, não nas leituras.

Reconexão, proxies e [DONE]

O padrão traz um mecanismo de recuperação para navegadores: depois de uma queda, o EventSource reconecta e envia um header Last-Event-ID, e o servidor pode interromper as tentativas com HTTP 204. A especificação também avisa que “legacy proxy servers” (servidores proxy legados) podem derrubar conexões HTTP após um timeout curto, e sugere uma linha de comentário “every 15 seconds or so” (a cada 15 segundos, mais ou menos).

As APIs de LLM usam menos disso. O stream da Chat Completions da OpenAI envia só linhas data: e termina com data: [DONE], uma convenção da API, não do SSE. Não há ID de evento a partir do qual retomar, então um stream interrompido não pode ser continuado; uma nova tentativa é uma nova requisição. O panorama geral do streaming e o ganho no time to first token estão naquela página.

Na BroadNet Inference

A documentação da BroadNet diz para definir stream=true e “read Server-Sent Events until the literal data: [DONE] marker” (tradução: ler os Server-Sent Events até o marcador literal data: [DONE]). Se a conexão terminar antes disso, trate a resposta como incompleta, registre o header X-Request-ID e decida se é seguro fazer uma nova requisição de inferência. Com stream_options: {"include_usage": true}, o usage chega no último chunk. O exemplo de curl da documentação usa -N para o curl não fazer buffer. Um stream também ocupa uma vaga de concorrência até terminar: 4 em uma chave de pagamento por uso, uma em uma chave por hora. A documentação pede que você verifique o streaming de cada modelo antes de ir para produção. O código para cada SDK está no guia de streaming, e o conteúdo dos chunks é explicado em Streaming de LLM explicado.

Perguntas frequentes

Posso usar a API EventSource do navegador com uma API de LLM?

Em geral, não diretamente. O construtor EventSource da especificação recebe só uma URL e uma flag withCredentials, então não consegue enviar um corpo POST nem um header Authorization. Use fetch e faça o parsing do stream você mesmo, ou use um SDK.

O que significa "data: [DONE]"?

Não faz parte do padrão SSE. APIs no estilo da OpenAI enviam a linha literal "data: [DONE]" como último evento para indicar que a resposta está completa.

Por que meu stream chega todo de uma vez?

Algo entre o servidor e o seu código está fazendo buffer da resposta, como um reverse proxy, um framework ou o curl sem -N. Desative o buffering nessa rota.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity