Filtro de Domínio da API Perplexity Retorna Zero Resultados: Causa

Quando você aplica um filtro de domínio na API Perplexity, a resposta pode retornar zero resultados mesmo sabendo que existe conteúdo relevante no site especificado. Isso geralmente acontece porque a API aplica um escopo de busca combinado que trata o filtro de domínio como uma restrição secundária, não como um operador de consulta primário. Neste artigo, você aprenderá a causa técnica exata desse comportamento e como ajustar suas chamadas de API para obter os resultados esperados.

Por que o Filtro de Domínio da API Perplexity Retorna Zero Resultados

A API Perplexity usa uma arquitetura de busca em dois estágios. Primeiro, ela consulta um índice web geral. Depois, aplica o filtro de domínio como uma etapa de pós-processamento nos documentos recuperados. Quando a consulta inicial ao índice não retorna documentos suficientes do domínio especificado, o filtro remove todos os resultados, deixando você com um conjunto vazio.

A causa raiz é que o parâmetro search_domain não força a API a priorizar conteúdo desse domínio. Em vez disso, ele atua como um filtro rígido após a recuperação. Se o índice retornar menos de, por exemplo, três documentos do domínio alvo, a API descarta todos eles porque não consegue formar uma resposta coerente a partir de uma amostra tão pequena.

Além disso, a API possui um mecanismo interno de deduplicação e pontuação de relevância. Documentos do mesmo domínio geralmente são classificados mais baixo se a consulta não mencionar explicitamente o nome do domínio. Isso significa que, mesmo que o domínio tenha páginas relevantes, elas podem ser superadas por resultados web gerais e nunca chegar ao estágio de filtro.

Passos para Diagnosticar e Corrigir o Problema do Filtro de Domínio

Para resolver o problema de resultados vazios, você precisa ajustar a estrutura da sua requisição à API e testar com diferentes combinações de parâmetros. Siga estes passos em ordem.

Método 1: Use o Operador site: Dentro da String de Consulta

1. Remova o parâmetro search_domain
   Exclua ou comente o campo search_domain do corpo da sua requisição à API. Este parâmetro é a causa mais comum de resultados vazios porque aplica um pós-filtro rigoroso.
2. Adicione site:exemplo.com à sua string de consulta
   Adicione o operador site: à sua consulta. Por exemplo, altere "query": "últimas pesquisas em IA" para "query": "site:arxiv.org últimas pesquisas em IA". Isso instrui o índice a priorizar conteúdo desse domínio durante a recuperação.
3. Aumente o parâmetro max_results
   Defina max_results para um valor maior, como 10 ou 15. O valor padrão geralmente é 5, que pode ser muito baixo para consultas restritas a domínio. Um valor maior fornece mais documentos para a API trabalhar antes de aplicar a pontuação de relevância.
4. Teste primeiro com uma consulta ampla
   Envie uma requisição sem nenhum filtro de domínio para confirmar que a API consegue recuperar resultados para o seu tópico. Se você obtiver zero resultados mesmo sem o filtro, o problema está na própria consulta, não no parâmetro de domínio.

Método 2: Combine search_domain com Domínio Explícito na Consulta

1. Mantenha search_domain definido para o domínio alvo
   Na sua requisição à API, defina "search_domain": "exemplo.com". Este parâmetro ainda aplica o pós-filtro, mas você compensará com o próximo passo.
2. Adicione o nome do domínio como uma palavra-chave na consulta
   Inclua o nome do domínio ou uma parte reconhecível dele na string de consulta. Por exemplo, se você está pesquisando documentação da Microsoft, use "query": "Microsoft docs Azure setup". Isso direciona o índice a recuperar documentos que mencionam o domínio.
3. Defina recency como "day" ou "week"
   Use o parâmetro recency para limitar os resultados a conteúdo recente. Isso pode ajudar se o domínio tiver muitas páginas antigas que o índice classifica como baixas. A API então focará em documentos mais novos e relevantes desse domínio.
4. Verifique os metadados usage na resposta da API
   Inspecione o objeto usage na resposta da API. Ele mostra quantos documentos foram recuperados e quantos foram filtrados. Se filtered_count for alto e result_count for zero, você sabe que o filtro de domínio está muito agressivo.

Se o Filtro de Domínio Ainda Retornar Nenhum Resultado

API Retorna Array Vazio para Todos os Filtros de Domínio

Se você testar vários domínios e todos retornarem zero resultados, o problema provavelmente está na sua chave de API ou no endpoint que você está usando. Verifique se sua chave de API tem acesso ao endpoint /search e se você não está atingindo um limite de taxa. Verifique o código de status HTTP: um status 429 significa que você excedeu sua cota. Aguarde o período de redefinição ou faça upgrade do seu plano.

Outra possibilidade é que o modelo de API selecionado não suporta filtragem de domínio. O modelo sonar-pro suporta, mas o modelo sonar-small pode não suportar. Mude para sonar-pro ou sonar-medium e teste novamente.

Filtro de Domínio Funciona na Interface Web, mas Não na API

A interface web do Perplexity usa um pipeline de busca diferente da API. A interface web aplica o filtro de domínio durante o estágio de planejamento da consulta, enquanto a API aplica após a recuperação. Essa diferença arquitetônica significa que o mesmo filtro pode se comportar de maneira diferente. Para imitar o comportamento da interface web, use o operador site: dentro da string de consulta, conforme mostrado no Método 1 acima.

Você também pode tentar definir o parâmetro "focus": "web" na requisição à API. Isso instrui a API a usar o índice web geral em vez de uma base de conhecimento especializada, o que geralmente retorna mais resultados filtrados por domínio.

Métodos de Filtro de Domínio da API Perplexity: search_domain vs Operador site:

Item	Parâmetro search_domain	Operador site: na Consulta
Método de filtragem	Filtro rígido pós-recuperação	Modificador de consulta no nível do índice
Efeito na recuperação	Não influencia quais documentos são inicialmente recuperados	Força o índice a priorizar documentos do domínio especificado
Risco de resultados vazios	Alto se o domínio tiver baixa cobertura no índice	Baixo, porque o índice busca ativamente conteúdo do domínio
Compatibilidade com outros filtros	Pode ser combinado com recency e max_results	Funciona com qualquer parâmetro de consulta, mas pode conflitar com search_domain

Agora você pode diagnosticar e corrigir o problema do filtro de domínio da API Perplexity trocando o parâmetro search_domain pelo operador site: dentro da sua string de consulta. Teste sua chamada de API primeiro com uma consulta ampla e, em seguida, adicione gradualmente a restrição de domínio. Para resultados vazios persistentes, verifique as permissões da sua chave de API e a seleção do modelo. Como dica avançada, use os metadados usage na resposta da API para monitorar quantos documentos são filtrados e ajuste o valor de max_results de acordo.