Streaming da API Perplexity Interrompido Antes do Fim: Passos de Diagnóstico

Quando você usa a API Perplexity para respostas em streaming, a saída pode parar antes do modelo terminar de gerar uma resposta. Esse corte precoce interrompe fluxos de trabalho que dependem de respostas completas, como resumos automatizados de pesquisa ou chatbots voltados para o cliente. O problema geralmente decorre de configurações de timeout no lado do cliente, interrupções de rede ou parâmetros da API mal configurados. Este artigo explica as causas técnicas do término precoce do stream e fornece etapas de diagnóstico passo a passo para isolar e resolver o problema.

Por que o Stream da API Perplexity Para Antes do Fim

A API Perplexity usa eventos enviados pelo servidor (SSE) para transmitir tokens um a um. Quando o cliente para de receber tokens, a causa raiz é quase sempre uma de três coisas: o cliente atingiu o timeout, o servidor atingiu um limite de tokens ou um componente de rede fechou a conexão.

Timeout de Leitura no Lado do Cliente

A maioria das bibliotecas HTTP tem um timeout de leitura padrão de 30 a 60 segundos. Se a API levar mais tempo que isso para enviar todos os tokens, o cliente fecha a conexão e descarta os dados restantes. Respostas longas de modelos de linguagem grandes podem exceder esses padrões, especialmente com prompts complexos ou janelas de contexto grandes.

Parâmetro Max Tokens

O parâmetro max_tokens na requisição da API determina o número máximo de tokens que o modelo pode gerar. Se esse valor for definido muito baixo, o modelo para no meio da frase. O valor padrão em muitos SDKs é 256 ou 512 tokens, o que geralmente é insuficiente para respostas detalhadas.

Interrupções de Rede

Proxies corporativos, VPNs ou firewalls podem ter configurações de timeout ocioso que interrompem conexões persistentes. Streams SSE são conexões HTTP de longa duração. Se o proxy não vir dados por alguns segundos, ele pode encerrar a conexão, fazendo com que o cliente veja uma resposta truncada.

Etapas para Diagnosticar e Corrigir Cortes Precoces no Stream

Método 1: Aumentar o Timeout de Leitura do Cliente

1. Identifique sua biblioteca cliente HTTP
   Verifique se você usa Python requests, Node.js fetch, cURL ou outra ferramenta. O nome do parâmetro de timeout difere por biblioteca.
2. Defina um timeout de leitura maior
   Para Python requests, adicione timeout=(5, 120) para definir um timeout de conexão de 5 segundos e um timeout de leitura de 120 segundos. Para Node.js fetch, use AbortController com um sinal de 120 segundos.
3. Teste com um prompt simples
   Envie uma consulta curta como “Qual é a capital da França?” e verifique se o stream é concluído. Depois teste com um prompt que gere uma resposta longa, como “Explique a história da computação quântica em 500 palavras.”
4. Monitore o tempo decorrido
   Registre o horário em que o primeiro token chega e quando o último token chega. Se o corte ocorrer próximo ao limite de timeout, você confirmou a causa.

Método 2: Ajustar o Parâmetro Max Tokens

1. Localize o campo max_tokens no corpo da requisição
   Este é um campo JSON de nível superior. Se você estiver usando o SDK da Perplexity, verifique a assinatura do método para um argumento max_tokens.
2. Aumente o valor para 2048 ou mais
   Um valor de 4096 tokens cobre a maioria das respostas detalhadas. O máximo suportado pela Perplexity depende do modelo; verifique o limite max_output_tokens na documentação do modelo.
3. Envie uma requisição de teste com um prompt longo
   Use o mesmo prompt longo do método anterior. Verifique se o stream agora retorna uma resposta completa.
4. Verifique o objeto usage na resposta
   A API retorna um campo usage com completion_tokens. Compare isso com seu valor de max_tokens. Se forem iguais, o modelo atingiu o limite.

Método 3: Testar Sem Intermediários de Rede

1. Desative temporariamente VPN ou proxy
   Desconecte-se da VPN corporativa ou desative o software de proxy. Execute a chamada da API novamente a partir de uma conexão direta com a internet.
