Filtrage par domaines

Contrôler les sources de recherche

Par défaut, Web Search explore l’ensemble du web. C’est parfait pour des recherches générales, mais souvent insuffisant pour des cas d’usage professionnels où vous avez besoin de sources fiables et contrôlées. Le filtrage par domaines vous permet de restreindre ou d’exclure des sites spécifiques.

Deux paramètres mutuellement exclusifs

Web Search propose deux paramètres de filtrage :

• allowed_domains : limite la recherche aux domaines spécifiés (liste blanche)
• excluded_domains : exclut certains domaines des résultats (liste noire)

Ces deux paramètres sont mutuellement exclusifs. Vous ne pouvez pas utiliser les deux en même temps dans une même requête. Si vous essayez, l’API retournera une erreur.

Chaque paramètre accepte un tableau de 5 domaines maximum.

Utiliser allowed_domains (liste blanche)

Ce paramètre est idéal quand vous savez exactement quelles sources vous voulez consulter. Par exemple, pour une recherche académique :

response = client.responses.create(
    model="grok-4.20-reasoning",
    input="Quelles sont les dernières publications sur les transformers ?",
    tools=[{
        "type": "web_search",
        "allowed_domains": ["arxiv.org", "nature.com", "science.org"]
    }]
)

Le modèle ne recherchera que sur ces trois domaines. Cela garantit que les résultats proviennent de sources scientifiques vérifiées.

Cas d’usage de la liste blanche

• Recherche académique : limiter à arxiv.org, scholar.google.com, nature.com
• Documentation technique : limiter aux sites officiels des technologies utilisées
• Veille concurrentielle : limiter aux sites de vos concurrents
• Conformité réglementaire : limiter aux sources gouvernementales ou réglementaires

Utiliser excluded_domains (liste noire)

Ce paramètre est utile quand vous voulez une recherche large mais souhaitez exclure certaines sources peu fiables ou non pertinentes :

response = client.responses.create(
    model="grok-4.20-reasoning",
    input="Quels sont les meilleurs frameworks JavaScript en 2026 ?",
    tools=[{
        "type": "web_search",
        "excluded_domains": ["reddit.com", "quora.com"]
    }]
)

Le modèle recherchera sur tout le web sauf les domaines exclus.

Cas d’usage de la liste noire

• Exclure les forums : éviter les opinions non vérifiées
• Exclure les agrégateurs : éviter les contenus dupliqués
• Exclure les concurrents : ne pas inclure leurs contenus dans vos résultats
• Exclure les paywall : éviter les sites dont le contenu est inaccessible

Syntaxe par SDK

xAI SDK

tools=[client.tools.web_search(
    allowed_domains=["arxiv.org", "nature.com"]
)]

OpenAI SDK

tools=[{
    "type": "web_search",
    "excluded_domains": ["reddit.com"]
}]

Vercel AI SDK

tools: [xai.tools.webSearch({
  allowedDomains: ["arxiv.org", "nature.com"]
})]

Notez la convention camelCase (allowedDomains) dans le SDK JavaScript.

Limites et bonnes pratiques

La limite de 5 domaines peut sembler restrictive. En pratique, elle pousse à être sélectif dans le choix des sources, ce qui améliore la qualité des résultats. Si vous avez besoin de plus de flexibilité, vous pouvez effectuer plusieurs requêtes avec des domaines différents et agréger les résultats côté client.

Lorsque vous utilisez allowed_domains, assurez-vous que les domaines choisis couvrent bien le sujet demandé. Un domaine trop restrictif peut empêcher le modèle de trouver des informations pertinentes, ce qui pourrait le pousser à répondre sans données actualisées.

Points clés à retenir

• Deux paramètres disponibles : allowed_domains (liste blanche) et excluded_domains (liste noire)
• Mutuellement exclusifs : impossible de les combiner dans une même requête
• Maximum 5 domaines par paramètre
• La liste blanche est idéale pour des sources contrôlées et fiables
• La liste noire convient pour des recherches larges avec quelques exclusions