Tempo Limite Padrão da API Perplexity: Como Aumentá-lo

Quando você envia uma requisição para a API Perplexity, a conexão pode parar de esperar por uma resposta antes que a resposta seja totalmente gerada. Isso é chamado de timeout. O valor padrão de timeout costuma ser curto demais para consultas complexas que exigem pesquisa aprofundada ou grandes janelas de contexto. Este artigo explica por que os timeouts ocorrem e como aumentar a configuração de timeout no seu código.

Você aprenderá os valores padrão de timeout para a API Perplexity, o motivo técnico por trás das quedas de conexão e instruções passo a passo para estender o timeout em Python e outras linguagens. Também abordamos erros relacionados e erros comuns a evitar.

Por que os Timeouts da API Perplexity Ocorrem

A API Perplexity processa consultas usando modelos de linguagem grandes que realizam raciocínio em várias etapas e pesquisas na web. Consultas complexas que exigem análise extensa ou recuperação de muitas fontes podem levar mais tempo do que o timeout padrão para serem concluídas. O timeout padrão é definido pela biblioteca cliente da API ou pelo cliente HTTP usado no seu código.

A maioria dos endpoints da API Perplexity tem um timeout padrão de 30 segundos. No entanto, alguns SDKs, como a biblioteca Python da OpenAI (usada para chamar a Perplexity), podem ter o padrão de 10 segundos ou 60 segundos, dependendo da versão. Quando o servidor não retorna uma resposta dentro dessa janela, o cliente fecha a conexão e gera um erro de timeout.

O timeout não é um limite do lado do servidor. Os servidores da Perplexity continuam processando mesmo após o timeout do cliente. O timeout é puramente uma configuração do lado do cliente que controla quanto tempo sua aplicação espera pelo primeiro byte da resposta. Se você receber um erro de timeout, a resposta ainda pode estar sendo gerada no servidor, mas nunca é entregue ao seu cliente.

Mensagens de Erro de Timeout Comuns

A mensagem de erro exata depende da sua linguagem de programação e biblioteca HTTP. Em Python com a biblioteca requests, você vê requests.exceptions.ConnectTimeout ou requests.exceptions.ReadTimeout. Em Node.js com axios, você vê Error: timeout of 10000ms exceeded. No cliente Python da OpenAI, você vê openai.APITimeoutError.

Passos para Aumentar o Timeout da API Perplexity

Você pode aumentar o timeout de duas maneiras: definindo o parâmetro timeout na sua requisição HTTP ou configurando o objeto cliente globalmente. Abaixo estão os passos para os ambientes mais comuns.

Método 1: Aumentar o Timeout em Python Usando a Biblioteca requests

1. Importe a biblioteca requests
   Certifique-se de ter o módulo requests instalado. Caso contrário, execute pip install requests no terminal.
2. Defina o parâmetro timeout para um valor maior
   Na sua chamada de API, adicione o argumento timeout. Por exemplo, defina-o para 120 segundos: response = requests.post(url, headers=headers, json=data, timeout=120).
3. Trate a exceção de timeout
   Envolva a chamada em um bloco try-except para capturar requests.exceptions.Timeout e registre ou tente novamente a requisição.

Método 2: Aumentar o Timeout em Python Usando o Cliente OpenAI

A API Perplexity é compatível com a biblioteca Python da OpenAI. O timeout padrão no cliente OpenAI é de 60 segundos. Para aumentá-lo:

1. Instale ou atualize a biblioteca openai
   Execute pip install openai --upgrade.
2. Crie o cliente com um timeout personalizado
   Use o parâmetro timeout ao inicializar o cliente: client = OpenAI(api_key='YOUR_KEY', base_url='https://api.perplexity.ai', timeout=120.0).
3. Faça a chamada de API normalmente
   O cliente agora espera até 120 segundos por uma resposta. Exemplo: response = client.chat.completions.create(model='sonar-pro', messages=[{'role':'user','content':'Sua consulta'}]).

Método 3: Aumentar o Timeout em Node.js Usando Axios

1. Instale o axios
   Execute npm install axios no diretório do seu projeto.
2. Defina a opção timeout na configuração da requisição
   Passe um objeto de configuração com timeout definido em milissegundos: const response = await axios.post(url, data, { headers: headers, timeout: 120000 }). Isso define um timeout de 120 segundos.
3. Adicione tratamento de erro para timeout
   Verifique error.code === 'ECONNABORTED' para detectar erros de timeout especificamente.

Erros Comuns ao Ajustar o Timeout da API Perplexity

Definir Timeout no Objeto Errado

Ao usar o cliente OpenAI, o timeout deve ser definido no objeto cliente, não no método de requisição individual. Definir timeout dentro de client.chat.completions.create() é ignorado em algumas versões da biblioteca. Sempre defina no construtor.

Usar um Timeout Muito Baixo para Consultas Complexas

Consultas que exigem pesquisa na web, múltiplas fontes ou grandes janelas de contexto podem levar de 60 a 120 segundos. Se você definir o timeout para 30 segundos, essas consultas falharão consistentemente. Aumente o timeout para pelo menos 120 segundos em aplicações de produção.

Não Tratar Erros de Timeout de Forma Adequada

Um timeout não significa que a requisição falhou permanentemente. O servidor ainda pode estar processando. Implemente um mecanismo de repetição com backoff exponencial para reenviar a requisição após um pequeno atraso. Sem repetições, os usuários veem uma mensagem de erro para uma consulta que teria sido bem-sucedida se tivesse mais tempo.

Confundir Timeout do Cliente com Timeout do Servidor

O servidor da API Perplexity também tem timeouts internos para consultas muito longas. Se o timeout do seu cliente for de 300 segundos, mas o servidor expirar em 180 segundos, você ainda receberá um erro. A Perplexity não documenta publicamente o timeout do lado do servidor, mas geralmente é acima de 120 segundos para endpoints padrão. Se você receber erros consistentemente mesmo com um timeout alto no cliente, entre em contato com o suporte da Perplexity.

Comparação das Configurações de Timeout do Cliente da API Perplexity

Item	Biblioteca requests Python	Cliente Python OpenAI	Node.js Axios
Timeout padrão	Nenhum (espera indefinidamente)	60 segundos	Nenhum (espera indefinidamente)
Como definir timeout	timeout=120 na chamada da requisição	timeout=120.0 no construtor do cliente	timeout: 120000 no objeto de configuração
Unidade de timeout	Segundos	Segundos	Milissegundos
Tipo de erro	requests.exceptions.Timeout	openai.APITimeoutError	Error com código ECONNABORTED
Valor recomendado para Perplexity	120 segundos	120 segundos	120000 ms

Agora você pode ajustar o timeout no seu cliente da API Perplexity para corresponder à complexidade das suas consultas. Comece definindo o timeout para 120 segundos e monitore os logs da sua aplicação em busca de erros de timeout. Se ainda vir timeouts, aumente o valor para 180 segundos. Para uso avançado, combine o aumento do timeout com uma política de repetição usando a biblioteca tenacity em Python ou o pacote retry em Node.js.