Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Filtraggio per dominio

Lezione 5 di 16 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. Controllo delle fonti di ricerca
  2. Due parametri mutualmente esclusivi
  3. Uso di allowed_domains (allowlist)
  4. Uso di excluded_domains (blocklist)
  5. Sintassi SDK
  6. Limiti e best practice
  7. Punti chiave

Controllo delle fonti di ricerca

Per impostazione predefinita, la Ricerca Web esplora l’intero web. Questo funziona bene per le query generiche, ma spesso non basta per casi d’uso professionali che richiedono fonti affidabili e controllate. Il filtraggio per dominio ti permette di limitare o escludere siti specifici.

Due parametri mutualmente esclusivi

La Ricerca Web offre due parametri di filtraggio:

  • allowed_domains: limita la ricerca ai domini specificati (allowlist)
  • excluded_domains: esclude domini specifici dai risultati (blocklist)

Questi due parametri sono mutualmente esclusivi. Non puoi usarli entrambi nella stessa richiesta. Se ci provi, l’API restituisce un errore.

Ogni parametro accetta un array di massimo 5 domini.

Uso di allowed_domains (allowlist)

Usa questo parametro quando sai esattamente quali fonti vuoi consultare. Ad esempio, per la ricerca accademica:

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What are the latest publications on transformers?",
    tools=[{
        "type": "web_search",
        "allowed_domains": ["arxiv.org", "nature.com", "science.org"]
    }]
)

Il modello cerca solo in questi tre domini. Questo garantisce che i risultati provengano da fonti scientifiche verificate.

Casi d’uso dell’allowlist

  • Ricerca accademica: limita ad arxiv.org, scholar.google.com, nature.com
  • Documentazione tecnica: limita ai siti ufficiali delle tecnologie
  • Intelligence competitiva: limita ai siti dei concorrenti
  • Conformità normativa: limita a fonti governative o di regolamentazione

Uso di excluded_domains (blocklist)

Usa questo parametro quando vuoi una ricerca ampia ma devi escludere fonti inaffidabili o irrilevanti:

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What are the best JavaScript frameworks in 2026?",
    tools=[{
        "type": "web_search",
        "excluded_domains": ["reddit.com", "quora.com"]
    }]
)

Il modello cerca in tutto il web tranne che nei domini esclusi.

Casi d’uso della blocklist

  • Escludere forum: evita opinioni non verificate
  • Escludere aggregatori: evita contenuti duplicati
  • Escludere concorrenti: tieni i loro contenuti fuori dai tuoi risultati
  • Escludere paywall: evita siti con contenuti inaccessibili

Sintassi 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"]
})]

Nota la convenzione camelCase (allowedDomains) nell’SDK JavaScript.

Limiti e best practice

Il limite di 5 domini potrebbe sembrare restrittivo. In pratica, ti costringe a essere selettivo sulle fonti, il che migliora la qualità dei risultati. Se hai bisogno di più flessibilità, puoi eseguire più richieste con domini diversi e aggregare i risultati lato client.

Quando usi allowed_domains, assicurati che i domini scelti coprano l’argomento richiesto. Un dominio troppo restrittivo potrebbe impedire al modello di trovare informazioni rilevanti, portandolo a rispondere senza dati aggiornati.

Punti chiave

  • Due parametri disponibili: allowed_domains (allowlist) e excluded_domains (blocklist)
  • Mutualmente esclusivi: non puoi combinarli nella stessa richiesta
  • Massimo 5 domini per parametro
  • L’allowlist è ideale per fonti controllate e affidabili
  • La blocklist funziona per ricerche ampie con poche esclusioni