Como Usar a API do Perplexity com o SDK Python da OpenAI

Você quer chamar a API do Perplexity a partir do código Python, mas prefere usar o familiar SDK da OpenAI em vez de uma biblioteca separada. A API do Perplexity é totalmente compatível com o cliente OpenAI porque usa o mesmo formato de endpoint de chat completions. Este artigo explica como configurar o SDK Python da OpenAI para conectar-se ao Perplexity, enviar consultas e lidar com as respostas. Você aprenderá a URL do endpoint necessária, o método de autenticação e os parâmetros do modelo para alternar entre OpenAI e Perplexity com o mínimo de alterações no código.

O que é a API do Perplexity e por que usar o SDK da OpenAI

A API do Perplexity fornece acesso a modelos de linguagem de grande escala hospedados pela Perplexity, incluindo modelos Sonar otimizados para busca em tempo real e raciocínio. A API foi projetada como um substituto direto para o endpoint de chat completions da OpenAI. Isso significa que você pode usar o mesmo código Python que chama o GPT-4 para chamar modelos Perplexity, alterando apenas a URL do endpoint e a chave da API.

Usar o SDK da OpenAI tem várias vantagens. Você evita instalar uma biblioteca separada do Perplexity. Você reutiliza código existente, padrões de autenticação e tratamento de erros que já possui para a OpenAI. O SDK lida com streaming, contagem de tokens e novas tentativas de forma uniforme. O Perplexity suporta a mesma estrutura de requisição e resposta que a OpenAI, então mensagens, papéis e parâmetros como temperature e max_tokens funcionam de forma idêntica.

Antes de começar, você precisa de uma chave da API do Perplexity. Faça login na sua conta Perplexity, vá para a seção de chaves de API nas configurações da conta e crie uma nova chave. Copie a chave e mantenha-a segura. Você também precisa do Python 3.8 ou superior e do pacote openai instalado. Instale-o com pip install openai se ainda não o fez.

Passos para configurar o SDK da OpenAI para a API do Perplexity

A configuração requer duas alterações na inicialização do cliente OpenAI: o base_url e o api_key. Todo o resto segue o padrão padrão de chat completion da OpenAI.

1. Instale ou atualize o pacote openai
   Execute pip install –upgrade openai no seu terminal para garantir que você tenha a versão 1.0 ou posterior. Versões anteriores a 1.0 usam uma API de cliente diferente que é incompatível com este guia.
2. Importe a classe OpenAI
   Adicione from openai import OpenAI no topo do seu script Python. Isso importa a classe de cliente moderna.
