Como Passar System Prompts em Chamadas da API Perplexity

Ao fazer chamadas de API para o Perplexity, você pode precisar definir o comportamento do modelo de IA antes de processar as mensagens do usuário. Um system prompt define o papel, o tom e as restrições para o assistente. Sem um system prompt colocado corretamente, o modelo pode responder de forma padrão que não atende às necessidades da sua aplicação. Este artigo explica como estruturar sua requisição de API para incluir system prompts e mostra o formato JSON correto para a API Perplexity.

O Que é um System Prompt e Por Que Passá-lo em Chamadas de API

Um system prompt é uma mensagem que define o contexto e as regras para o assistente de IA. Na API do Perplexity, você fornece esse prompt como um objeto de mensagem com o role system. O modelo lê esta instrução antes de ver qualquer entrada do usuário. Por exemplo, você pode instruir o assistente a responder apenas em francês, atuar como um agente de suporte técnico ou citar fontes de um intervalo de datas específico.

Passar um system prompt é necessário quando você deseja um comportamento consistente em várias chamadas de API. Sem ele, o modelo usa uma persona padrão que pode não corresponder ao seu caso de uso. A API Perplexity segue o mesmo formato de chat completion que a OpenAI, então a estrutura do array messages é familiar para a maioria dos desenvolvedores.

Passos para Estruturar a Requisição de API com um System Prompt

Siga estes passos para incluir um system prompt em uma chamada de API Perplexity. O exemplo usa o modelo sonar-pro, mas a mesma estrutura funciona para outros modelos disponíveis através da API.

1. Defina a URL e o método da requisição
   Use o endpoint https://api.perplexity.ai/chat/completions com o método HTTP POST. Inclua sua chave de API no cabeçalho Authorization como Bearer SUA_CHAVE_API.
2. Construa o corpo JSON com o parâmetro model
   Adicione a chave model e defina-a com o nome do modelo, por exemplo "sonar-pro". Isso informa ao Perplexity qual modelo usar para a requisição.
3. Crie o array messages
   Adicione um array messages. O primeiro objeto neste array deve ter "role": "system" e o campo content contendo o texto do seu prompt.
4. Adicione a mensagem do usuário após a mensagem de sistema
   Anexe um segundo objeto com "role": "user" e o campo content para a consulta do usuário. A ordem dos objetos no array importa: sistema primeiro, depois usuário e, em seguida, quaisquer mensagens do assistente se você estiver continuando uma conversa.
5. Envie a requisição e analise a resposta
   Faça a requisição POST. A resposta contém um array choices com um objeto que possui um campo message. A resposta do assistente está em message.content.

Exemplo de Payload JSON

Abaixo está um payload JSON completo para uma chamada de API Perplexity com um system prompt. O system prompt instrui o modelo a responder em inglês simples e a fornecer citações sempre que possível.

{
  "model": "sonar-pro",
  "messages": [
    {
      "role": "system",
      "content": "Você é um assistente útil. Sempre responda em inglês simples e inclua citações de fontes confiáveis quando disponíveis."
    },
    {
      "role": "user",
      "content": "Qual é a capital da França?"
    }
  ]
}

Verificando se o System Prompt Foi Aplicado

Após receber a resposta, verifique se o comportamento do assistente corresponde ao seu system prompt. No exemplo acima, o modelo deve responder “Paris” e incluir uma citação de uma fonte de geografia ou governo. Se a resposta não seguir o prompt, revise a ordem do array messages. Um erro comum é colocar a mensagem do usuário antes da mensagem de sistema.

Erros Comuns ao Passar System Prompts

A API Retorna um Erro 400 Bad Request

Este erro geralmente significa que o payload JSON está malformado ou o array messages está vazio. Verifique se o array messages contém pelo menos um objeto e se cada objeto possui os campos role e content. Confirme também se o campo model está presente e escrito corretamente.

O System Prompt Não Tem Efeito na Saída

Se o modelo ignorar seu system prompt, verifique se a mensagem de sistema é o primeiro item no array messages. Se você colocar a mensagem do usuário primeiro, o modelo pode tratar o system prompt como uma instrução secundária ou ignorá-lo completamente. Certifique-se também de que o system prompt não seja muito longo — a API aceita prompts até o limite de contexto do modelo, que é tipicamente 200.000 tokens para sonar-pro.

System Prompt Sobrescreve a Intenção do Usuário

Um system prompt muito restritivo pode impedir o modelo de responder corretamente às perguntas do usuário. Por exemplo, se você definir um system prompt que diz “Responda apenas em uma palavra”, o modelo pode falhar ao fornecer respostas úteis para consultas complexas. Mantenha os system prompts claros e alinhados com as interações esperadas do usuário.

Comparação de Comportamento: API Perplexity com System Prompt vs Sem System Prompt

Item	Com System Prompt	Sem System Prompt
Estilo de resposta	Segue o tom e as regras que você define	Usa a persona padrão do assistente
Comportamento de citação	Pode ser forçado ou desabilitado via prompt	Pode citar fontes de forma inconsistente
Controle de idioma	Você pode definir um idioma específico	Responde no idioma da consulta do usuário
Imposição de papel	Funciona bem para tarefas específicas de domínio	Nenhuma imposição de papel

A tabela acima mostra as principais diferenças entre chamadas de API que incluem um system prompt e aquelas que não incluem. Para a maioria das aplicações em produção, um system prompt é recomendado para garantir um comportamento consistente e previsível do modelo.

Agora você pode passar system prompts em chamadas de API Perplexity colocando um objeto de mensagem com role system como o primeiro item no array messages. Teste seu payload com uma consulta de usuário simples antes de implantar em produção. Para casos de uso avançados, tente adicionar parâmetros como temperature ou max_tokens no mesmo corpo JSON para controlar ainda mais a saída do modelo. Lembre-se de que o system prompt não é criptografado em trânsito — evite incluir dados sensíveis, como senhas ou chaves de API, no conteúdo do prompt.