Como Transmitir Respostas da API Perplexity com Server-Sent Events

Transmitir respostas da API Perplexity usando Server-Sent Events permite que seu aplicativo exiba respostas em tempo real conforme são geradas, em vez de esperar pela resposta completa. SSE é um protocolo padrão que envia dados do servidor para o cliente em uma única conexão HTTP. Este artigo explica como configurar sua requisição para ativar a transmissão e como lidar com o fluxo de eventos recebidos em JavaScript e Python. Você aprenderá os parâmetros exatos, tipos de evento e padrões de código necessários para uma implementação funcional.

Entendendo Server-Sent Events para a API Perplexity

Server-Sent Events é um padrão web que permite que um servidor envie dados para um cliente em uma conexão HTTP de longa duração. Ao contrário de WebSockets, SSE é unidirecional — o servidor envia dados apenas. A API Perplexity suporta SSE quando você define o parâmetro stream como true no corpo da requisição. Em vez de receber uma única resposta JSON, o servidor envia vários eventos, cada um contendo um fragmento do texto gerado. Essa abordagem reduz a latência percebida pelos usuários, pois eles veem a resposta aparecer palavra por palavra.

O fluxo SSE usa o tipo de conteúdo padrão text/event-stream. Cada evento tem um campo data e um campo opcional event. A Perplexity emite dois tipos de evento: text_chunk para cada pedaço de texto gerado e done para sinalizar o fim do fluxo. O campo data para eventos text_chunk contém um objeto JSON com a resposta parcial, enquanto o evento done inclui a resposta completa e metadados.

O Que Você Precisa Antes de Começar

Para transmitir respostas da API Perplexity, você precisa de uma chave de API válida do portal do desenvolvedor Perplexity. Você também precisa de um ambiente de desenvolvimento que possa fazer requisições HTTP e analisar fluxos SSE. Este guia cobre JavaScript no navegador e Python 3.7 ou superior. Nenhuma biblioteca adicional é necessária para a implementação básica, mas você pode usar o polyfill eventsource para navegadores antigos ou a biblioteca sseclient em Python por conveniência.

Passos para Ativar a Transmissão e Analisar Server-Sent Events

Os passos a seguir mostram como definir o parâmetro stream e lidar com os eventos recebidos em JavaScript e Python. Ambos os métodos seguem o mesmo fluxo lógico: abrir uma conexão, ouvir eventos, processar cada pedaço de texto e fechar o fluxo quando o evento done chegar.

Método 1: JavaScript no Navegador

1. Criar um objeto EventSource
   Use o construtor EventSource para conectar ao endpoint da API Perplexity. Passe a URL do endpoint da API e sua chave de API como um parâmetro de consulta ou defina o cabeçalho Authorization. O construtor EventSource não suporta cabeçalhos personalizados, então você deve incluir a chave de API na URL como um parâmetro de consulta se seu proxy de backend a encaminhar. Alternativamente, use a API fetch com um ReadableStream para controle total de cabeçalhos.
2. Ouvir o evento text_chunk
   Anexe um ouvinte de evento ao objeto EventSource para o evento text_chunk. Dentro do callback, analise a propriedade event.data como JSON. Extraia o campo text do objeto analisado e anexe-o ao elemento de exibição em sua interface. Cada evento contém um pequeno pedaço da resposta.
3. Ouvir o evento done
   Adicione um segundo ouvinte de evento para o evento done. Quando este evento for disparado, analise os dados JSON para recuperar a resposta completa e quaisquer metadados, como estatísticas de uso ou citações. Após o processamento, chame eventSource.close() para encerrar a conexão.
4. Lidar com erros
   Use o callback onerror no objeto EventSource para detectar falhas de conexão ou erros do servidor. A propriedade readyState indica o status da conexão. A lógica de reconexão pode ser implementada criando um novo EventSource após um atraso.

Método 2: Python com a Biblioteca Requests

1. Enviar uma requisição POST com streaming ativado
   Use o método requests.post com o parâmetro stream=True. Defina o cabeçalho Authorization como Bearer SUA_CHAVE_API. Inclua o campo stream: true no corpo JSON junto com o nome do modelo e o prompt.
2. Iterar sobre as linhas da resposta
   Use response.iter_lines() para processar cada linha do fluxo SSE. Cada linha que começa com data: contém um payload JSON. Pule linhas vazias ou que começam com event: se preferir analisar o tipo de evento a partir do campo data.
3. Analisar cada linha de dados
   Remova o prefixo data: e analise a string restante como JSON. Verifique o campo type do objeto analisado. Se o tipo for text_chunk, extraia o campo text e exiba ou imprima. Se o tipo for done, interrompa o loop e armazene a resposta final e os metadados.
4. Fechar a resposta
   Após o loop terminar, chame response.close() para liberar a conexão. Alternativamente, use um gerenciador de contexto com a declaração with para garantir que a resposta seja fechada automaticamente.

Problemas Comuns e Limitações ao Transmitir

EventSource Não Suporta Cabeçalhos Personalizados

A API EventSource do navegador não permite definir cabeçalhos HTTP personalizados, como Authorization. Para contornar isso, você deve fazer o proxy da requisição através do seu próprio servidor backend que adiciona a chave da API. Alternativamente, use a API fetch com um ReadableStream e analise o SSE manualmente. A abordagem fetch oferece controle total sobre cabeçalhos e corpo da requisição.

A Transmissão Para Antes da Resposta Estar Completa

Se a conexão cair ou o servidor expirar, o fluxo pode terminar prematuramente. Implemente lógica de reconexão que detecte o evento done ou o callback onerror. Em Python, capture requests.exceptions.ChunkedEncodingError e repita a requisição com o mesmo prompt. A API Perplexity não suporta retomar um fluxo parcial, então você deve reiniciar a requisição.

Eventos Chegam Fora de Ordem

Os eventos SSE são entregues na ordem em que o servidor os envia. Buffering de rede ou servidores proxy podem reordenar pacotes, mas o fluxo de eventos em si preserva a ordem. Se você observar texto fora de ordem, verifique se não está processando eventos de múltiplas conexões concorrentes. Cada fluxo é independente e sequencial.

Resposta com Streaming vs Sem Streaming da API Perplexity

Item	Streaming (SSE)	Sem Streaming
Entrega da resposta	Um evento por token ou pequeno bloco	Resposta JSON única após geração completa
Latência percebida	Baixa — o usuário vê o texto aparecer imediatamente	Maior — o usuário espera pela resposta completa
Duração da conexão	Aberta até que todos os eventos sejam enviados	Fechada após a resposta única
Tratamento de erros	Saída parcial pode ser perdida em caso de falha	Nenhuma saída parcial — repita a requisição inteira
Complexidade do cliente	Requer análise de eventos e lógica de reconexão	Simples — analisar um objeto JSON

Streaming é melhor para interfaces de chat e exibições em tempo real. Sem streaming é mais simples para processamento em lote ou agregação no lado do servidor onde a latência não é crítica.

Conclusão

Agora você pode transmitir respostas da API Perplexity usando Server-Sent Events definindo stream: true em sua requisição e analisando os eventos text_chunk e done. Em JavaScript, use a API EventSource ou fetch com um ReadableStream para controle total de cabeçalhos. Em Python, use a biblioteca requests com stream=True e itere sobre as linhas. Como próximo passo, implemente lógica de reconexão para lidar com interrupções de rede de forma elegante. Para uso avançado, combine streaming com o parâmetro citation para receber dados de citação no evento done.