3. Crie o cliente com o endpoint do Perplexity
   Inicialize o cliente assim: client = OpenAI(api_key=’sua-chave-da-api-perplexity’, base_url=’https://api.perplexity.ai’). Substitua a string api_key pela sua chave real. O base_url deve apontar para a raiz da API do Perplexity.
4. Envie uma requisição de chat completion
   Chame client.chat.completions.create com o parâmetro model definido como um nome de modelo Perplexity, como sonar-pro. Passe a lista de messages como faria para a OpenAI. Por exemplo: response = client.chat.completions.create(model=’sonar-pro’, messages=[{‘role’: ‘user’, ‘content’: ‘Explique computação quântica em uma frase’}]).
5. Extraia a resposta
   Leia o conteúdo da resposta usando response.choices[0].message.content. Imprima ou retorne esta string para ver a saída do modelo.

O script mínimo completo é assim:

from openai import OpenAI

client = OpenAI(
    api_key="pplx-sua-chave-aqui",
    base_url="https://api.perplexity.ai"
)

response = client.chat.completions.create(
    model="sonar-pro",
    messages=[
        {"role": "user", "content": "Qual é a capital da França?"}
    ]
)

print(response.choices[0].message.content)

Substitua pplx-sua-chave-aqui pela sua chave real da API do Perplexity. O modelo sonar-pro é o modelo principal do Perplexity. Outros modelos disponíveis incluem sonar-small-chat, sonar-medium-chat e sonar-small-online. Verifique a documentação da API do Perplexity para a lista mais recente.

Streaming de Respostas

Para fazer streaming da resposta token por token, adicione stream=True à chamada create. Em seguida, itere sobre o objeto de resposta:

stream = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "Conte uma piada"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

O streaming funciona de forma idêntica à API de streaming da OpenAI. Cada chunk contém um objeto delta com o conteúdo incremental.

Enviando Mensagens de Sistema

O Perplexity suporta mensagens de sistema para definir o comportamento do assistente. Adicione uma mensagem de sistema no início do array de mensagens:

messages = [
    {"role": "system", "content": "Você é um assistente prestativo que responde em rimas."},
    {"role": "user", "content": "Qual é a velocidade da luz?"}
]

O modelo seguirá a instrução do sistema. Isso é útil para definir tom, formato ou regras específicas de domínio.

Erros Comuns e Coisas a Evitar

Usar a Base URL Errada

A base URL deve ser exatamente https://api.perplexity.ai sem um caminho adicional como /v1. O SDK da OpenAI anexa /chat/completions automaticamente. Se você definir base_url como https://api.perplexity.ai/v1, o SDK enviará requisições para https://api.perplexity.ai/v1/chat/completions, o que está incorreto. Sempre use a URL raiz.

Passar uma Chave da API da OpenAI

O parâmetro api_key deve ser uma chave da API do Perplexity, não uma chave da OpenAI. As chaves do Perplexity começam com pplx-. Se você usar uma chave da OpenAI, o servidor do Perplexity retornará um erro de autenticação 401. Verifique o prefixo da chave e regenere-a no painel do Perplexity, se necessário.

Usar Versões Desatualizadas do Cliente OpenAI

A versão 0.x do pacote openai usa uma classe de cliente diferente chamada openai.ChatCompletion. Essa classe não aceita base_url ou api_key como parâmetros de inicialização. Atualize para a versão 1.0 ou posterior com pip install –upgrade openai. A classe de cliente moderna é OpenAI.

Erros de Digitação no Nome do Modelo

Os nomes dos modelos do Perplexity diferenciam maiúsculas de minúsculas e devem corresponder exatamente. Erros comuns incluem usar underscores em vez de hífens ou escrever sonar incorretamente. Verifique o nome exato do modelo na documentação da API do Perplexity. Um nome de modelo inválido retorna um erro 404 com a mensagem Model not found.

Ignorar Limites de Taxa

O Perplexity impõe limites de taxa com base no seu plano de assinatura. Contas do nível gratuito têm limites mais baixos. Se você receber um erro 429 Too Many Requests, implemente backoff exponencial no seu código. O SDK da OpenAI não lida automaticamente com os limites de taxa do Perplexity.

Item	SDK OpenAI + Perplexity	SDK Nativo do Perplexity
Instalação	pip install openai	pip install perplexity-ai
Inicialização do cliente	OpenAI(api_key, base_url)	Perplexity(api_key)
Formato da requisição	Chat completions padrão da OpenAI	Métodos específicos do Perplexity
Suporte a streaming	Sim, igual à OpenAI	Sim, sintaxe diferente
Seleção de modelo	Parâmetro model como string	Parâmetro model como string
Tratamento de erros	Classes de exceção da OpenAI	Classes de exceção do Perplexity
Reutilização de código com OpenAI	Reutilização total, altere apenas base_url e api_key	Sem reutilização, reescreva todas as chamadas

Usar o SDK da OpenAI com o Perplexity oferece a vantagem de portabilidade de código. Você pode alternar entre provedores alterando duas linhas. O SDK nativo do Perplexity oferece recursos adicionais como integração de busca embutida, mas o SDK da OpenAI cobre completamente a funcionalidade principal de chat.

Agora você pode chamar a API do Perplexity a partir do Python usando o SDK da OpenAI com configuração mínima. Comece copiando o código de inicialização deste artigo e substituindo a chave da API e o nome do modelo. Teste com uma consulta simples antes de construir aplicações mais complexas. Para uso em produção, armazene a chave da API em uma variável de ambiente em vez de codificá-la no script. Use os.environ.get(‘PERPLEXITY_API_KEY’) para ler a chave de forma segura e mantê-la fora do controle de versão.