Streaming Tokens — Server-Sent Events for Real-Time LLM Output | tutorialQ
Streaming de tokens em tempo real: por que o Server-Sent Events virou o padrão dos apps de IA
Quem já usou um chatbot baseado em LLM antes da era do streaming conhece bem a sensação: você envia a pergunta, o cursor pisca, o botão de enviar fica desabilitado e a tela permanece vazia por 5, 10, às vezes 30 segundos. Só então o texto inteiro aparece de uma vez, como se tivesse sido colado de um lugar qualquer. A resposta pode até ser excelente, mas a experiência parece quebrada — porque, do ponto de vista da percepção humana, ela é.
O contraste com as interfaces modernas de IA é brutal. Nas melhores aplicações, a primeira palavra aparece em poucas centenas de milissegundos e o texto flui na tela como se alguém estivesse digitando do outro lado. Nada mudou na velocidade do modelo em si: o que mudou foi a forma de transportar a resposta. E a tecnologia que se consolidou como padrão para esse transporte tem nome: Server-Sent Events (SSE).
O problema real não é latência, é latência percebida
É tentador resumir a discussão a “o modelo é lento”. Mas o tempo total de geração de uma resposta raramente é o gargalo principal da experiência. O que domina a percepção do usuário é o tempo até o primeiro token (TTFT, na sigla em inglês) e a sensação de progresso contínuo.
Em uma requisição HTTP tradicional no padrão request/response, o cliente manda a requisição, o servidor segura a conexão enquanto o modelo gera todos os tokens, monta a resposta completa e só então envia tudo de volta. O navegador fica com a requisição pendente e a interface, congelada. Se a geração leva 20 segundos, são 20 segundos de tela morta.
Com streaming, o mesmo modelo pode levar os mesmos 20 segundos para concluir — mas o primeiro fragmento de texto chega ao usuário em menos de um segundo, e cada token subsequente mantém a percepção de movimento. A aplicação deixa de parecer travada e passa a parecer rápida, mesmo com a mesma carga no servidor.
Anatomia do Server-Sent Events
SSE é um mecanismo simples e elegante: uma conexão HTTP de longa duração em que o servidor mantém o canal aberto e envia eventos de texto ao cliente sempre que tiver algo novo. Não há handshake de upgrade, não há framing binário, não há negociação de subprotocolos. É HTTP puro, com um único detalhe decisivo no cabeçalho de resposta:
Content-Type: text/event-stream
A partir daí, o corpo da resposta é um fluxo de eventos em formato de texto delimitado por linhas. Cada evento é composto por campos opcionais:
data:— o conteúdo do evento, que no caso de uma LLM é o fragmento de texto gerado (o delta);event:— o tipo/nome do evento, útil para separar, por exemplo, tokens de mensagens de controle como “fim da geração”;id:— um identificador do evento, usado na reconexão;retry:— o intervalo, em milissegundos, que o cliente deve esperar antes de tentar reconectar.
Um trecho típico de stream durante a geração de uma frase se parece com isto:
event: token
data: {"delta":"Olá"}
event: token
data: {"delta":", como"}
event: done
data: {"finish_reason":"stop"}
O navegador expõe essa API de forma nativa por meio do objeto EventSource, que reconecta automaticamente em caso de queda e dispara callbacks para cada mensagem recebida. Do lado do servidor, o contrato é igualmente enxuto: manter o socket aberto, escrever os eventos, dar flush a cada token e encerrar quando o modelo terminar.
Por que SSE e não WebSockets?
A pergunta é quase inevitável para quem já construiu aplicações em tempo real. WebSockets oferecem comunicação bidirecional e menor overhead por mensagem — parecem, à primeira vista, a escolha “mais poderosa”. Na prática, para streaming de LLM, essa potência é desnecessária e cobra um preço.
- Direção do fluxo: em uma geração de texto, o cliente envia um prompt e o servidor devolve uma sequência de tokens. É um fluxo essencialmente unidirecional depois do primeiro envio. SSE foi desenhado exatamente para isso.
- Simplicidade operacional: WebSockets exigem servidores com estado, transporte dedicado, bibliotecas específicas e cuidados extras com balanceamento de carga. SSE roda sobre HTTP comum e, em boa medida, reaproveita a infraestrutura que já existe.
- Reconexão nativa: o navegador reconecta sozinho em SSE e ainda pode reenviar o último
idrecebido via cabeçalhoLast-Event-ID, permitindo retomar o fluxo. Em WebSockets, toda a lógica de reconexão e retomada é responsabilidade sua. - Proxy e firewall: WebSockets podem ser bloqueados ou mal suportados em ambientes corporativos com proxies intermediários. HTTP puro costuma passar onde o upgrade falha.
- HTTP/2 e HTTP/3: nesses protocolos, várias requisições multiplexadas compartilham uma única conexão TCP, o que elimina uma das críticas históricas ao SSE sob HTTP/1.1 — o limite de conexões simultâneas por domínio.
Isso não significa que WebSockets estejam fora de cena. Para voz em tempo real, colaboração multiusuário no mesmo documento ou controle bidirecional contínuo, eles continuam sendo a ferramenta certa. Mas para “o modelo está escrevendo e eu quero ver as palavras aparecendo”, SSE entrega o melhor custo-benefício.
Como as APIs de LLM expõem o streaming
A maioria dos provedores de modelos — OpenAI, Anthropic, Google e alternativas open source servidas por vLLM, Ollama ou TGI — oferece um parâmetro do tipo stream: true. Quando ativado, a resposta deixa de ser um JSON único e passa a ser um fluxo de eventos SSE, cada um contendo um pequeno fragmento de conteúdo sob campos como delta ou choices[0].delta.content.
Há uma sutileza importante aqui: essas chamadas são feitas por POST, com corpo JSON contendo o prompt. E o EventSource do navegador só suporta GET. Na prática, isso significa que existem dois padrões de arquitetura:
- Consumir o stream no back-end e repassá-lo ao front-end. O servidor faz a chamada com streaming para o provedor, lê o fluxo e reemite os eventos para o navegador. É a abordagem mais comum, porque permite esconder a chave de API, aplicar autenticação, filtrar conteúdo, registrar métricas e controlar custos.
- Consumir o stream diretamente no navegador usando
fetch()comReadableStreame um parser manual do formato SSE. Isso funciona com POST e é o caminho adotado por várias aplicações que falam direto com o provedor — ao custo de expor credenciais e perder a reconexão automática.
O lado do cliente: além do EventSource
Quando o navegador usa EventSource, ganha reconexão automática e simplicidade, mas fica preso ao GET e à impossibilidade de cancelar de forma limpa. Quando usa fetch() com streams, ganha controle total: pode enviar POST, adicionar cabeçalhos de autorização e abortar a requisição com AbortController — recurso essencial para o botão “parar de gerar”, que os usuários esperam encontrar.
Do lado da renderização, há detalhes que separam uma demo de um produto:
- Markdown incremental: aplicar o parser a cada token é caro e pode causar “pulos” visuais quando um bloco de código começa e ainda não terminou. Estratégias de renderização em lotes pequenos (a cada 30–60 ms) suavizam o resultado.
- Preservação de scroll: em respostas longas, o auto-scroll precisa respeitar a posição do usuário. Se ele rolou para cima, forçar o retorno ao fim da mensagem é hostil.
- Cursor de digitação: um indicador visual pulsante reduz a ambiguidade entre “ainda está gerando” e “acabou”.
- Acessibilidade: atualizações muito frequentes em regiões live de leitores de tela geram ruído. O ideal é anunciar em blocos ou apenas ao final.
As armadilhas de infraestrutura que quebram o streaming
Aqui está a parte em que muitos projetos falham mesmo com o código aparentemente correto. Streaming é sensível a qualquer camada intermediária que acumule bytes antes de repassá-los — e a internet corporativa está cheia delas.
- Buffering em proxies reversos: o Nginx, por padrão, tende a bufferizar respostas. Sem
proxy_buffering off, o texto chega em blocos grandes e o efeito “digitando” desaparece. - Compressão agressiva: compressão pode segurar dados esperando um bloco maior antes de enviar. Para
text/event-stream, o comum é desativá-la ou ajustar os parâmetros. - CDNs e gateways de API: alguns produtos de borda acumulam respostas para cachear ou inspecionar conteúdo. É preciso configurar explicitamente rotas de streaming como não bufferizadas.
- Timeouts de load balancer: conexões ociosas podem ser cortadas por idle timeout. Enviar comentários periódicos no stream (
: keep-alive) mantém a conexão viva em fluxos com pausas longas. - Limite de conexões por domínio: sob HTTP/1.1, o navegador limita conexões simultâneas ao mesmo host. Vários streams abertos podem esgotar esse orçamento — outra razão para priorizar HTTP/2.
Resiliência, retomada e custo de escala
SSE herda uma vantagem poderosa do HTTP: reconexão. Como cada evento pode carregar um id, o cliente que cai e volta pode informar ao servidor qual foi o último evento recebido. Isso permite implementar retomada — desde que o back-end guarde um buffer dos tokens já emitidos por um curto período, algo especialmente útil em redes móveis instáveis.
Do ponto de vista de escala, o ponto de atenção é que cada usuário gera uma conexão de longa duração, e não uma requisição curta. Isso muda o perfil de consumo de recursos: o gargalo deixa de ser CPU por requisição e passa a ser número de conexões abertas simultâneas, memória por conexão e tempo médio de vida do stream. Aplicações com muitas sessões concorrentes precisam ajustar limites de arquivos abertos, escolher servidores assíncronos (Node, Go, Python com ASGI) e evitar arquiteturas que amarrem uma thread por conexão.
Além disso, vale lembrar que o streaming não elimina o custo de inferência — ele apenas o distribui no tempo. Se o provedor cobra por token gerado, o total permanece o mesmo; o que muda é a capacidade de cancelar gerações longas quando o usuário já obteve o que precisava, o que pode gerar economia real.
Segurança e observabilidade
Dois pontos merecem atenção especial. O primeiro é a autenticação: como o EventSource não permite cabeçalhos customizados, muita gente acaba passando tokens na query string — onde eles vazam para logs de servidor, proxies e histórico do navegador. A alternativa é usar cookies com SameSite adequado, restringir CORS com precisão e, quando necessário, emitir tokens efêmeros e de escopo limitado para o stream.
O segundo é a observabilidade. Métricas que importam para um app de streaming são diferentes das de uma API tradicional: tempo até o primeiro token, tokens por segundo, taxa de streams abortados pelo usuário, frequência de reconexões e distribuição de duração das sessões. Sem esses números, é impossível saber se uma lentidão percebida vem do modelo, da rede ou do seu back-end.
Quando o streaming não é a resposta
Nem tudo se beneficia de SSE. Se a saída do modelo alimenta outro processo automatizado — um pipeline de extração de dados, um classificador, um job em lote — não há humano esperando e o streaming só adiciona complexidade. Da mesma forma, respostas muito curtas, geradas em menos de um segundo, tendem a não justificar a engenharia extra. E em fluxos com áudio bidirecional ou interação multiturno de baixíssima latência, WebSockets ou WebRTC continuam sendo a escolha mais adequada.
Conclusão
O streaming de tokens deixou de ser um detalhe de experiência do usuário para se tornar expectativa básica em produtos de IA. A diferença entre uma interface que parece instantânea e outra que parece travada raramente está no modelo — está na forma como a resposta viaja até a tela.
O Server-Sent Events ganhou esse espaço porque resolve o problema com o mínimo de peças: HTTP comum, um formato de texto simples, reconexão nativa no navegador e compatibilidade ampla com a infraestrutura existente. Os desafios que restam não estão no protocolo, mas nos detalhes de implementação: desativar buffering em proxies, escolher entre EventSource e fetch com streams, tratar reconexão com retomada, permitir cancelamento e medir o que realmente importa — o tempo até o primeiro token.
Para quem está construindo aplicações com LLMs hoje, dominar SSE não é apenas uma decisão técnica pontual. É o que separa um produto que espera por 30 segundos em silêncio de um que conversa com o usuário desde a primeira palavra.