Como Migrar da API OpenAI para o Perplexity Sonar

Se você usa a API OpenAI para geração de texto ou conclusões aumentadas por busca, pode migrar para o Perplexity Sonar para menor custo, fundamentação web integrada e citações em tempo real. A API OpenAI e o Perplexity Sonar suportam um endpoint de chat completions, mas o formato da requisição, autenticação e estrutura da resposta diferem em vários aspectos. Este artigo explica as mudanças exatas que você precisa fazer no seu código, as diferenças nas capacidades dos modelos e as armadilhas comuns a evitar durante a migração.

Diferenças Entre a API OpenAI e a API Perplexity Sonar

A API Perplexity Sonar foi projetada para ser compatível com o formato de chat completions da OpenAI, mas existem várias diferenças. A diferença mais importante é que o Perplexity Sonar pesquisa automaticamente a web para cada requisição e retorna citações na resposta. Isso significa que você não precisa implementar um pipeline separado de geração aumentada por recuperação. A API também suporta um parâmetro return_citations e um parâmetro search_domain_filter para restringir quais fontes são usadas. O modelo de precificação é por requisição de pesquisa, em vez de por token, o que pode reduzir custos para aplicações que exigem consultas frequentes.

Diferenças no Formato da Requisição

Ambas as APIs usam um payload JSON com campos messages e model. No entanto, o Perplexity Sonar não suporta o parâmetro stream para respostas em streaming da mesma forma. Também não suporta o parâmetro temperature para todos os modelos. Você deve verificar a documentação específica do modelo para parâmetros suportados.

Mudanças na Estrutura da Resposta

A resposta da OpenAI inclui um array choices com um objeto message. O Perplexity Sonar retorna a mesma estrutura, mas adiciona um array citations dentro de cada choice. Cada citação contém um url, title e um trecho text. Se você antes analisava apenas o campo content, deve atualizar seu código para opcionalmente ler as citações.

Passos para Atualizar Seu Código para o Perplexity Sonar

Siga estes passos para modificar um cliente existente da API OpenAI para funcionar com o Perplexity Sonar. Os exemplos usam Python com a biblioteca requests, mas a mesma lógica se aplica a qualquer linguagem de programação.

1. Altere a URL do endpoint da API
   Substitua a URL base da OpenAI pelo endpoint do Perplexity. Use https://api.perplexity.ai/chat/completions para todas as requisições.
2. Atualize o cabeçalho de autenticação
   Substitua sua chave de API OpenAI por uma chave de API Perplexity. Defina o cabeçalho como Authorization: Bearer pplx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. Obtenha sua chave no painel da API Perplexity.
3. Defina o nome correto do modelo
   Altere o campo model para um dos seguintes: sonar-pro para geração aumentada por busca padrão, sonar-reasoning-pro para raciocínio mais profundo com citações, ou sonar-deep-research para consultas de pesquisa em várias etapas. Para testes, você pode usar sonar ou sonar-reasoning.
4. Remova parâmetros não suportados
   Verifique seu payload existente para parâmetros como temperature, top_p, frequency_penalty, presence_penalty, logit_bias ou user. Remova qualquer um que não esteja listado na documentação da API Perplexity. Se você mantiver parâmetros não suportados, a API os ignorará ou retornará um erro.
5. Adicione parâmetros de pesquisa opcionais
   Para controlar o comportamento da pesquisa, adicione o parâmetro search_domain_filter com um array de domínios, como ["wikipedia.org"]. Para forçar uma pesquisa nova e ignorar resultados em cache, defina search_recency_filter como "month" ou "week".
6. Analise as citações da resposta
   Após receber a resposta, extraia o array citations de response["choices"][0]. Itere sobre as citações para exibir URLs e trechos junto com o texto gerado. Se sua aplicação usava uma API de busca separada, agora você pode remover essa chamada.

Exemplo de Código Python

Aqui está um exemplo mínimo que envia uma consulta para o Perplexity Sonar e imprime a resposta com citações:

import requests

url = "https://api.perplexity.ai/chat/completions"
headers = {
    "Authorization": "Bearer SUA_CHAVE_API_PERPLEXITY",
    "Content-Type": "application/json"
}
payload = {
    "model": "sonar-pro",
    "messages": [
        {"role": "system", "content": "Você é um assistente útil."},
        {"role": "user", "content": "Qual é a capital da França?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
answer = data["choices"][0]["message"]["content"]
citations = data["choices"][0].get("citations", [])
print(answer)
for citation in citations:
    print(citation["url"])

Erros Comuns ao Migrar para o Perplexity Sonar

Vários problemas surgem quando desenvolvedores mudam da OpenAI para o Perplexity sem ajustar suas suposições. Os problemas a seguir são os mais frequentes.

Usar o Nome Errado do Modelo

A API OpenAI usa nomes de modelo como gpt-4 ou gpt-3.5-turbo. O Perplexity Sonar usa identificadores de modelo diferentes. Se você mantiver o nome antigo do modelo, a API retornará um erro 404. Sempre defina o modelo como sonar-pro ou sonar-reasoning-pro para produção.

Esquecer de Lidar com o Campo de Citações

Se sua aplicação espera que a resposta contenha apenas a string content e ignora o campo citations, você perde os links das fontes. Atualize seu analisador de resposta para verificar a presença de citations e exibi-los se disponíveis. Se você não precisa de citações, ainda pode ignorar o campo, mas perde um dos principais benefícios do Perplexity Sonar.

Limites de Taxa e Cotas Diferem

Os limites de taxa do Perplexity Sonar são baseados em requisições por minuto, não em tokens por minuto. Se sua aplicação envia muitas requisições pequenas, você pode atingir o limite mais rápido do que com a OpenAI. Verifique a documentação da API para os limites específicos do seu plano e implemente backoff exponencial na sua lógica de repetição.

Prompts de Sistema se Comportam Diferentemente

A mensagem system no Perplexity Sonar é respeitada, mas o modelo pode sobrescrever as instruções do sistema com resultados de pesquisa web. Se você precisa de adesão estrita a um prompt de sistema, teste seu prompt com o modelo Sonar específico que planeja usar. Alguns modelos, como sonar-reasoning-pro, podem priorizar o raciocínio em vez da adesão estrita a instruções.

Item	API OpenAI	API Perplexity Sonar
Endpoint	api.openai.com/v1/chat/completions	api.perplexity.ai/chat/completions
Autenticação	Bearer sk-…	Bearer pplx-…
Modelo padrão	gpt-4o	sonar-pro
Pesquisa web integrada	Não (requer plugin ou ferramenta)	Sim (automática)
Citações na resposta	Não incluídas	Incluídas no array citations
Suporte a streaming	Streaming SSE completo	Limitado (verifique docs do modelo)
Base de precificação	Por token	Por requisição (pesquisa)

Migrar da API OpenAI para o Perplexity Sonar exige atualizar sua URL de endpoint, cabeçalho de autenticação, nome do modelo e analisador de resposta. A mudança mais significativa é a adição de pesquisa web automática e citações. Teste sua integração com uma única consulta antes de implantar em produção. Para casos de uso avançados, explore os parâmetros search_domain_filter e search_recency_filter para refinar o comportamento da pesquisa. Se encontrar comportamento inesperado, verifique o changelog da API Perplexity para atualizações nas capacidades do modelo.