2. Use uma rede diferente
   Se não puder desativar o proxy, teste a partir de um hotspot pessoal ou de uma rede Wi-Fi diferente. Se o stream for concluído, o problema provavelmente é sua rede corporativa.
3. Verifique os logs do firewall
   Se tiver acesso, procure por conexões descartadas ou timeouts de sessão direcionados ao endpoint da API Perplexity (api.perplexity.ai e todos os subdomínios).
4. Ative cabeçalhos keep-alive
   Adicione Connection: keep-alive aos cabeçalhos da requisição HTTP. Isso informa aos intermediários para não fechar a conexão prematuramente.

Método 4: Verificar a Implementação do Stream

1. Inspecione os dados SSE brutos
   Registre cada chunk recebido. Cada chunk deve começar com data: seguido por um objeto JSON contendo um array choices. O chunk final tem [DONE] como valor de dados.
2. Verifique se há estouro de buffer no seu parser
   Se você estiver usando um parser SSE personalizado, certifique-se de que ele não descarte chunks quando o buffer encher. Use uma biblioteca bem testada como eventsource-parser para Python ou eventsource para Node.js.
3. Teste com cURL
   Execute curl -N https://api.perplexity.ai/chat/completions -H "Authorization: Bearer SUA_CHAVE_API" -H "Content-Type: application/json" -d '{"model":"sonar-pro","messages":[{"role":"user","content":"Conte uma longa história sobre IA."}],"stream":true}'. A flag -N desativa o buffer. Se o cURL mostrar o stream completo, o problema está no seu código cliente.

Se o Stream Ainda Parar Após o Diagnóstico

Stream Inicia mas Para Após Poucos Tokens

Isso indica um erro no lado do servidor que a API oculta no modo streaming. Verifique o código de status HTTP da resposta. Se for 400 ou 500, a API está rejeitando a requisição antes de gerar tokens. Causas comuns: nome de modelo inválido, array de mensagens mal formatado ou chave de API expirada. Consulte a documentação da API para o formato correto da requisição.

Stream Funciona em um Cliente mas Não em Outro

Compare as bibliotecas HTTP e versões entre os clientes que funcionam e os que não funcionam. Versões antigas do Python requests (abaixo de 2.25) têm problemas conhecidos com streaming. Atualize a biblioteca do cliente para a versão mais recente. Compare também os cabeçalhos da requisição, especialmente Accept e Cache-Control. O cliente que não funciona pode estar faltando Accept: text/event-stream.

Stream Para no Mesmo Ponto Sempre

Isso é um forte indicador de que o parâmetro max_tokens está muito baixo. O corte ocorre em uma contagem de tokens previsível. Aumente max_tokens para pelo menos 2048 e teste novamente. Se o corte se mover para uma contagem de tokens maior, você confirmou a causa.

Parâmetros da API Perplexity que Afetam o Comprimento do Stream

Parâmetro	Efeito no Stream	Valor Recomendado
max_tokens	Limita o total de tokens de saída	2048 a 4096 para respostas detalhadas
temperature	Valores mais altos podem produzir respostas mais longas devido a escolhas de tokens mais variadas	0.7 a 1.0
top_p	Amostragem nuclear; valores mais baixos restringem a seleção de tokens e podem encurtar a saída	0.9 a 1.0
stream	Deve ser definido como true para streaming	true

Ao ajustar max_tokens, verifique também se o modelo que você está usando suporta o número solicitado. Por exemplo, o modelo Sonar Pro suporta até 4096 tokens de saída, enquanto modelos mais antigos podem ter um limite de 2048.

Conclusão

Agora você pode diagnosticar cortes precoces no stream da API Perplexity verificando timeouts no lado do cliente, o parâmetro max_tokens e intermediários de rede. Comece aumentando o timeout de leitura para 120 segundos e definindo max_tokens para 2048 ou mais. Se o problema persistir, teste com cURL para isolar problemas no código do cliente. Para depuração avançada, ative o log detalhado no seu cliente HTTP para ver o ponto exato onde a conexão cai. Essa abordagem resolverá mais de 90% dos casos de corte precoce sem precisar entrar em contato com o suporte.