API Perplexity Sonar Não Retorna Citações: Solução

Ao chamar o modelo Sonar da Perplexity pela API, você espera que a resposta inclua citações mostrando as fontes da informação. Em vez disso, a resposta pode conter apenas o texto da resposta com um array de citações vazio ou nenhum campo de citações. Esse problema geralmente ocorre porque a requisição da API está faltando o parâmetro necessário que ativa a geração de citações para o modelo Sonar. Este artigo explica a causa raiz das citações ausentes e fornece as etapas exatas para incluir citações em toda resposta da API Sonar.

Por que a API Sonar Retorna Respostas Sem Citações

O modelo Sonar da API Perplexity é projetado para gerar respostas baseadas em resultados de pesquisa web em tempo real. Por padrão, a resposta da API inclui apenas o texto gerado no array choices. O modelo não anexa citações automaticamente porque a API trata a geração de citações como um recurso opcional controlado por parâmetros de requisição.

Quando você omite o parâmetro return_citations da sua requisição à API, o servidor assume que você não deseja citações. Esta é a causa mais comum de citações ausentes. Outras causas incluem usar um endpoint de API mais antigo que não suporta citações ou enviar o parâmetro com um tipo de valor incorreto. O modelo Sonar suporta citações apenas quando você as solicita explicitamente.

Entendendo o Parâmetro return_citations

O parâmetro return_citations é um valor booleano que você deve incluir no corpo JSON da sua requisição POST para o endpoint /sonar/chat/completions. Quando definido como true, a API retorna um array citations no objeto de resposta. Cada elemento do array é uma string de URL apontando para a fonte usada para gerar a resposta.

O modelo Sonar também suporta o parâmetro return_related_questions. Embora esse parâmetro não afete as citações, muitos desenvolvedores incluem ambos os parâmetros juntos para obter uma resposta abrangente.

Passos para Corrigir Citações Ausentes na Resposta da API Sonar

Siga estas etapas para modificar sua requisição à API e garantir que o modelo Sonar retorne citações com cada resposta.

1. Verifique se Você Está Usando o Endpoint Correto
   Envie sua requisição para https://api.perplexity.ai/sonar/chat/completions. Usar um endpoint diferente, como o endpoint geral de chat completions, pode não suportar os parâmetros de citação. Verifique seu código e confirme se a URL é exatamente https://api.perplexity.ai/sonar/chat/completions.
2. Adicione o Parâmetro return_citations ao Corpo da Requisição
   No corpo JSON da sua requisição, inclua a chave return_citations com o valor true. Exemplo de corpo:
   { "model": "sonar", "messages": [{"role": "user", "content": "Qual é a capital da França?"}], "return_citations": true }. Não use valores string como "true"; use o booleano true sem aspas.
3. Opcionalmente, Adicione o Parâmetro return_related_questions
   Inclua "return_related_questions": true no mesmo corpo da requisição. Este parâmetro adiciona um array related_questions à resposta. Embora não seja necessário para citações, é comumente usado junto com as citações.
4. Envie a Requisição e Inspecione a Resposta
   Execute a requisição. O objeto de resposta agora deve conter uma chave citations no nível superior. O valor é um array de URLs. Exemplo de trecho de resposta:
   { "id": "...", "citations": ["https://exemplo.com/fonte1", "https://exemplo.com/fonte2"], "choices": [...] }. Se o array citations estiver vazio, o modelo não conseguiu encontrar fontes verificáveis para a resposta.
5. Teste com uma Consulta Conhecida e Verificável
   Use uma consulta factual como “Qual é a população de Tóquio?” para confirmar se as citações aparecem. Essa consulta tem muitas fontes confiáveis, então o modelo deve retornar pelo menos uma citação. Se as citações ainda não aparecerem, verifique novamente a ortografia do nome do parâmetro e o tipo de dado.

Se a API Sonar Ainda Omitir Citações Após Aplicar a Correção

Array de Citações Vazio Apesar de Definir return_citations como true

Um array citations vazio significa que o modelo não conseguiu encontrar fontes verificáveis para a resposta. Isso pode acontecer com perguntas altamente especulativas, eventos muito recentes ainda não indexados pelos mecanismos de busca ou consultas que o modelo responde a partir de seus dados de treinamento em vez de uma pesquisa ao vivo. Para contornar essa limitação, reformule a consulta para ser mais específica ou para pedir dados atuais. Por exemplo, em vez de “Quais são as últimas notícias?”, pergunte “Quais são as últimas notícias sobre o rover Perseverance em Marte em outubro de 2023?”

A API Retorna um Erro Quando return_citations é Incluído

Se a API retornar um erro 400 ou um erro de requisição inválida, o parâmetro pode estar com erro de digitação ou definido com um tipo incorreto. Verifique se a chave é exatamente return_citations sem erros de digitação. Certifique-se de que o valor é o booleano true e não a string "true". Confirme também se o corpo da sua requisição é um JSON válido. Use um validador JSON para verificar o corpo antes de enviar.

Citações Aparecem, mas Estão Incompletas ou Incorretas

O modelo Sonar retorna citações com base nas fontes que usou durante a geração. Se uma URL de citação estiver quebrada ou apontar para uma página que não contém a informação citada, o modelo pode ter extraído um trecho incorretamente. Esta é uma limitação conhecida do modelo Sonar. Para melhorar a precisão das citações, faça perguntas mais precisas que correspondam a conteúdo bem indexado. Por exemplo, inclua o ano ou terminologia específica em sua consulta.

API Sonar da Perplexity Com Citações vs Sem Citações

Item	Com return_citations: true	Sem return_citations
Resposta inclui array de citações	Sim	Não
Tamanho da resposta	Maior devido às URLs	Menor
Verificabilidade da fonte	Alta	Baixa
Latência da API	Ligeiramente maior	Padrão
Caso de uso ideal	Pesquisa, verificação de fatos, trabalho acadêmico	Respostas rápidas, ferramentas internas

Após adicionar o parâmetro return_citations às suas requisições da API Sonar, você pode recuperar consistentemente URLs de fontes junto com a resposta gerada. Esse recurso é essencial para aplicações que exigem informações rastreáveis, como assistentes de pesquisa, ferramentas de verificação de conteúdo e plataformas educacionais. Para melhores resultados, sempre combine o parâmetro de citação com uma consulta bem formulada e valide as URLs retornadas na lógica da sua aplicação.