Filtraggio per dominio
In questa pagina
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) eexcluded_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