Como Restringir a API do Perplexity a Domínios Específicos

Você quer que a API do Perplexity pesquise ou recupere dados apenas de sites específicos, não de toda a internet. Isso é útil para bases de conhecimento internas, fontes de notícias confiáveis ou conjuntos de conteúdo curados. A API do Perplexity não oferece um filtro de lista de permissões de domínio integrado como alguns mecanismos de busca. Este artigo explica como alcançar a restrição de domínio combinando a API com um script Python personalizado que valida as fontes antes de retornar os resultados.

Por que a API do Perplexity Não Tem um Filtro de Domínio Integrado

A API do Perplexity foi projetada como um mecanismo de busca e resposta de uso geral. Ela retorna as fontes mais relevantes de toda a web com base na sua consulta. A API não inclui um parâmetro como site:exemplo.com que você possa passar no corpo da requisição. Esta é uma escolha de design deliberada para manter a simplicidade e a utilidade ampla.

No entanto, muitos casos de uso empresariais exigem restringir os resultados a domínios específicos. Por exemplo, uma ferramenta de pesquisa jurídica pode querer apenas resultados de sites governamentais. Um bot de suporte ao cliente pode querer apenas resultados da central de ajuda da sua empresa. Sem um filtro nativo, você deve implementar a restrição de domínio no lado do cliente. Isso significa que você escreve código que recebe a resposta da API, inspeciona as URLs das fontes e descarta aquelas que não correspondem à sua lista de permitidos.

O Que Você Precisa Antes de Começar

Você precisa de uma chave de API do Perplexity com uma assinatura ativa. Você precisa do Python 3.7 ou superior instalado em sua máquina. Você precisa da biblioteca requests. Instale-a com pip install requests. Você também precisa de uma lista de domínios permitidos. Escreva-os exatamente como aparecem nas URLs, como exemplo.com ou suporte.microsoft.com. Não inclua o protocolo ou a barra final.

Passos para Construir um Script Python que Filtra Resultados da API por Domínio

Os passos a seguir criam um script que envia uma consulta para a API do Perplexity, recebe a resposta e mantém apenas os resultados cujo domínio está na sua lista de permitidos.

1. Crie um novo arquivo Python
   Abra seu editor de código e crie um arquivo chamado perplexity_domain_filter.py.
2. Importe as bibliotecas necessárias
   Adicione import requests e from urllib.parse import urlparse no topo do arquivo.
3. Defina seus domínios permitidos
   Crie um conjunto Python com os domínios exatos que você permite. Exemplo: DOMINIOS_PERMITIDOS = {"wikipedia.org", "bbc.com", "reuters.com"}
4. Defina sua chave de API e endpoint
   Defina CHAVE_API = "sua-chave-aqui" e URL_API = "https://api.perplexity.ai/search". Substitua sua-chave-aqui pela sua chave real.
5. Defina a função de busca
   Crie uma função chamada buscar_perplexity(consulta). Dentro dela, construa os cabeçalhos e o payload da requisição. Os cabeçalhos devem incluir "Authorization": f"Bearer {CHAVE_API}" e "Content-Type": "application/json". O payload deve ser um dicionário Python com pelo menos a chave "query" definida como a string de consulta.
6. Envie a requisição e analise a resposta
   Use requests.post(URL_API, headers=cabecalhos, json=payload). Verifique se response.status_code == 200. Analise o JSON com dados = response.json().
7. Extraia as fontes da resposta
   A resposta da API normalmente contém uma chave como "sources" ou "results". Itere sobre cada item de fonte. Para cada fonte, extraia a URL usando fonte.get("url", "").
8. Analise o domínio de cada URL
   Use analisado = urlparse(url) para obter o netloc. Em seguida, extraia o domínio com dominio = analisado.netloc.lower(). Remova qualquer prefixo www. se presente.
9. Verifique o domínio contra sua lista de permitidos
   Escreva uma instrução if: if dominio in DOMINIOS_PERMITIDOS:. Se verdadeiro, adicione a fonte a uma nova lista chamada fontes_filtradas. Se falso, pule a fonte.
10. Retorne apenas os resultados filtrados
    Após o loop, retorne ou imprima fontes_filtradas. Seu script agora retorna apenas resultados dos seus domínios permitidos.

Exemplo de Script Completo

Aqui está o script completo que você pode copiar e adaptar:

import requests
from urllib.parse import urlparse

DOMINIOS_PERMITIDOS = {"wikipedia.org", "bbc.com", "reuters.com"}
CHAVE_API = "sua-chave-de-api-aqui"
URL_API = "https://api.perplexity.ai/search"

def buscar_perplexity(consulta):
    cabecalhos = {
        "Authorization": f"Bearer {CHAVE_API}",
        "Content-Type": "application/json"
    }
    payload = {
        "query": consulta,
        "model": "sonar-pro"
    }
    resposta = requests.post(URL_API, headers=cabecalhos, json=payload)
    if resposta.status_code != 200:
        return []
    dados = resposta.json()
    fontes = dados.get("sources", [])
    filtradas = []
    for fonte in fontes:
        url = fonte.get("url", "")
        if not url:
            continue
        analisado = urlparse(url)
        dominio = analisado.netloc.lower()
        if dominio.startswith("www."):
            dominio = dominio[4:]
        if dominio in DOMINIOS_PERMITIDOS:
            filtradas.append(fonte)
    return filtradas

resultados = buscar_perplexity("últimas notícias de tecnologia")
print(resultados)

Problemas Comuns com Filtragem de Domínio e Suas Soluções

A Resposta da API Não Inclui URLs

Alguns endpoints da API do Perplexity retornam apenas um texto de resposta sem uma lista separada de fontes. Verifique a documentação da sua API para confirmar que você está usando um endpoint que retorna URLs de fontes. Caso contrário, mude para o endpoint /search ou o endpoint /chat/completions com citações de fontes habilitadas.

Incompatibilidades de Subdomínio

Se você permitir exemplo.com mas o resultado vier de blog.exemplo.com, a verificação estrita o rejeitará. Para incluir todos os subdomínios, modifique a verificação para ver se o domínio termina com .exemplo.com ou é igual a exemplo.com. Use if dominio == PERMITIDO or dominio.endswith("." + PERMITIDO).

Limites de Taxa e Cotas

A filtragem no lado do cliente não reduz o número de chamadas de API. Você ainda paga por cada consulta, mesmo que a maioria dos resultados seja descartada. Para economizar custos, considere pré-filtrar sua consulta incluindo dicas de domínio no texto da consulta. Por exemplo, inclua site:nature.com na string de consulta. Isso não é garantido de funcionar, mas pode reduzir resultados irrelevantes.

Item	Filtragem no Lado do Cliente	Dicas no Nível da Consulta
Confiabilidade	Sempre funciona	Pode ser ignorado pela API
Custo	Custo total da chamada de API	Mesmo custo, mas menos resultados descartados
Esforço de implementação	Médio, requer código Python	Baixo, apenas modificar a string de consulta
Flexibilidade	Alta, suporta qualquer lista de domínios	Baixa, depende do comportamento da API

Agora você pode restringir os resultados da API do Perplexity a qualquer conjunto de domínios usando um script Python curto. Em seguida, considere adicionar uma camada de cache para evitar chamadas repetidas de API para a mesma consulta. Uma dica avançada é usar um filtro Bloom para listas de permissões de domínio muito grandes para manter o uso de memória baixo.